Fleet Engine offre un servizio di logging semplice 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 per consentirti di accedervi tramite gli strumenti di Cloud Logging.
Log di Fleet Engine
Fleet Engine invia diverse informazioni a Cloud Logging, ad esempio:
- Tutte le richieste e 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 lo schema e i messaggi di log disponibili nel riferimento di Logging.
Utilizza bucket di log limitati e predefiniti per rispettare i criteri di conservazione dei dati
L'utilizzo dei bucket "con restrizioni" e "predefinito" garantisce un quadro chiaro dell'utilizzo dei dati limitato e non limitato. Alcuni dei dati di log che Fleet Engine invia a Google Maps Platform possono 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 limitati solo per il periodo di tempo consentito, tali dati devono essere etichettati come TOS_RESTRICTED (già Fleet Engine lo fa) e registrati in un bucket dedicato chiamato "limitato".
Da qui, puoi controllare per quanto tempo verrà conservato ed eliminarli automaticamente alla scadenza utilizzando le impostazioni di Cloud Logging. Ad esempio, i log per l'utilizzo limitato devono essere conservati solo per 30 giorni.
Registra tutti i dati senza limitazioni rimanenti nel bucket "predefinito", dove possono essere conservati per durate più lunghe come definito nei Termini specifici dei servizi per la mobilità (in genere per 1 anno). L'uso dei bucket "con restrizioni" e "predefinito" garantisce un quadro chiaro dell'utilizzo dei dati limitato e non limitato.
Ottieni una visualizzazione completa unendo log con e senza restrizioni
I log a utilizzo limitato contengono i dati a utilizzo limitato e un riferimento al log predefinito in modo che possano essere considerati insieme. Il log per l'utilizzo limitato contiene l'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 il quadro completo.
Consulta la documentazione per tutti i messaggi di log e lo schema disponibili nel riferimento di Logging.
Abilitazione di Cloud Logging
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 log per quella 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 con utilizzo limitato sono abilitati su richiesta. Per abilitare questi log per il tuo progetto Google Cloud, completa i seguenti passaggi:
Prepara il progetto per ricevere log a utilizzo limitato
- Nella console Google Cloud, apri la pagina del router dei log.
- Aggiorna il bucket di logging _Default per escludere i log a utilizzo limitato.
- Seleziona il bucket di logging _Default, quindi scegli Modifica sink.
- Nella sezione "Scegli i log da escludere 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 a utilizzo limitato.
- Nella pagina Router dei log, seleziona "Crea sink".
- Crea un sink con le seguenti impostazioni:
- Dettagli sink:
- Nome: RestrictedLogs
- Descrizione: log a utilizzo limitato di Routes Fleet Engine
- Destinazione sink:
- Servizio sink: bucket di Logging
- Seleziona bucket di log: Crea nuovo bucket di log
- Nome: Con restrizioni
- Descrizione: contiene log a 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
- 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
Poi, contatta l'assistenza e fornisci le seguenti informazioni nella richiesta di assistenza:
- ID progetto da abilitare:
- Indirizzo email della persona che richiede la modifica:
- Nota: questa persona deve disporre dell'accesso in modifica ai progetti Google Cloud elencati.
- Abilitando i contenuti di Google Maps a utilizzo limitato in Cloud Logging, accetti di rispettare i termini di Google Maps Platform e i termini specifici del servizio Mobile, inclusi i requisiti per la memorizzazione nella cache e l'utilizzo consentito in relazione ai Contenuti di Google Maps. Sì/No
Quando il team di assistenza riceve la tua richiesta, invia la conferma che il logging è stato abilitato per il tuo progetto
Suddividi 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 i log di grandi dimensioni, Fleet Engine può suddividerli in una serie di log al di sotto della soglia di 256 kB. Questi log hanno un prefisso insertId comune per indicare l'ordine in cui il servizio suddivide il log più piccolo dal log originale con dimensioni eccessive. Potrai quindi partecipare di nuovo a questi partecipanti in base al loro insertId.
Per accedere al log originale non suddiviso, unisci i log suddivisi in base ai relativi insertId nell'ordine originale in cui sono stati suddivisi, come indicato dall'indice nella voce di log del cloud.
La struttura dei log suddivisi è la stessa menzionata nella guida alle voci di audit log Suddividi per Cloud Audit Logs. La differenza principale per i log suddivisi in Fleet Logging è che la suddivisione avviene nel campo jsonPayload, anziché nel campo protoPayload. Esamina la suddivisione di esempio mostrata nella sezione successiva.
Tipi di log supportati
Fleet Engine supporta la suddivisione dei log solo per i seguenti tipi di log le cui dimensioni superano i 256 kB:
Esempio di struttura di log suddivisi
// 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 cloud sono strutturati secondo il formato LogEntry. Fleet Engine invia i log a Cloud Logging con resource.type della voce di log impostato su fleetengine.googleapis.com. Puoi utilizzare Esplora log per scrivere query per la visualizzazione dei log.
Ad esempio, per visualizzare tutte le RPC di Fleet Engine che hanno restituito un errore, utilizza la seguente query Esplora log:
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
Per visualizzare i log delle RPC effettuate al metodo UpdateDeliveryVehicle per l'ID progetto-progetto, utilizza la seguente query 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 all'interno del 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 all'interno di 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 la Panoramica delle metriche basate su log.
Gestire i costi di logging
Dopo aver 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, potresti incorrere in addebiti aggiuntivi di Google Cloud per l'importazione e la conservazione dei log. Tuttavia, puoi controllare i costi di logging effettuando una delle seguenti operazioni:
Riduci l'utilizzo del logging
Puoi limitare la quantità di importazione dei dati di log escludendo determinate voci di log.
Esporta o instrada i log
Puoi eseguire il routing dei log su altre destinazioni Google Cloud o esterne per evitare i costi di importazione e archiviazione predefiniti. Assicurati di disattivare l'importazione dei log, come descritto nella prossima sezione, per evitare costi di importazione.
Disattiva l'importazione dei log per evitare addebiti
È preferibile ridurre l'utilizzo del logging o l'esportazione o il routing dei log rispetto alla disattivazione dell'importazione dei log. Tuttavia, se non intendi utilizzare i log di Fleet Engine, puoi evitare i potenziali addebiti di Cloud Logging disattivando l'importazione. Per impostazione predefinita, i log di Fleet Engine vengono instradati al bucket di log _Default.
Il seguente comando aggiorna il bucket di logging _Default in modo da non importare i log del 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 di 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 usarle per selezionare i log per le attività o i veicoli che ti interessano.
Filtra i log per 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"
Filtrare 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 monitorare il numero di attività create nel tempo.
Nella console Cloud, seleziona Logging, quindi Esplora log per aprire Esplora log. A questo punto, 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 seleziona Crea metrica.
Nella finestra di dialogo Editor metriche:
- Specifica il nome di una 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.
Poi seleziona il pulsante Crea metrica.
Nella pagina Metriche basate su log, dovresti visualizzare un messaggio che conferma che la metrica è stata creata correttamente e che la nuova metrica dovrebbe essere visualizzata nella sezione Metriche definite dall'utente. La metrica verrà ora completata 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 Metrics Explorer.
Nel riquadro a sinistra, in Crea query, imposta il tipo di risorsa su Fleet Engine e cerca la metrica billable_tasks.
Il grafico a destra mostra la percentuale di chiamate fatturabili_tasks.
Utilizzo di BigQuery
BigQuery è un potente strumento per l'esecuzione di analisi. Può essere utilizzata per archiviare log a lungo termine ed eseguire query ad hoc di tipo SQL sui dati.
Routing dei log a BigQuery
Per utilizzare 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 di 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 e specifica il nome di un 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.
Verranno compilate automaticamente diverse tabelle nel set di dati FleetEngineLogs, una per ogni tipo di log:
- CreateDeliveryVehicle
- GetDeliveryVehicle
- ListDeliveryVehicle
- UpdateDeliveryVehicle
- CreateTask
- GetTask
- UpdateTask
- ListTasks
- SearchTasks
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 conta 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 scali 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 fermate 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 pubblicazione
La seguente query che 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
È possibile integrare BigQuery con strumenti di business intelligence, oltre a creare dashboard per l'analisi aziendale.
L'esempio seguente mostra come creare una dashboard in base alle attività e ai movimenti dei veicoli che possono essere visualizzati su una mappa.
Avvia una nuova dashboard di Datastudio e seleziona BigQuery come connessione dati.
Seleziona Query personalizzata e il progetto Cloud a cui deve essere fatturata.
Inserisci la query seguente 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 Mappa a bolle come tipo di grafico, quindi seleziona il campo della località.
Seleziona Crea campo.
Assegna un nome al campo e aggiungi la seguente formula: 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 altri controlli all'elenco a discesa per delivery_vehicle_id.
Con questi controlli, puoi visualizzare il movimento del veicolo o quello all'interno di una consegna.