O Fleet Engine oferece um serviço de geração de registros simples que permite salvar solicitações de API e payloads de resposta. Com esses registros, é possível depurar sua integração, criar métricas de monitoramento e analisar padrões de tráfego.
O Fleet Engine envia os registros como registros da plataforma para o Cloud Logging, para que você possa usar as ferramentas do Cloud Logging para acessá-los.
O que o Fleet Engine registra
O Fleet Engine envia várias informações para o Cloud Logging, como:
- Todas as solicitações e respostas REST e gRPC autenticadas
- Respostas de erro
- Solicitações, respostas e mensagens de erro de chamadas iniciadas pelo SDK do driver para o Fleet Engine
Consulte a documentação para ver as mensagens de registro e o esquema disponíveis na Referência do Logging.
Use buckets de registros restritos e padrão para obedecer às políticas de retenção de dados.
Usar buckets "restritos" e "padrão" garante uma imagem clara do uso de dados restrito e irrestrito. Alguns dos dados de registro que o Fleet Engine envia para a Plataforma Google Maps só podem ser retidos por um período limitado, de acordo com os Termos específicos de serviço de mobilidade. Para reter dados restritos apenas pelo tempo permitido, o Google recomenda que você rotule dados restritos como TOS_RESTRICTED e os envie para um bucket dedicado chamado "restrito". De lá, é possível controlar por quanto tempo eles são retidos e limpá-los automaticamente após a expiração usando as configurações do Cloud Logging. Por exemplo, os registros de uso restrito só devem ser retidos por 30 dias.
Envia todos os dados de registro irrestritos restantes para o bucket "padrão", em que podem permanecer indefinidamente.
Tenha uma visão completa mesclando registros restritos e irrestritos
Os registros de uso restrito contêm os dados de uso restrito e uma referência ao registro padrão para que sejam considerados juntos. O registro de uso restrito contém o insertId do registro padrão como uma referência no campo parent_insert_id. Use esse campo para mesclar os dados dos dois registros e ter uma visão completa.
Consulte a documentação de todas as mensagens de registro e esquemas disponíveis na Referência do Logging.
Como ativar o Cloud Logging
O Fleet Engine ativa automaticamente os registros padrão para novos clientes do Mobility, começando com os projetos criados em 10 de fevereiro de 2022. Confirme se o registro está ativado usando a seguinte consulta no Buscador de registros :
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
Se não houver registros para essa consulta, talvez o Cloud Logging não esteja ativado para seu projeto. Entre em contato com o suporte se quiser ativar o recurso.
Ativar registros de uso restrito
Os registros de uso restrito são ativados mediante solicitação. Para ativar esses registros no seu projeto do GCP, siga estas etapas:
Prepare seu projeto para receber registros de uso restrito
- No console do Google Cloud, abra a página "Roteador de registros".
- Atualize o bucket de geração de registros _Default para excluir registros de uso restrito.
- Selecione o bucket de geração de registros _Padrão e escolha Editar coletor.
- Na seção "Escolher registros para filtrar do coletor", clique no botão "Adicionar exclusão":
- Nome do filtro de exclusão: ExcludeRestrictedLogs
- Filtro de exclusão: labels.restriction="TOS_RESTRICTED"
- Clique em "Atualizar coletor".
- Atualize o bucket de geração de registros restritos para armazenar os registros de uso restrito.
- Na página "Roteador de registros", selecione "Criar coletor".
- Crie um coletor com as seguintes configurações:
- Detalhes do coletor:
- Nome: RestrictedLogs
- Descrição: registros de uso restrito do Routes Fleet Engine
- Destino do coletor:
- Serviço do coletor: bucket do Logging
- Selecionar bucket de registros: criar um novo bucket de registros
- Nome: Restrito
- Descrição: contém registros de uso restrito do Fleet Engine
- Período de retenção: 30 dias
- Observação: o período de armazenamento não pode exceder 30 dias.
- Registros a serem incluídos no coletor: deixe em branco
- Registros a serem filtrados do coletor: clique em "Adicionar exclusão"
- Nome do filtro de exclusão: ExcludeNonRestrictedLogs
- Filtro de exclusão: NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliveryFleet") NOT (labels.restriction = "TOS_RESTRICTED")
- Clique em "Criar coletor"
Entrar em contato com o suporte para ativar os registros de uso restrito
Em seguida, entre em contato com o suporte e forneça as seguintes informações na sua solicitação de suporte:
- IDs dos projetos a serem ativados:
- Endereço de e-mail da pessoa que solicita a mudança:
- Observação: essa pessoa precisa ter acesso para editar os projetos do GCP listados acima.
- Ao ativar o conteúdo do Google Maps para uso restrito no Cloud Logging, você concorda em obedecer aos termos da Plataforma Google Maps e aos termos específicos do serviço de mobilidade, incluindo os requisitos de armazenamento em cache e de uso permitido relacionados ao conteúdo do Google Maps. Sim / Não
Assim que a equipe de suporte receber seu pedido, ela enviará a confirmação de que o registro foi ativado no seu projeto
Acessar os registros
Os registros do Cloud são estruturados em torno do formato dSYM. O Fleet Engine envia registros para o Cloud Logging com o resource.type
do RecyclerView definido como fleetengine.googleapis.com. Use o Navegador de Registros e grave consultas para visualizá-los.
Por exemplo, para ver todas as RPCs para o Fleet Engine que retornaram um erro, use a seguinte consulta do Explorador de registros:
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
Para ver registros de RPCs feitas no método UpdateDeliveryVehicle do ID do projeto example-project, use a seguinte consulta do Explorador de registros:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle"
No exemplo a seguir, mostramos um dSYM para o registro UpdateDeliveryVehicle. A solicitação e a resposta da RPC estão localizadas dentro do 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 um erro de RPC for retornado, o campo responseDeliveryVehicle será
limpado e o campo errorResponse será definido e preenchido em 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"
}
Para mais informações sobre a linguagem de consulta da geração de registros, acesse Linguagem de consulta do Logging. Para mais informações sobre como usar registros para criar métricas, consulte Visão geral de métricas com base em registros.
Gerenciar custos de geração de registros
Depois que a geração de registros estiver ativada, você será responsável por configurar o roteamento, o armazenamento e a retenção de registros. Você poderá receber cobranças extras do Google Cloud Platform pelo processamento e retenção de registros se exceder os limites de uso e retenção sem custos adicionais. No entanto, é possível controlar os custos de geração de registros seguindo um destes procedimentos:
Reduzir o uso da geração de registros
Para limitar a quantidade de ingestão de dados de registro, exclua determinadas entradas.
Exportar ou rotear registros
É possível rotear registros para outros destinos do GCP ou externos para evitar os custos de ingestão e armazenamento padrão. Desative a ingestão de registros, conforme descrito abaixo, para evitar custos de ingestão.
Desative a ingestão de registros para evitar cobranças
É preferível reduzir o uso da geração de registros, ou exportar ou rotear registros, em vez de desativar a ingestão de registros. No entanto, se você não pretende usar os registros do Fleet Engine, desative a ingestão para evitar possíveis cobranças do Cloud Logging. Por padrão, os registros do Fleet Engine são roteados para o bucket de registros _Default.
O comando a seguir atualiza o bucket de geração de registros _Default para não ingerir registros do 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"''
Para mais informações, consulte: Exclusões do Cloud Logging e Como excluir registros. Exportações do Cloud Logging e exportação de registros
Usar o explorador de registros
Para usar o Explorador de registros, abra o Console do Cloud, selecione Logging e, em seguida, Explorador de registros. Para ver uma lista de todos os registros do Fleet Engine disponíveis, clique no tipo de recurso do Fleet Engine. Alguns registros da API Delivery são identificados com um ID da tarefa e um ID do veículo de entrega. Use esses rótulos para selecionar registros para as tarefas ou veículos do seu interesse.
Filtrar registros por ID do veículo de entrega
No Explorador de registros, use a consulta a seguir para restringir os registros a um veículo específico:
none
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
Filtrar registros por ID da tarefa
Use a consulta a seguir no Explorador de registros para restringir os registros a uma tarefa específica:
none
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.task_id=~"task_id"
Observação: para garantir que o filtro de consulta capture todos os registros, use o operador
=~. Se houver várias tarefas atribuídas a um veículo,
os IDs das tarefas serão separados por vírgulas. Esse filtro corresponde a qualquer registro que inclua o valor no rótulo, em vez de uma verificação estrita de igualdade.
Filtrar registros de um veículo em um período específico
No Explorador de registros, use a consulta a seguir para restringir os registros
aos de um veículo em um período específico:
none
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"
Observação: os valores de horário neste exemplo estão no formato Tempo Universal Coordenado (UTC). Para especificar um fuso horário, substitua a letra Z no final do carimbo de data/hora por +hh:mm ou -hh:mm. Para mais informações, consulte a documentação do Cloud.
Exemplo de métricas com base em registros
O exemplo a seguir mostra como usar métricas com base em registros para rastrear o número de tarefas criadas ao longo do tempo.
No Console do Cloud, selecione Logging e, em seguida, Explorador de registros para abri-lo. Em seguida, aplique o filtro abaixo:
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")No painel "Query Results", selecione o menu suspenso Actions e selecione Create Metric.
Na caixa de diálogo "Editor de métricas", faça o seguinte:
- Especifique o nome de uma métrica (por exemplo, billable_tasks).
- Especifique uma descrição de métrica (por exemplo, O número de tarefas faturáveis).
- Deixe a opção Unidades em branco. Deixe a opção Tipo como Contador.
Em seguida, selecione o botão Criar métrica.
Na página "Métricas com base em registros", você verá uma mensagem confirmando que a métrica foi criada com êxito, e a nova métrica aparecerá na seção "Métricas definidas pelo usuário". A métrica agora será preenchida à medida que os registros correspondentes forem gerados.
Selecione o menu suspenso vertical no lado direito da nova métrica e, em seguida, selecione Exibir no Metrics Explorer.
No painel esquerdo, em "Criar sua consulta", defina o tipo de recurso como Fleet Engine e pesquise a métrica billable_tasks.
O gráfico à direita mostra a taxa de chamadas billable_tasks.
Usar o BigQuery
O BigQuery é uma ferramenta eficiente para realizar análises. Ele pode ser usado para armazenar registros de longo prazo e realizar consultas ad hoc do tipo SQL nos dados.
Como rotear registros para o BigQuery
Para aproveitar o BigQuery, os registros precisam ser roteados para um armazenamento de dados do BigQuery da seguinte maneira:
No console do Cloud, selecione Logging e, em seguida, Buscador de registros.
Crie um filtro que isole os registros do Fleet Engine. No Explorador de campos de registros, selecione o tipo de recurso Fleetengine.googleapis.com/DeliveryFleet.
No painel "Resultados da consulta", clique no menu suspenso "Ações" e escolha Criar coletor.
Na caixa de diálogo "Selecionar serviço do coletor", selecione Conjunto de dados do BigQuery.
Na caixa de diálogo Editar coletor, especifique as seguintes opções:
- Especifique um nome de coletor (por exemplo, FleetEngineLogsColetor).
- Deixe o Serviço do coletor como BigQuery.
- Selecione a opção Usar tabelas particionadas. Isso vai melhorar a performance da consulta.
- Em "Destino do coletor", selecione Criar novo conjunto de dados do BigQuery e especifique o nome de um conjunto de dados do BigQuery (por exemplo, FleetEngineLogs).
- Clique no botão Criar coletor.
Seus registros começarão a preencher o conjunto de dados do BigQuery. Veja os dados na seção BigQuery do Console do Cloud.
Várias tabelas no conjunto de dados FleetEngineLogs serão preenchidas automaticamente, uma para cada tipo de registro:
- CreateDeliveryVehicle
- Veículo GetDelivery
- Veículo de entrega de listas
- Atualize o veículo de entrega
- CreateTask
- GetTask
- Tarefa de atualização
- ListTasks
- Tarefas de pesquisa
Os nomes das tabelas usam o seguinte padrão:
project_id.data_set.log_name
Por exemplo, se o projeto se chamar test_project e o nome do conjunto de dados for FleetEngineLogs, a tabela CreateTask terá o seguinte nome:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_task
Exemplos de consultas
Esta seção mostra exemplos de consultas que podem ser criadas.
Tarefas criadas por hora
A consulta a seguir conta o número de registros CreateTasks e os agrupa por hora.
sql
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
Número de paradas por veículo e hora
A consulta a seguir gera uma contagem das paradas que um veículo atendeu, divididas por hora.
Por exemplo, essa consulta pode indicar que, na última hora:
- O Veículo A completou 10 paradas na hora 12 e 8 paradas na hora 13.
- O Veículo B fez 5 paradas na hora 11 e 7 paradas na hora 12.
O Veículo C completou 12 paradas na hora 13 e 9 paradas na hora 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
Taxa de sucesso da primeira entrega
A consulta a seguir mostra a porcentagem de sucesso na primeira taxa de tentativa de entrega.
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
Painéis do Data Studio
O BigQuery pode ser integrado a ferramentas de Business Intelligence, e painéis podem ser criados para análise de negócios.
O exemplo a seguir mostra como criar um painel em que as tarefas e os movimentos do veículo podem ser visualizados em um mapa.
Inicie um novo painel do Data Studio e selecione BigQuery como a conexão de dados.
Selecione "Consulta personalizada" e o projeto do Cloud que receberá a cobrança.
Insira a consulta a seguir na caixa de consulta.
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`
Selecione "Tipo de gráfico" como Mapa de círculos e selecione o campo de local.
Selecione Criar campo.
Nomeie o campo e adicione a seguinte fórmula: CONCAT(lat, ",", lng).
Em seguida, defina o tipo como Geo->Latitude, Longitude.
É possível adicionar controles ao painel para filtrar dados. Por exemplo, selecione o filtro "Período".
Edite a caixa para selecionar um período padrão.
Você pode adicionar outros controles de lista suspensa para delivery_vehicle_id.
Com esses controles, é possível visualizar o movimento do veículo ou de uma entrega.