O Fleet Engine oferece um serviço simples de geração de registros que permite salvar solicitações de API e payloads de resposta. Com esses registros, é possível depurar da empresa, criar métricas de monitoramento e analisar padrões de tráfego.
O Fleet Engine envia os registros como plataforma registros no Cloud Logging, para poder usar o Cloud ferramentas de geração de registros 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 ligações iniciadas pelo motorista SDK para o Fleet Engine.
Dividir registros para tipos de registro com suporte:
Consulte a documentação para conferir o esquema e as mensagens de registro disponíveis em Geração de registros Referência.
Use buckets de registros restritos e padrão para obedecer às políticas de retenção de dados
Usando "restrito" e "default" os buckets garantem uma imagem clara da sua para uso de dados restrito e irrestrito. Alguns dos dados de registro que o Fleet Engine os envios à Plataforma Google Maps só podem ser retidos por um período limitado, de acordo com o Relatório específico de serviços de mobilidade Termos. Para garantir que você retenha os dados restritos apenas pelo tempo permitido, esses dados devem ser rotulados como TOS_RESTRICTED (o Fleet Engine já faz isso) e registrados em um bucket dedicado chamado "restrito".
Você pode controlar o tempo de retenção e limpar os dados automaticamente a expiração usando as configurações do Cloud Logging. Por exemplo, os registros de uso restrito precisam ser retidas por apenas 30 dias.
Registrar todos os dados irrestritos restantes no "padrão" em um bucket, onde eles podem ser mantidos por períodos mais longos, conforme definido nas Informações específicas sobre serviços de mobilidade Termos (normalmente por 1 ano). Usando "restrito" e "default" de buckets garante uma clareza do seu uso de dados restrito e irrestrito.
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 parent_insert_id.
. É possível usar esse campo para mesclar os dados dos dois registros e receber o
o panorama completo.
Consulte a documentação para conhecer o esquema e as mensagens de registro disponíveis em Geração de registros Referência.
Como ativar o Cloud Logging
O Fleet Engine ativa automaticamente os registros padrão para novos clientes de mobilidade, começando com projetos criados em 10 de fevereiro de 2022. Você pode confirmar se a geração de registros será ativada usando a seguinte consulta na seção Registros Análise :
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
Se não houver registros para essa consulta, talvez o Cloud Logging não tenha sido ativado para seu projeto. Contato suporte, se quiser. para ativar o recurso.
Ativar registros de uso restrito
Os registros de uso restrito são ativados mediante solicitação. Para ativar esses registros para seus serviços Google Cloud, conclua as seguintes etapas:
Preparar seu projeto para receber registros de uso restrito
- No console do Google Cloud, abra a página do 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 _Default e, em seguida, escolha Editar coletor.
- Em "Escolha os registros para filtrar pelo coletor" clique no botão "Adicionar
Exclusão" botão:
- Nome do filtro de exclusão: ExcludeRestrictedLogs
- Filtro de exclusão: labels.restriction="TOS_RESTRICTED"
- Clique em "Atualizar coletor".
- Atualize o bucket de registro restrito 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 Fleet Engine do Routes
- Destino do coletor:
- Serviço do coletor: bucket do Logging
- Selecionar bucket de registros: criar 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" OU resource.type = "fleetengine.googleapis.com/DeliveryFleet") NÃO (labels.restriction = "TOS_RESTRICTED")
- Clique em "Criar coletor".
- Detalhes do coletor:
Entre em contato com o suporte para ativar os registros de uso restrito
Em seguida, entre em contato com dar suporte e fornecer as seguintes informações na sua solicitação de suporte:
- IDs dos projetos a serem ativados:
- Endereço de e-mail da pessoa que está solicitando a alteração:
- Observação: essa pessoa precisa ter acesso para editar os projetos do Google Cloud listados.
- Ao ativar o Conteúdo do Google Maps de uso restrito no Cloud Logging, você concorda aderir à Plataforma Google Maps termos e serviços de mobilidade específicas em inglês, incluindo os requisitos de armazenamento em cache e de uso permitido relacionados ao gerenciamento Conteúdo do Google Maps. Sim / Não
Depois que a equipe de suporte recebe a solicitação, ela envia a confirmação de que o registro foi ativado para seu projeto
Dividir registros de nuvem
O Cloud Logging limita o tamanho dos registros de entrada a 256 KB. O serviço descarta os registros além desse limite. Para garantir que o Cloud Logging retenha grandes registros, a frota Engine podem dividi-los em uma série de registros abaixo do limite de 256 KB. Esses registros têm um ponto em comum insertId para indicar a ordem em que o serviço dividiu o registro menor do registro original muito grande. Depois, é possível reuni-las com base nas insertId.
Para acessar o registro não dividido original, mescle os registros divididos pelos insertIds na ordem original em que foram divididos, conforme indicado pelo índice na entrada de registro na nuvem.
A estrutura do registro dividido é a mesma mencionada em Auditoria dividida
guia de entradas de registros para
Registros de auditoria do Cloud. A principal diferença para registros divididos no Fleet Logging é que
a divisão ocorre no campo jsonPayload, e não no protoPayload
. Confira o exemplo de divisão mostrado na próxima seção.
Tipos de registro compatíveis
O Fleet Engine oferece suporte à divisão de registros apenas para os seguintes tipos de registros com tamanho de registro superior a 256 KB:
Exemplo de estrutura de registro dividido
// 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
}
}
Acessar os registros
Os registros do Cloud são estruturados
LogEntry
. O Fleet Engine envia registros para o Cloud Logging com os LogEntrys
resource.type definido como fleetengine.googleapis.com. Use a guia Registros
Explorer para
gravar consultas para visualizar os registros.
Por exemplo, para visualizar todas as RPCs do Fleet Engine que retornaram um erro, use o método seguinte consulta da Análise de registros:
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
Para visualizar registros de RPCs feitos no método UpdateDeliveryVehicle do
project example-project-id, use a seguinte consulta da Análise de registros:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle"
O exemplo a seguir mostra um LogEntry para o UpdateDeliveryVehicle.
de registro. A solicitação e a resposta de 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á
limpo e o campo errorResponse é 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 do Logging, acesse Consulta do Logging idioma. Para saber como usar seus registros para criar métricas, consulte Visão geral com base em registros e métricas.
Gerenciar os custos do Logging
Depois de ativar o registro, você é responsável por configurar como gostaria para rotear, armazenar e manter seus registros. Pode haver cobranças extras do Google Cloud cobranças pelo registro ingestão e retenção se você exceder os limites de uso e retenção para carga. No entanto, é possível controlar os custos de geração de registros de uma destas maneiras:
Reduzir o uso da geração de registros
É possível limitar a quantidade de ingestão de dados de registro excluindo determinadas entradas de registro.
Exportar ou rotear registros
É possível rotear os registros para outros destinos do Google Cloud ou externos a fim de evitar custos padrão de ingestão e armazenamento. Desative a ingestão de registros, porque descritos na próxima seção, para evitar custos de ingestão.
Desative a ingestão de registros para evitar cobranças
Reduzir o uso da geração de registros, ou exportar ou rotear registros, é preferível em vez de transformar fora da ingestão de registros. No entanto, se você não pretende usar os registros do Fleet Engine, pode evitar possíveis cobranças do Cloud Logging desativando a ingestão. 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 a frota do Compute 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: Cloud Logging exclusões e exclusão registros do Google Cloud. Cloud Logging Exportações e exportação registros
Usar o explorador de registros
Para usar a Análise de registros, abra o console do Cloud, selecione Logging e, em seguida, Análise de registros. Para acessar uma lista de todos os registros do Fleet Engine disponíveis, clique em o tipo de recurso Fleet Engine. Alguns registros da API Delivery são rotulados IDs da tarefa e do veículo de entrega Use esses rótulos para selecionar registros as tarefas ou os veículos do seu interesse.
Filtrar registros por ID do veículo de entrega
Na Análise de registros, use a consulta a seguir para restringir os registros veículo específico:
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
Filtrar registros por ID de tarefa
Na Análise de registros, use a consulta a seguir para restringir os registros uma tarefa específica:
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.task_id=~"task_id"
Filtrar registros de um veículo em um período específico
Na Análise de registros, use a consulta a seguir para restringir os registros a para um veículo durante um período específico:
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"
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 em tarefas criadas ao longo do tempo.
No console do Cloud, selecione Logging e depois Análise de registros para abrir a Análise de registros. Em seguida, aplique o seguinte 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")No painel "Resultados da consulta", selecione o menu suspenso Ações e escolha a Criar métrica.
Na caixa de diálogo do Editor de métricas:
- Especifique um nome de métrica (por exemplo, billable_tasks).
- Especifique uma descrição de métrica (por exemplo, O número de itens faturáveis Tarefas).
- 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 o métrica foi criada com sucesso, e a nova métrica deve aparecer Seção "Métricas definidas pelo usuário". A métrica será preenchida como correspondência registros são gerados.
Selecione o menu suspenso vertical à direita da nova métrica e, em seguida, Selecione Ver no Metrics Explorer.
No painel esquerdo, em "Build Your Query", defina o "Resource Type" como Fleet Engine e procure a métrica billable_tasks.
O gráfico à direita mostra a taxa de chamadas billable_tasks.
Usar o BigQuery
O BigQuery é uma ferramenta poderosa para realizar análises. Ele pode ser usado para armazenar registros de longo prazo e para realizar consultas ad hoc semelhantes a SQL nos dados.
Como rotear registros para o BigQuery
Para utilizar o BigQuery, os registros devem ser roteados para um repositório de dados do BigQuery, conforme da seguinte forma:
No console do Cloud, selecione Logging e depois Análise de registros.
Criar um filtro que isole os registros do Fleet Engine. Na Análise de campo 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", escolha Conjunto de dados do BigQuery.
Na caixa de diálogo "Editar coletor", especifique as seguintes opções:
- Especifique um nome de coletor (por exemplo, FleetEngineLogsSink).
- Deixe "Serviço do coletor" como BigQuery.
- Selecione a opção Usar tabelas particionadas. Isso vai otimizar as consultas desempenho.
- Em "Destino do coletor", selecione Criar novo conjunto de dados do BigQuery e Especifique um nome de conjunto de dados do BigQuery (por exemplo, FleetEngineLogs).
- Clique no botão Criar coletor.
Seus registros vão começar a preencher o conjunto de dados do BigQuery. Confira o dados na seção do BigQuery do console do Cloud.
Várias tabelas do conjunto de dados FleetEngineLogs serão preenchidas automaticamente, um para cada tipo de registro:
- CreateDeliveryVehicle
- GetDeliveryVehicle
- ListDeliveryVehicle
- UpdateDeliveryVehicle
- CreateTask
- GetTask
- UpdateTask
- ListTasks
Os nomes das tabelas usam o seguinte padrão:
project_id.data_set.log_name
Por exemplo, se o nome do projeto for 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 por hora.
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 a cada hora
A consulta a seguir gera uma contagem das paradas quebradas por um veículo por hora.
Por exemplo, esta consulta pode indicar que, na última hora:
- O veículo A fez 10 paradas na 12a hora e 8 paradas na 13a hora.
- O veículo B completou 5 paradas na 11h e 7 paradas na 12h.
O veículo C fez 12 paradas na 13a hora e 9 paradas na 14h.
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, que mostra a porcentagem de sucesso na primeira entrega e a taxa de tentativas.
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 os painéis ser criadas para análise de negócios.
O exemplo a seguir mostra como criar um painel com quais tarefas e veículos os movimentos podem ser visualizados em um mapa.
Iniciar um novo painel do Data Studio e selecionar o BigQuery como os dados uma conexão com a Internet.
Selecione "Consulta personalizada" e escolha o projeto do Cloud para o qual ela deve ser faturada.
Digite a consulta abaixo 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 o tipo de gráfico como Mapa de círculos e, em seguida, selecione o campo de local.
Selecione Criar campo.
Dê um nome ao campo e adicione a seguinte fórmula: CONCAT(lat, ",", lng).
Em seguida, defina o tipo como Geográfico->Latitude, Longitude.
É possível adicionar controles ao painel para filtrar dados. Por exemplo, selecione o filtro "Período".
Edite a caixa "Período" para selecionar um período padrão.
Você pode adicionar outros controles da lista suspensa para delivery_vehicle_id.
Com esses controles, é possível visualizar o movimento do veículo ou as movimento dentro de uma entrega.