Fleet Engine offre un semplice servizio di logging che consente di salvare le richieste API e i payload di risposta. Con questi log puoi eseguire il debug dell'integrazione, creare metriche di monitoraggio e analizzare i pattern di traffico.
Fleet Engine invia i log come log della piattaforma a Cloud Logging, in modo da potervi accedere con gli strumenti di Cloud Logging.
Dati registrati da Fleet Engine
Fleet Engine invia più informazioni a Cloud Logging, ad esempio:
- Tutte le richieste e le risposte REST e gRPC autenticate
- Risposte di errore
- Richieste, risposte e messaggi di errore da chiamate avviate dall'SDK Driver a Fleet Engine.
Suddividi i log per i tipi di log supportati:
Consulta la documentazione per i messaggi di log e lo schema disponibili nel riferimento su Logging.
Utilizza bucket di log limitati e predefiniti per rispettare i criteri di conservazione dei dati
L'uso dei bucket "limitato" e "predefinito" garantisce un quadro chiaro dell'utilizzo dei dati limitato e senza restrizioni. Alcuni dei dati di log che Fleet Engine invia a Google Maps Platform potrebbero essere conservati solo per un periodo di tempo limitato, in base ai Termini specifici dei servizi per la mobilità. Per assicurarti di conservare i dati con restrizioni solo per il periodo di tempo consentito, questi dati devono essere etichettati come TOS_RESTRICTED (già Fleet Engine lo fa) e registrati in un bucket dedicato denominato "limitato".
Da qui, puoi controllare per quanto tempo vengono conservati ed eliminarli definitivamente alla scadenza utilizzando le impostazioni di Cloud Logging. Ad esempio, i log per uso limitato devono essere conservati solo per 30 giorni.
Registra tutti i dati senza restrizioni rimanenti nel bucket "predefinito", dove possono essere conservati per periodi più lunghi, come definito nei Termini specifici dei servizi per la mobilità (in genere per 1 anno). L'uso dei bucket "limitato" e "predefinito" garantisce un quadro chiaro dell'utilizzo dei dati limitato e non limitato.
Ottieni una visualizzazione completa unendo i log con e senza restrizioni
I log per utilizzo limitato contengono i dati per l'utilizzo limitato e un riferimento al log predefinito in modo che possano essere considerati insieme. Il log a uso limitato contiene il valore insertId del log predefinito come riferimento nel campo parent_insert_id. Puoi utilizzare questo campo per unire i dati di entrambi i log e ottenere un quadro completo.
Consulta la documentazione per tutti i messaggi di log e lo schema disponibili nel riferimento su Logging.
Abilitazione di Cloud Logging in corso...
Fleet Engine abilita automaticamente i log predefiniti per i nuovi clienti di Mobility, a partire dai progetti creati il 10 febbraio 2022. Puoi verificare se il logging è abilitato utilizzando la seguente query in Esplora log :
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
Se non vedi alcun log per la query, è possibile che Cloud Logging non sia stato abilitato per il tuo progetto. Contatta l'assistenza se vuoi abilitare la funzionalità.
Abilita log per utilizzo limitato
I log per uso limitato vengono abilitati su richiesta. Per abilitare questi log per il tuo progetto Google Cloud, completa questi passaggi:
Prepara il progetto per ricevere i log per utilizzo limitato
- Nella console Google Cloud, apri la pagina Router dei log.
- Aggiorna il bucket di logging _Default per escludere i log con utilizzo limitato.
- Seleziona il bucket di logging predefinito _Default e poi scegli Modifica sink.
- Nella sezione "Scegli i log per filtrare dal sink", fai clic sul pulsante "Aggiungi esclusione":
- Nome filtro di esclusione: EscludiRestrictedLogs
- Filtro di esclusione: labels.restriction="TOS_RESTRICTED"
- Fai clic su "Aggiorna sink".
- Aggiorna il bucket di logging limitato per archiviare i log per l'utilizzo limitato.
- Nella pagina Router dei log, seleziona "Crea sink".
- Crea un sink con le seguenti impostazioni:
- Dettagli sink:
- Nome: RestrictedLogs
- Descrizione: route di log di Fleet Engine a utilizzo limitato
- Destinazione sink:
- Servizio sink: bucket di logging
- Seleziona bucket di log: crea nuovo bucket di log
- Nome: con limitazioni
- Descrizione: contiene i log per utilizzo limitato di Fleet Engine
- Periodo di conservazione: 30 giorni
- Nota: il periodo di conservazione non deve superare i 30 giorni.
- Log da includere nel sink: lascia vuoto il campo
- Log da filtrare dal sink: fai clic su "Aggiungi esclusione"
- Nome filtro di esclusione: EscludiNonRestrictedLogs
- Filtro di esclusione: NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliveryFleet") NOT (labels.restriction = "TOS_RESTRICTED")
- Fai clic su "Crea sink"
- Dettagli sink:
Contatta l'assistenza per abilitare i log con utilizzo limitato
Quindi, contatta l'assistenza e fornisci le seguenti informazioni nella richiesta di assistenza:
- ID progetto da attivare:
- Indirizzo email della persona che ha richiesto la modifica:
- Nota: questa persona deve disporre dell'accesso in modifica ai progetti Google Cloud elencati.
- Attivando l'utilizzo limitato di Google Maps Content in Cloud Logging, accetti di rispettare i termini di Google Maps Platform e i termini specifici per i servizi per la mobilità, tra cui la memorizzazione nella cache e i requisiti di utilizzo consentito relativi a Google Maps Content. Sì/No
Quando il team di assistenza riceve la richiesta, invia la conferma dell'abilitazione del logging per il progetto
Suddividi i log cloud
Cloud Logging limita le dimensioni dei log in entrata a 256 kB. Il servizio elimina i log oltre questa soglia. Per garantire che Cloud Logging conservi log di grandi dimensioni, Fleet Engine può suddividerli in una serie di log al di sotto della soglia dei 256 kB. Questi log hanno un prefisso insertId comune per indicare l'ordine in cui il servizio divide il log più piccolo dal log sovradimensionato originale. Puoi quindi partecipare nuovamente tra loro in base al loro insertId.
Per accedere al log non suddiviso originale, unisci i log divisi in base ai rispettivi insertId nell'ordine originale in cui sono stati suddivisi, come indicato dal relativo indice nella voce di log cloud.
La struttura di log suddivisi è uguale a quella menzionata nella Guida alle voci di audit log suddiviso per Cloud Audit Logs. La differenza principale per i log suddivisi nel logging del parco risorse è che la suddivisione avviene nel campo jsonPayload, anziché nel campo protoPayload. Osserva l'esempio di suddivisione mostrato nella sezione successiva.
Tipi di log supportati
Fleet Engine supporta la suddivisione dei log solo per i seguenti tipi di log con dimensioni di log superiori a 256 kB:
Esempio di struttura di log di suddivisione
// First Split Log
{
// insertId appended with an increasing number
"insertId": "ABCDE-1",
"jsonPayload": {
"request": {
"filter": "tracking_id=tracking-test-splitting-task"
},
"@type": "type.googleapis.com/maps.fleetengine.delivery.log.v1.ListTasksLog",
"response": {
"tasks": [
{
"name": "providers/providers-123/tasks/test-splitting-task-id-0",
// ...
},
{
"name": "providers/providers-123/tasks/test-splitting-task-id-1",
// ...
},
{
"name": "providers/providers-123/tasks/test-splitting-task-id-2"
// ...
},
{
"name": "providers/providers-123/tasks/test-splitting-task-id-3",
// ...
},
]
},
"header": {}
},
"resource": {
"type": "fleetengine.googleapis.com/DeliveryFleet",
"labels": {
"resource_container": "projects/providers-123",
"location": "global"
}
},
// Same timestamp
"timestamp": "2024-01-29T23:35:58.076515Z",
"labels": {
},
"logName": "projects/providers-123/logs/fleetengine.googleapis.com%2Flist_tasks",
"receiveTimestamp": "2024-01-29T23:35:59.278858322Z",
"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": {
"request": {
"filter": "tracking_id=tracking-test-splitting-task"
},
"@type": "type.googleapis.com/maps.fleetengine.delivery.log.v1.ListTasksLog",
"response": {
"tasks": [
// Previous tasks appear as empty objects in subsequent splits
{}, {}, {}, {},
{
"name": "providers/providers-123/tasks/test-splitting-task-id-4",
// ...
}
]
},
"header": {}
},
"resource": {
"type": "fleetengine.googleapis.com/DeliveryFleet",
"labels": {
"resource_container": "projects/providers-123",
"location": "global"
}
},
// Same timestamp
"timestamp": "2024-01-29T23:35:58.076515Z",
"labels": {
},
"logName": "projects/providers-123/logs/fleetengine.googleapis.com%2Flist_tasks",
"receiveTimestamp": "2024-01-29T23:35:59.278858322Z",
"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
}
}
Accedi ai tuoi log
I log di Cloud sono strutturati in base al formato LogEntry. Fleet Engine invia i log a Cloud Logging con resource.type di LogEntry impostato su fleetengine.googleapis.com. Puoi utilizzare Esplora log per scrivere query per visualizzare i log.
Ad esempio, per visualizzare tutte le RPC per Fleet Engine che hanno restituito un errore, utilizza la seguente query di Esplora log:
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
Per visualizzare i log delle RPC effettuate con il metodo UpdateDeliveryVehicle per il progetto example-project-id, utilizza la seguente query di Esplora log:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle"
L'esempio seguente mostra una voce LogEntry per il log UpdateDeliveryVehicle. La richiesta e la risposta RPC si trovano nel campo 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.UpdateDeliveryVehicleLog"
},
"resource": {
"type": "fleetengine.googleapis.com/DeliveryFleet",
"labels": {2}
},
"timestamp": "2021-01-01T00:00:00.000000000Z",
"labels": {2},
"logName": "projects/example-project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle",
"receiveTimestamp": "2021-01-01T00:00:00.000000000Z"
}
Se viene restituito un errore RPC, il campo responseDeliveryVehicle viene cancellato e il campo errorResponse viene impostato e compilato in jsonPayload:
{
"insertId": "2ead60bdec561836a1bb84a90e9915cd",
"jsonPayload": {
"@type": "type.googleapis.com/maps.fleetengine.delivery.log.v1.UpdateDeliveryVehicleLog",
"header": {
"languageCode": "en",
"osVersion": "11",
"platform": "PLATFORM_LOG_ANDROID",
"regionCode": "US",
"sdkType": "SDK_TYPE_LOG_DRIVER",
"sdkVersion": "4.4.3"
},
"request": {
"deliveryVehicle": {4},
"deliveryVehicleId": "uniqueDeliveryVehicleId",
"updateMask": "lastLocation"
},
"response": {
"lastLocation": {14},
"name": "providers/example-project-id/deliveryVehicles/uniqueDeliveryVehicleId",
"navigationStatus": "NAVIGATION_STATUS_ARRIVED_AT_DESTINATION",
"remainingDistanceMeters": "430",
"remainingDuration": "10s"
}
},
"labels": {
"delivery_vehicle_id": "uniqueDeliveryVehicleId"
},
"logName": "projects/example-project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle",
"receiveTimestamp": "2023-07-14T22:57:51.156515110Z",
"resource": {
"labels": {2},
"type": "fleetengine.googleapis.com/DeliveryFleet"
},
"timestamp": "2023-07-14T22:57:51.018045Z"
}
Per ulteriori informazioni sul linguaggio di query di logging, consulta Lingua delle query di logging. Per informazioni su come utilizzare i log per creare metriche, consulta Panoramica delle metriche basate su log.
Gestisci i costi di logging
Una volta abilitato il logging, sei responsabile di configurare la modalità di routing, archiviazione e conservazione dei log. Se superi i limiti di utilizzo e conservazione senza costi aggiuntivi, potresti incorrere in addebiti Google Cloud aggiuntivi per l'importazione e la conservazione dei log. Tuttavia, puoi controllare i costi di logging in uno dei seguenti modi:
Riduci l'utilizzo del logging
Puoi limitare la quantità di importazione dei dati di log escludendo determinate voci di log.
Esporta o esegui il routing dei log
Puoi eseguire il routing dei log ad altre destinazioni Google Cloud o esterne per evitare i costi predefiniti per l'importazione e l'archiviazione. Assicurati di disattivare l'importazione dei log, come descritto nella sezione successiva, per evitare costi di importazione.
Disattiva l'importazione dei log per evitare addebiti
È preferibile ridurre l'utilizzo del logging oppure esportare o eseguire il routing dei log rispetto alla disattivazione dell'importazione dei log. Tuttavia, se non intendi utilizzare i log di Fleet Engine, puoi evitare potenziali addebiti di Cloud Logging disattivando l'importazione. Per impostazione predefinita, i log di Fleet Engine vengono instradati al bucket di log _Default.
Il comando seguente aggiorna il bucket di logging _Default per non importare i log di 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"''
Per ulteriori informazioni, consulta: Esclusioni di Cloud Logging ed esclusione dei log. Esportazioni Cloud Logging ed Esportazione dei log
Utilizzo di Esplora log
Per utilizzare Esplora log, apri la console Cloud, seleziona Logging, quindi Esplora log. Per visualizzare un elenco di tutti i log di Fleet Engine disponibili, fai clic sul tipo di risorsa Fleet Engine. Alcuni log dell'API Delivery sono etichettati con un ID attività e un ID veicolo di consegna. Puoi usare queste etichette per selezionare i log per le attività o i veicoli che ti interessano.
Filtra i log in base all'ID veicolo per la consegna
In Esplora log, puoi utilizzare la seguente query per limitare i log a un veicolo specifico:
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
Filtra i log per ID attività
In Esplora log, puoi utilizzare la seguente query per limitare i log a un'attività specifica:
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.task_id=~"task_id"
Filtra i log per un veicolo in un periodo di tempo specifico
In Esplora log, puoi utilizzare la seguente query per limitare i log a quelli per un veicolo in un periodo di tempo specifico:
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
timestamp>="2020-09-24T20:00:00.000Z"
timestamp<"2020-09-24T21:00:00.000Z"
Esempio di metriche basate su log
L'esempio seguente mostra come utilizzare le metriche basate su log per tenere traccia del numero di attività create nel tempo.
Nella console Cloud, seleziona Logging, quindi Esplora log per aprire Esplora log. Quindi applica il seguente filtro:
resource.type="fleetengine.googleapis.com/DeliveryFleet" resource.labels.location="global" logName="projects/ProjectID/logs/fleetengine.googleapis.com%2Fupdate_task" jsonPayload.request.task.taskOutcome="TASK_OUTCOME_LOG_SUCCEEDED" jsonPayload.request.updateMask="taskOutcome" jsonPayload.response.type= ("TASK_TYPE_LOG_PICKUP" OR "TASK_TYPE_LOG_DELIVERY")Nel riquadro Risultati delle query, seleziona il menu a discesa Azioni e quindi seleziona Crea metrica.
Nella finestra di dialogo Editor metriche:
- Specifica un nome per la metrica, ad esempio billable_tasks.
- Specifica una descrizione della metrica, ad esempio Il numero di attività fatturabili.
- Lascia vuota l'opzione Unità. _ Lascia l'opzione Tipo impostata su Contatore.
Quindi seleziona il pulsante Crea metrica.
Nella pagina Metriche basate su log, dovrebbe essere visualizzato un messaggio che conferma l'avvenuta creazione della metrica e la nuova metrica dovrebbe apparire nella sezione Metriche definite dall'utente. La metrica verrà compilata man mano che vengono generati i log corrispondenti.
Seleziona il menu a discesa verticale sul lato destro della nuova metrica e poi seleziona Visualizza in Esplora metriche.
Nel riquadro a sinistra, in Crea la tua query, imposta il tipo di risorsa su Motore del parco risorse e cerca la metrica billable_tasks.
Il grafico sulla destra mostra la frequenza delle chiamate billable_tasks.
Utilizzo di BigQuery
BigQuery è un potente strumento per eseguire analisi. Può essere utilizzato per archiviare log a lungo termine ed eseguire query ad hoc di tipo SQL sui dati.
Routing dei log a BigQuery
Per sfruttare BigQuery, i log devono essere instradati a un datastore BigQuery, come segue:
Nella console Cloud, seleziona Logging, quindi Esplora log.
Crea un filtro che isola i log di Fleet Engine. In Esplora campi dei log, seleziona il tipo di risorsa Fleetengine.googleapis.com/DeliveryFleet.
Nel riquadro Risultati delle query, fai clic sul menu a discesa Azioni e scegli Crea sink.
Nella finestra di dialogo Seleziona servizio sink, seleziona Set di dati BigQuery.
Nella finestra di dialogo Modifica sink, specifica le seguenti opzioni:
- Specifica un nome per il sink (ad esempio, FleetEngineLogsSink).
- Lascia il servizio sink su BigQuery.
- Seleziona l'opzione Utilizza tabelle partizionate. Ciò migliorerà le prestazioni delle query.
- In Destinazione sink, seleziona Crea nuovo set di dati BigQuery, quindi specifica un nome per il set di dati BigQuery (ad esempio, FleetEngineLogs).
- Fai clic sul pulsante Crea sink.
A questo punto i log dovrebbero iniziare a completare il set di dati BigQuery. Puoi visualizzare i dati nella sezione BigQuery della console Cloud.
Diverse tabelle nel set di dati FleetEngineLogs verranno compilate automaticamente, una per ogni tipo di log:
- CreateDeliveryVehicle
- GetDeliveryVehicle
- ListDeliveryVehicle
- UpdateDeliveryVehicle
- CreateTask
- GetTask
- UpdateTask
- ListTasks
I nomi delle tabelle utilizzano il seguente pattern:
project_id.data_set.log_name
Ad esempio, se il progetto è denominato test_project e il nome del set di dati è FleetEngineLogs, la tabella CreateTask ha il seguente nome:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_task
Esempi di query
Questa sezione mostra esempi di query che puoi creare.
Attività create all'ora
La seguente query conteggia il numero di log CreateTasks e li raggruppa per ora.
SELECT TIMESTAMP_TRUNC(timestamp, HOUR) as hour,
count(*) as num_tasks_created
FROM
`ProjectId.FleetEngineLogs.fleetengine_googleapis_com_create_task`
GROUP BY hour
ORDER by hour
Numero di fermate per veicolo all'ora
La seguente query genera un conteggio delle fermate servite da un veicolo, suddivise per ora.
Ad esempio, questa query potrebbe indicare che nell'ultima ora:
- Il veicolo A ha completato 10 fermate nell'ora 12 e 8 fermate nell'ora 13.
- Il veicolo B ha completato 5 fermate nell'ora 11 e 7 soste nell'ora 12.
Il veicolo C ha completato 12 fermate nell'ora 13 e 9 fermate nell'ora 14.
SELECT jsonpayload_v1_updatedeliveryvehiclelog.request.deliveryvehicleid AS vehicle, TIMESTAMP_TRUNC(timestamp, HOUR) AS hour, COUNT(*) AS num_stops FROM `ProjectId.FleetEngineLogs.fleetengine_googleapis_com_update_delivery_vehicle` WHERE ARRAY_LENGTH(jsonpayload_v1_updatedeliveryvehiclelog.request.deliveryvehicle.remainingvehiclejourneysegments) > 0 AND jsonpayload_v1_updatedeliveryvehiclelog.request.deliveryvehicle.remainingvehiclejourneysegments[ OFFSET (0)].stop.state = 'VEHICLE_STOP_STATE_LOG_ARRIVED' GROUP BY 1, 2 ORDER BY 2
Percentuale di successo della prima consegna
La seguente query mostra la percentuale di successo nella prima percentuale di tentativi di consegna.
SELECT
vehicle_id,
COUNTIF(outcome = "TASK_OUTCOME_LOG_SUCCEEDED") AS num_success,
COUNT(*) AS total_deliveries,
COUNTIF(outcome = "TASK_OUTCOME_LOG_SUCCEEDED") * 100/ COUNT(*) AS success_rate
FROM (
SELECT
labels.delivery_vehicle_id AS vehicle_id,
jsonpayload_v1_updatetasklog.response.trackingid AS trackingid,
ARRAY_AGG(jsonpayload_v1_updatetasklog.response.taskoutcome
ORDER BY
timestamp ASC)[ORDINAL(1)] AS outcome,
FROM
`ProjectId.FleetEngineLogsfleetengine_googleapis_com_update_task`
WHERE
jsonpayload_v1_updatetasklog.response.type = "TASK_TYPE_LOG_DELIVERY"
GROUP BY 1, 2
ORDER BY 1, 2)
GROUP BY 1
ORDER BY 1
Dashboard di Data Studio
Integrare BigQuery con strumenti di business intelligence e creare dashboard per l'analisi aziendale.
L'esempio seguente mostra come creare una dashboard su cui le attività e i movimenti dei veicoli possono essere visualizzati su una mappa.
Avvia una nuova dashboard di Data Studio e seleziona BigQuery come connessione dati.
Seleziona Query personalizzata e scegli il progetto Cloud a cui deve essere fatturata.
Inserisci la seguente query nella casella della query.
SELECT
timestamp,
labels.delivery_vehicle_id,
jsonpayload_v1_updatedeliveryvehiclelog.response.lastlocation.rawlocation.latitude AS lat,
jsonpayload_v1_updatedeliveryvehiclelog.response.lastlocation.rawlocation.longitude AS lng
FROM
`ProjectId.FleetEngineLogs.fleetengine_googleapis_com_update_delivery_vehicle`
Seleziona Tipo di grafico come Mappa a bolle, quindi seleziona il campo della posizione.
Seleziona Crea campo.
Assegna un nome al campo e aggiungi la formula seguente: CONCAT(lat, ",", lng).
Quindi imposta il tipo su Geo->Latitudine, Longitudine.
Puoi aggiungere controlli alla dashboard per filtrare i dati. Ad esempio, seleziona il filtro Intervallo di date.
Modifica la casella dell'intervallo di date per selezionare un intervallo di date predefinito.
Puoi aggiungere ulteriori controlli all'elenco a discesa per delivery_vehicle_id.
Con questi controlli, puoi visualizzare il movimento del veicolo o il movimento all'interno di una consegna.