Fleet Engine propose un service de journalisation simple qui vous permet d'enregistrer ses requêtes API et les charges utiles de ses réponses. Ces journaux vous permettent de déboguer votre intégration, de créer des métriques de surveillance et d'analyser les modèles de trafic.
Fleet Engine envoie les journaux sous forme de journaux de plate-forme à Cloud Logging. Vous pouvez ainsi utiliser les outils Cloud Logging pour y accéder.
Informations consignées par Fleet Engine
Fleet Engine envoie plusieurs informations à Cloud Logging, telles que:
- Toutes les requêtes et réponses REST et gRPC authentifiées
- Réponses d'erreur
- Requêtes, réponses et messages d'erreur des appels initiés par le SDK Driver à Fleet Engine.
- Divisez les journaux en fonction des types de journaux compatibles :
Consultez la documentation pour connaître les messages de journal et le schéma disponibles dans la documentation de référence de Logging.
Utilisez des buckets de journaux restreints et par défaut pour respecter les règles de conservation des données
L'utilisation de buckets "limités" et "default" garantit une image claire de votre consommation de données, qu'elle soit restreinte ou non. Certaines données de journaux que Fleet Engine envoie à Google Maps Platform ne peuvent être conservées que pendant une période limitée, conformément aux Conditions spécifiques du service de mobilité. Pour vous assurer de ne conserver des données restreintes que pendant la durée autorisée, vous devez les étiqueter avec la mention TOS_RESTRICTED (Fleet Engine le fait déjà) et les enregistrer dans un bucket dédié appelé "restricted".
Vous pouvez alors contrôler leur durée de conservation et les supprimer automatiquement à l'expiration à l'aide des paramètres Cloud Logging. Par exemple, les journaux à utilisation limitée ne doivent être conservés que pendant 30 jours.
Consignez toutes les données non restreintes restantes dans le bucket "par défaut", où elles peuvent être conservées plus longtemps, telles que définies dans les Conditions spécifiques aux services de mobilité (généralement pendant un an). L'utilisation de buckets "restricted" et "default" garantit une image claire de votre consommation de données restreinte et non restreinte.
Envoyez toutes les données de journaux non restreintes restantes dans le bucket "default" (par défaut), où elles peuvent être conservées indéfiniment.
Obtenez une vue complète en fusionnant les journaux restreints et non restreints
Les journaux à utilisation limitée contiennent ces données, ainsi qu'une référence au journal par défaut afin de pouvoir les considérer ensemble. Le journal à usage limité contient l'identifiant insertId du journal par défaut comme référence dans le champ parent_insert_id. Vous pouvez utiliser ce champ pour joindre les données des deux journaux et obtenir une vue d'ensemble complète.
Consultez la documentation pour connaître tous les messages de journal et schémas disponibles dans la documentation de référence de Logging.
Activer Cloud Logging
Fleet Engine active automatiquement les journaux par défaut pour les nouveaux clients Mobility, à partir des projets créés le 10 février 2022. Vous pouvez vérifier si la journalisation est activée en exécutant la requête suivante dans l'Explorateur de journaux :
resource.type:"fleetengine.googleapis.com"
Si aucun journal ne s'affiche pour cette requête, il est possible que Cloud Logging n'ait pas été activé pour votre projet. Contactez l'assistance si vous souhaitez activer cette fonctionnalité.
Activer les journaux à utilisation limitée
Les journaux à usage limité sont activés sur demande. Pour activer ces journaux pour votre projet Google Cloud, procédez comme suit:
Préparer votre projet pour recevoir des journaux à usage restreint
- Dans la console Google Cloud, ouvrez la page du routeur de journaux.
- Mettez à jour le bucket de journalisation _Default pour exclure les journaux à utilisation limitée.
- Sélectionnez le bucket de journalisation _Default, puis cliquez sur Modifier le récepteur.
- Dans la section "Sélectionner les journaux à exclure du récepteur", cliquez sur le bouton "Ajouter une exclusion" :
- Nom du filtre d'exclusion: ExcludeRestrictedLogs
- Filtre d'exclusion: labels.restriction="TOS_RESTRICTED"
- Cliquez sur "Mettre à jour le récepteur".
- Mettez à jour le bucket de journalisation restreinte pour stocker les journaux à utilisation limitée.
- Sur la page "Routeur de journaux", sélectionnez "Créer un récepteur".
- Créez un récepteur avec les paramètres suivants :
- Détails du récepteur :
- Nom: RestrictedLogs
- Description: journaux à usage restreint de Routes Fleet Engine
- Destination du récepteur :
- Service du récepteur: bucket Logging
- Sélectionnez un bucket de journaux : "Créer un bucket de journaux".
- Nom: Limité
- Description: contient les journaux à usage limité Fleet Engine
- Durée de conservation: 30 jours
- Remarque: La durée de conservation ne doit pas dépasser 30 jours.
- Journaux à inclure dans le récepteur: laissez ce champ vide
- Journaux à exclure du récepteur: cliquez sur "Ajouter une exclusion"
- Nom du filtre d'exclusion: ExcludeNonRestrictedLogs
- Filtre d'exclusion: NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliveryFleet") NOT (labels.restriction = "TOS_RESTRICTED")
- Cliquez sur "Créer un récepteur".
- Détails du récepteur :
Contactez l'assistance pour activer les journaux à utilisation limitée
Ensuite, contactez l'assistance et indiquez les informations suivantes dans votre demande:
- ID des projets à activer:
- Adresse e-mail de la personne à l'origine de la demande de modification :
- Remarque: Cette personne doit disposer d'un accès en modification aux projets Google Cloud répertoriés.
- En activant l'utilisation limitée du contenu Google Maps dans Cloud Logging, vous acceptez de respecter les Conditions d'utilisation de Google Maps Platform et les Conditions spécifiques au service de mobilité, y compris les conditions relatives à la mise en cache et aux utilisations autorisées qui s'appliquent au contenu Google Maps. Oui/Non
Lorsque l'équipe d'assistance reçoit votre demande, elle vous envoie une confirmation indiquant que la journalisation a été activée pour votre projet.
Diviser les journaux cloud
Cloud Logging limite la taille des journaux entrants à 256 Ko. Le service supprime les journaux au-delà de ce seuil. Pour s'assurer que Cloud Logging conserve les journaux volumineux, Fleet Engine peut les diviser en une série de journaux inférieurs au seuil de 256 Ko. Ces journaux ont un préfixe insertId commun pour indiquer l'ordre dans lequel le service a divisé le journal le plus petit du journal d'origine surdimensionné. Vous pouvez ensuite les réassocier en fonction de leur insertId.
Pour accéder au journal non fractionné d'origine, fusionnez les journaux fractionnés en fonction de leurs ID insertId dans l'ordre d'origine dans lequel ils ont été fractionnés, comme indiqué par leur index dans l'entrée de journal cloud.
La structure du journal fractionné est identique à celle mentionnée dans le guide des entrées de journaux d'audit fractionnés pour Cloud Audit Logs. La principale différence avec les journaux fractionnés dans la journalisation de parc est que la répartition se fait dans le champ jsonPayload, et non dans le champ protoPayload. Consultez l'exemple de fractionnement présenté dans la section suivante.
Types de journaux compatibles
Fleet Engine n'accepte la division des journaux que pour les types de journaux suivants dont la taille dépasse 256 Ko:
Exemple de structure de journal fractionné
// First Split Log
{
// insertId appended with an increasing number
"insertId": "ABCDE-1",
"jsonPayload": {
"response": {
"matches": [
{
// ...
"vehicle": {
"name": "providers/test-123/vehicles/test-vehicle-0",
// ...
}
},
{
// ...
"vehicle": {
"name": "providers/test-123/vehicles/test-vehicle-1",
// ...
}
}
]
},
"@type": "type.googleapis.com/maps.fleetengine.v1.SearchVehiclesLog",
"request": {
"searchTripTypes": [
"EXCLUSIVE_TRIP"
],
"pickupPoint": {},
"count": 50,
"pickupRadiusMeters": 400,
"minimumCapacity": 1,
"matchOrderBy": "PICKUP_POINT_ETA",
"vehicleTypes": [
{
"vehicleCategory": "TAXI"
}
]
}
},
"resource": {
"type": "fleetengine.googleapis.com/Fleet",
"labels": {
"resource_container": "projects/test-123",
"location": "global"
}
},
// Same timestamp
"timestamp": "2024-02-06T22:48:50.620713Z",
"logName": "projects/test-123/logs/fleetengine.googleapis.com%2Fsearch_vehicles",
"receiveTimestamp": "2024-02-06T22:48:52.006308491Z",
"split": {
// UID for this logical log entry (same across splits)
"uid": "ABCDE",
"totalSplits": 2
}
}
// Second Split Log
{
// insertId appended with an increasing number
"insertId": "ABCDE-2",
"jsonPayload": {
"response": {
"matches": [
{},{} // Previous matches appear as empty objects
{
// ...
"vehicle": {
"name": "providers/test-123/vehicles/test-vehicle-2",
// ...
},
}
]
},
"@type": "type.googleapis.com/maps.fleetengine.v1.SearchVehiclesLog",
"request": {
"searchTripTypes": [
"EXCLUSIVE_TRIP"
],
"pickupPoint": {},
"count": 50,
"pickupRadiusMeters": 400,
"minimumCapacity": 1,
"matchOrderBy": "PICKUP_POINT_ETA",
"vehicleTypes": [
{
"vehicleCategory": "TAXI"
}
]
}
},
"resource": {
"type": "fleetengine.googleapis.com/Fleet",
"labels": {
"resource_container": "projects/test-123",
"location": "global"
}
},
// Same timestamp
"timestamp": "2024-02-06T22:48:50.620713Z",
"logName": "projects/test-123/logs/fleetengine.googleapis.com%2Fsearch_vehicles",
"receiveTimestamp": "2024-02-06T22:48:52.006308491Z",
"split": {
// UID for this logical log entry (same across splits)
"uid": "ABCDE",
// Subsequent logs after the original will have a zero based index
"index": 1,
"totalSplits": 2
}
}
Accéder à vos journaux
Les journaux Cloud sont structurés autour du format LogEntry. Fleet Engine envoie des journaux à Cloud Logging avec le paramètre resource.type de LogEntry défini sur fleetengine.googleapis.com. Vous pouvez utiliser l'explorateur de journaux pour écrire des requêtes permettant d'afficher les journaux.
Par exemple, pour afficher tous les RPC vers Fleet Engine qui ont renvoyé une erreur, utilisez la requête suivante de l'Explorateur de journaux:
resource.type:"fleetengine.googleapis.com"
severity=ERROR
Pour afficher les journaux des RPC effectués dans la méthode UpdateVehicle pour le projet example-project-id, utilisez la requête suivante de l'explorateur de journaux:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle"
L'exemple suivant montre une entrée LogEntry pour le journal UpdateVehicle. La requête et la réponse RPC se trouvent dans le champ jsonPayload:
{
"insertId": "c6b85fbc927343fc8a85338c57a65733",
"jsonPayload": {
"request": {
"header": {4},
"updateMask": "deviceSettings",
"vehicleId": "uniqueVehicleId",
"vehicle": {2}
},
"response": {
"name": "providers/example-project-id/vehicles/uniqueVehicleId",
"availableCapacity": 2,
"state": "VEHICLE_STATE_OFFLINE",
"maximumCapacity": 2,
"vehicleType": {1},
"supportedTrips": {1}
},
"@type": "type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
},
"resource": {
"type": "fleetengine.googleapis.com/Fleet",
"labels": {2}
},
"timestamp": "2021-01-01T00:00:00.000000000Z",
"labels": {2},
"logName": "projects/example-project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle",
"receiveTimestamp": "2021-01-01T00:00:00.000000000Z"
}
Si une erreur RPC est renvoyée, le champ responseVehicle est effacé, et le champ errorResponse est défini et renseigné dans jsonPayload:
{
"insertId": "c6b85fbc927343fc8a85338c57a65733",
"jsonPayload": {
"errorResponse": {
"httpStatusCode": 404,
"code": "NOT_FOUND",
"message": "No entity with id invalidVehicleId exists"
},
"@type": "type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog",
"request": {
"vehicle": {3},
"updateMask": "deviceSettings",
"vehicleId": "fakeVehicleId",
"header": {4}
}
},
"resource": {
"type": "fleetengine.googleapis.com/Fleet",
"labels": {2}
},
"timestamp": "2021-01-01T00:00:00.000000000Z",
"severity": "ERROR",
"labels": {2}
"logName": "projects/example-project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle",
"receiveTimestamp": "2021-01-01T00:00:00.000000000Z"
}
Pour en savoir plus sur le langage de requête Logging, consultez la page Langage de requête Logging . Pour savoir comment créer des métriques à l'aide de vos journaux, consultez la page Présentation des métriques basées sur les journaux.
Gérer les coûts de journalisation
Une fois la journalisation activée, vous êtes responsable de la configuration de l'acheminement, du stockage et de la conservation des journaux. Des frais Google Cloud supplémentaires peuvent vous être facturés pour l'ingestion et la conservation des journaux si vous dépassez sans frais les limites d'utilisation et de conservation. Cependant, vous pouvez contrôler les coûts de journalisation en effectuant l'une des opérations suivantes:
Réduire l'utilisation de la journalisation
Vous pouvez limiter la quantité de données de journaux ingérées en excluant certaines entrées de journal.
Exporter ou acheminer les journaux
Vous pouvez acheminer les journaux vers d'autres destinations Google Cloud ou des destinations externes pour éviter les coûts d'ingestion et de stockage par défaut. Veillez à désactiver l'ingestion de journaux, comme décrit dans la section suivante, pour éviter des coûts d'ingestion.
Désactivez l'ingestion de journaux pour éviter des frais
Il est préférable de réduire l'utilisation des journaux, ou de les exporter ou de les acheminer plutôt que de désactiver l'ingestion de journaux. Toutefois, si vous ne prévoyez pas d'utiliser les journaux Fleet Engine, vous pouvez éviter d'éventuels frais liés à Cloud Logging en désactivant l'ingestion. Par défaut, les journaux de Fleet Engine sont acheminés vers le bucket de journaux _Default.
La commande suivante met à jour le bucket de journalisation _Default pour qu'il n'ingère pas les journaux Fleet Engine.
gcloud logging sinks update _Default \
--log-filter='NOT LOG_ID("cloudaudit.googleapis.com/activity") \
AND NOT LOG_ID("externalaudit.googleapis.com/activity") \
AND NOT LOG_ID("cloudaudit.googleapis.com/system_event") \
AND NOT LOG_ID("externalaudit.googleapis.com/system_event") \
AND NOT LOG_ID("cloudaudit.googleapis.com/access_transparency") \
AND NOT LOG_ID("externalaudit.googleapis.com/access_transparency") \
AND NOT resource.type:"fleetengine.googleapis.com"''
Pour en savoir plus, consultez les pages Exclusions Cloud Logging et Exclure des journaux. Exportations Cloud Logging et Exportation de journaux
Utiliser l'explorateur de journaux
Pour utiliser l'explorateur de journaux, ouvrez Cloud Console, sélectionnez Logging, puis Explorateur de journaux. Pour afficher la liste de tous les journaux Fleet Engine disponibles, cliquez sur le type de ressource Fleet Engine. Certains journaux de l'API comportent un ID de trajet et un ID de véhicule. Vous pouvez utiliser ces libellés pour sélectionner les journaux des trajets ou véhicules qui vous intéressent.
Filtrer les journaux par identifiant de véhicule
Dans l'explorateur de journaux, vous pouvez utiliser la requête suivante pour limiter les journaux à un véhicule spécifique:
resource.type="fleetengine.googleapis.com/Fleet"
labels.vehicle_id="vehicle_id"
Filtrer les journaux par ID de trajet
Dans l'explorateur de journaux, vous pouvez utiliser la requête suivante pour limiter les journaux à un trajet spécifique:
resource.type="fleetengine.googleapis.com/Fleet"
labels.trip_id=~"trip_id"
Filtrer les journaux d'un véhicule sur une période spécifique
Dans l'explorateur de journaux, vous pouvez utiliser la requête suivante pour limiter les journaux à ceux d'un véhicule sur une période spécifique:
resource.type="fleetengine.googleapis.com/Fleet"
labels.vehicle_id="vehicle_id"
timestamp>="2020-09-24T20:00:00.000Z"
timestamp<"2020-09-24T21:00:00.000Z"
Exemple de métriques basées sur les journaux
L'exemple suivant montre comment utiliser les métriques basées sur les journaux pour suivre le nombre de trajets créés au fil du temps.
Dans la console Cloud, sélectionnez Journalisation, puis Explorateur de journaux pour ouvrir l'explorateur de journaux. Appliquez ensuite le filtre suivant:
resource.type="audited_resource" resource.labels.method="maps.fleetengine.v1.TripService.ReportBillableTrip"Dans le volet "Résultats de la requête", sélectionnez la liste déroulante Actions, puis Créer une métrique.
Dans la boîte de dialogue de l'éditeur de métriques:
- Spécifiez un nom de métrique (par exemple, billable_trips).
- Spécifiez une description de métrique (par exemple, The number of Billable Trip call).
- Laissez l'option Units (Unités) vide. _ Laissez l'option Type sur Counter (Compteur).
Sélectionnez ensuite le bouton Create Metric (Créer une métrique).
Sur la page des métriques basées sur les journaux, un message doit confirmer que la métrique a bien été créée. La nouvelle métrique doit apparaître dans la section des métriques définies par l'utilisateur. La métrique est désormais renseignée à mesure que les journaux correspondants sont générés.
Sélectionnez le menu déroulant vertical situé à droite de la nouvelle métrique, puis sélectionnez Afficher dans l'explorateur de métriques.
Dans le volet de gauche, sous "Créer votre requête", définissez le type de ressource sur Fleet Engine et recherchez la métrique "billable_trips".
Le graphique de droite indique le tarif des appels billable_trips.
Utiliser BigQuery
BigQuery est un outil puissant pour effectuer des analyses. Il permet de stocker des journaux à long terme et d'exécuter des requêtes de type SQL ad hoc sur les données.
Acheminer les journaux vers BigQuery
Pour tirer parti de BigQuery, les journaux doivent être acheminés vers un datastore BigQuery, comme suit:
Dans la console Cloud, sélectionnez Journalisation, puis Explorateur de journaux.
Créez un filtre qui isole les journaux Fleet Engine. Dans l'explorateur de champs de journaux, sélectionnez le type de ressource Fleetengine.googleapis.com/Fleet.
Dans le volet "Résultats de la requête", cliquez sur le menu déroulant "Actions", puis sélectionnez Créer un récepteur.
Dans la boîte de dialogue "Sélectionner le service de récepteur", sélectionnez Ensemble de données BigQuery.
Dans la boîte de dialogue "Modifier le récepteur", spécifiez les options suivantes:
- Spécifiez un nom de récepteur (par exemple, FleetEngineLogsSink).
- Laissez le service du récepteur défini sur BigQuery.
- Sélectionnez l'option Utiliser des tables partitionnées. Cela permet d'améliorer les performances des requêtes.
- Sous "Destination du récepteur", sélectionnez Créer un ensemble de données BigQuery, puis spécifiez un nom pour l'ensemble de données BigQuery (par exemple, FleetEngineLogs).
- Cliquez sur le bouton Créer un récepteur.
Vos journaux devraient maintenant commencer à remplir l'ensemble de données BigQuery. Vous pouvez consulter les données dans la section BigQuery de Cloud Console.
Plusieurs tables sous l'ensemble de données FleetEngineLogs sont automatiquement renseignées, une pour chaque type de journal:
- CreateVehicle
- GetVehicle
- ListVehicles
- SearchVehicles
- UpdateVehicle
- CreateTrip
- GetTrip
- UpdateTrip
- ListTrips
Les noms de table utilisent le format suivant:
project_id.data_set.log_name
Par exemple, si le projet s'appelle test_project et que le nom de l'ensemble de données est FleetEngineLogs, la table CreateTrip porte le nom suivant:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_trip
Exemples de requêtes
Cette section présente des exemples de requêtes que vous pouvez créer.
Voyages créés par heure
La requête suivante compte le nombre de journaux CreateTrips et les regroupe par heure.
SELECT TIMESTAMP_TRUNC(timestamp, HOUR) as hour,
count(*) as num_trips_created
FROM
`ProjectId.FleetEngineLogs.fleetengine_googleapis_com_create_trip`
GROUP BY hour
ORDER by hour
Nombre d'arrêts par véhicule et par heure
La requête suivante génère le nombre d'arrêts desservis par un véhicule, ventilés par heure.
Par exemple, cette requête pourrait nous indiquer que dans la dernière heure:
- Le véhicule A a effectué 10 arrêts au cours de l'heure 12 et 8 arrêts au cours de l'heure 13.
- Le véhicule B a effectué 5 arrêts au cours de l'heure 11 et 7 arrêts au cours de l'heure 12.
Le véhicule C a effectué 12 arrêts au cours de l'heure 13 et 9 arrêts au cours de l'heure 14.
SELECT jsonpayload_v1_updatevehiclelog.request.vehicleid AS vehicle, TIMESTAMP_TRUNC(timestamp, HOUR) AS hour, COUNT(*) AS num_stops FROM `ProjectId.FleetEngineLogs.fleetengine_googleapis_com_update__vehicle` WHERE ARRAY_LENGTH(jsonpayload_v1_updatevehiclelog.request.vehicle.remainingvehiclejourneysegments) > 0 AND jsonpayload_v1_updatevehiclelog.request.vehicle.remainingvehiclejourneysegments[ OFFSET (0)].stop.state = 'VEHICLE_STOP_STATE_LOG_ARRIVED' GROUP BY 1, 2 ORDER BY 2
Tableaux de bord Data Studio
BigQuery peut être intégré aux outils d'informatique décisionnelle, et des tableaux de bord peuvent être créés pour les analyses commerciales.
L'exemple suivant montre comment créer un tableau de bord permettant de visualiser les ttrips et les mouvements des véhicules sur une carte.
Lancez un nouveau tableau de bord Data Studio et sélectionnez BigQuery comme connexion de données.
Sélectionnez "Requête personnalisée", puis le projet Cloud sur lequel la facturation doit être effectuée.
Saisissez la requête suivante dans la zone de requête.
SELECT timestamp, labels.vehicle_id, jsonpayload_v1_updatevehiclelog.response.lastlocation.location.latitude AS lat, jsonpayload_v1_updatevehiclelog.response.lastlocation.location.longitude AS lng FROM `ProjectId.FleetEngineLogs.fleetengine_googleapis_com_update_vehicle`Sélectionnez le type de graphique Carte à bulles, puis sélectionnez le champ "Emplacement".
Sélectionnez Créer un champ.
Attribuez un nom au champ et ajoutez la formule suivante: CONCAT(lat, ",", lng).
Définissez ensuite le type sur Géo->Latitude, Longitude.
Vous pouvez ajouter des commandes au tableau de bord pour filtrer les données. Par exemple, sélectionnez le filtre Plage de dates.
Modifiez la zone de sélection de la plage de dates pour sélectionner une plage de dates par défaut.
Vous pouvez ajouter des commandes supplémentaires à la liste déroulante pour l'identifiant du véhicule.
Ces commandes vous permettent de visualiser le mouvement du véhicule ou le mouvement au cours d'un trajet.