O Fleet Engine oferece um serviço de geração de registros simples que permite salvar as solicitações de API e os payloads de resposta. Com esses registros, é possível depurar a 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.
- Dividir registros para os tipos de registro compatíveis:
Consulte a documentação das mensagens de registro e do 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
O uso de 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 do Mobile. Para garantir que você mantenha os dados restritos apenas pelo tempo permitido, eles precisam ser rotulados como TOS_RESTRICTED (o Fleet Engine já faz isso) e registrados em um bucket dedicado chamado "restrito".
A partir daí, é possível controlar por quanto tempo eles são retidos e limpar automaticamente após a expiração usando as configurações do Cloud Logging. Por exemplo, os registros de uso restrito devem ser retidos por apenas 30 dias.
Registre todos os dados irrestritos restantes no bucket "padrão", onde eles podem ser retidos por períodos mais longos, conforme definido nos Termos específicos de serviço do Mobility (normalmente por um ano). O uso de buckets "restritos" e "padrão" garante uma visão clara do uso de dados restrito e irrestrito.
Enviar todos os dados de registro irrestritos restantes para o bucket "padrão", onde 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 eles possam ser considerados juntos. O registro de uso restrito
contém o insertId do registro padrão como uma referência no campo
parent_insert_id. É possível usar 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.
Ativar o Cloud Logging
O Fleet Engine ativa automaticamente os registros padrão para novos clientes do Mobility, começando com projetos criados em 10 de fevereiro de 2022. Confirme se a geração de registros está ativada usando a seguinte consulta no Análise de registros :
resource.type:"fleetengine.googleapis.com"
Se você não vir nenhum registro 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
Registros de uso restrito são ativados mediante solicitação. Para ativar esses registros no seu projeto do Google Cloud, siga estas etapas:
Preparar 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 registro _Default 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 registro restrito para armazenar os registros de uso restrito.
- Na página do 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 armazenamento: 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"
- Detalhes do coletor:
Entre 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 solicitou a mudança:
- 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 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 uso permitido relacionados ao conteúdo do Google Maps. Sim / Não
Assim que a equipe de suporte receber sua solicitação, ela enviará a confirmação de que a geração de registros foi ativada para seu projeto.
Dividir registros da nuvem
O Cloud Logging limita o tamanho dos registros de entrada a 256 KB. O serviço descarta registros além desse limite. Para garantir que o Cloud Logging mantenha registros grandes, o Fleet Engine pode dividi-los em uma série de registros abaixo do limite de 256 KB. Esses registros têm um prefixo insertId comum para indicar a ordem em que o serviço dividiu o registro menor do registro grande original. Você pode voltar a mesclá-las com base no insertId.
Para acessar o registro não dividido original, mescle os registros divididos pelos respectivos insertIds na ordem original em que foram divididos, conforme indicado pelo índice na entrada de registro do Cloud.
A estrutura do registro de divisão é a mesma mencionada no Guia de entradas de registro de auditoria
divididas para os
Registros de auditoria do Cloud. A principal diferença para registros divididos no Fleet Logging é que
a divisão ocorre no campo jsonPayload, não no campo
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 tipos de registro a seguir, com um tamanho maior que 256 KB:
Exemplo de estrutura de registro dividida
// 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
}
}
Acessar os registros
Os registros do Cloud são estruturados com base no formato LogEntry. O Fleet Engine envia registros para o Cloud Logging com o resource.type
do LogEntry definido como fleetengine.googleapis.com. Use a Análise
de registros para
criar consultas para visualizar seus registros.
Por exemplo, para visualizar todas as RPCs para o Fleet Engine que retornaram um erro, use a seguinte consulta da Análise de registros:
resource.type:"fleetengine.googleapis.com"
severity=ERROR
Para ver os registros de RPCs feitas no método UpdateVehicle do
example-project-id do projeto, use a seguinte consulta da Análise de registros:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle"
O exemplo a seguir mostra um LogEntry para o registro UpdateVehicle. A solicitação e a resposta de RPC estão localizadas no 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.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"
}
Se um erro de RPC for retornado, o campo responseVehicle será
limpado e o campo errorResponse será definido e preenchido em 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"
}
Para mais informações sobre a linguagem de consulta do Logging, consulte 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 os custos da 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. Poderá haver cobranças extras do Google Cloud pela ingestão e retenção de registros se você exceder os limites de uso e retenção sem custo financeiro. No entanto, é possível controlar os custos da geração de registros seguindo um destes procedimentos:
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 registros para outros destinos externos ou do Google Cloud para evitar os custos padrão de ingestão e armazenamento. Certifique-se de desativar a ingestão de registros, conforme descrito na próxima seção, para evitar custos de ingestão.
Desative a ingestão de registros para evitar cobranças
É preferível reduzir o uso de 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, 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 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ções de 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 conferir uma lista de todos os registros do Fleet Engine disponíveis, clique no tipo de recurso Fleet Engine. Alguns registros da API são identificados com um ID de viagem e um ID de veículo. Use esses rótulos para selecionar registros das viagens ou veículos do seu interesse.
Filtrar registros por ID do veículo
Na Análise de registros, é possível usar a seguinte consulta para restringir os registros a um veículo específico:
resource.type="fleetengine.googleapis.com/Fleet"
labels.vehicle_id="vehicle_id"
Filtrar registros por ID de viagem
Na Análise de registros, use a consulta a seguir para restringir os registros a uma viagem específica:
resource.type="fleetengine.googleapis.com/Fleet"
labels.trip_id=~"trip_id"
Filtrar registros de um veículo durante um período específico
Na Análise de registros, use a consulta a seguir para restringir os registros àqueles de um veículo durante um período específico:
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"
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 viagens criadas ao longo do tempo.
No Console do Cloud, selecione Logging e, em seguida, Análise de registros para abri-la. Em seguida, aplique o seguinte filtro:
resource.type="audited_resource" resource.labels.method="maps.fleetengine.v1.TripService.ReportBillableTrip"No painel "Resultados da consulta", selecione o menu suspenso Ações e, em seguida, Criar métrica.
Na caixa de diálogo do editor de métricas, faça o seguinte:
- Especifique um nome de métrica (por exemplo, billable_trips).
- Especifique uma descrição de métrica (por exemplo, The number of Billable Trip Calls).
- 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 que a nova métrica deve aparecer na seção "Métricas definidas pelo usuário". A métrica será preenchida à medida que os registros correspondentes forem gerados.
Selecione o menu suspenso vertical no lado direito da nova métrica e escolha 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_trips.
O gráfico à direita mostra a taxa de chamadas billable_trips.
Usar o BigQuery
O BigQuery é uma ferramenta poderosa para análises. Ele pode ser usado para armazenar registros de longo prazo e realizar consultas ad hoc semelhantes a SQL nos dados.
Rotear registros para o BigQuery
Para aproveitar o BigQuery, os registros precisam ser roteados para um repositório de dados do BigQuery, da seguinte maneira:
No Console do Cloud, selecione Logging e, em seguida, Análise de registros.
Criar um filtro que isole os registros do Fleet Engine. Em "Análise de campo de registros", selecione o tipo de recurso Fleetengine.googleapis.com/Fleet.
No painel "Resultados da consulta", clique no menu suspenso "Ações" e escolha Criar coletor.
Na caixa de diálogo "Selecionar serviço de 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 o Serviço do coletor como BigQuery.
- Selecione a opção Usar tabelas particionadas. Isso vai melhorar o desempenho 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 vão começar 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:
- CreateVehicle
- GetVehicle
- ListVehicles
- SearchVehicles
- UpdateVehicle
- CreateTrip
- GetTrip
- UpdateTrip
- ListTrips
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 CreateTrip terá o seguinte nome:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_trip
Exemplos de consultas
Nesta seção, mostramos exemplos de consultas que podem ser criadas.
Viagens criadas por hora
A consulta a seguir conta o número de registros CreateTrips e os agrupa por hora.
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
Número de paradas por veículo por hora
A consulta a seguir gera uma contagem das paradas atendidas por um veículo, detalhadas por hora.
Por exemplo, esta consulta nos diz que, na última hora:
- O Veículo A completou 10 paradas na hora 12 e 8 paradas na hora 13.
- O Veículo B completou 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_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
Painéis do Data Studio
É possível integrar o BigQuery a ferramentas de Business Intelligence e criar painéis para análise de negócios.
O exemplo a seguir mostra como criar um painel em que as viagens e os movimentos do veículo podem ser visualizados em um mapa.
Iniciar um novo painel do Data Studio e selecionar o BigQuery como a conexão de dados.
Selecione "Consulta personalizada" e o projeto do Cloud em que ele será faturado.
Digite a consulta abaixo na caixa de consulta.
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`Selecione "Tipo de gráfico" como Mapa de círculos e depois 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 Geo->Latitude, Longitude.
Você pode 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 na lista suspensa para o veículo_id.
Com esses controles, é possível visualizar o movimento do veículo ou movimento dentro de uma viagem.