Fleet Engine ofrece un servicio de registro simple que te permite guardar sus solicitudes a la API y cargas útiles de respuesta. Con estos registros, puedes depurar tu integración, crear métricas de supervisión y analizar patrones de tráfico.
Fleet Engine envía los registros como registros de plataforma a Cloud Logging para que puedas usar las herramientas de Cloud Logging a fin de acceder a ellos.
Qué registra Fleet Engine
Fleet Engine envía varios datos a Cloud Logging, como los siguientes:
- Todas las respuestas y solicitudes autenticadas de REST y gRPC
- Respuestas de error
- Solicitudes, respuestas y mensajes de error de llamadas que inició el SDK de Driver a Fleet Engine.
- Divide los registros para los tipos de registro compatibles:
Consulta la documentación para ver el esquema y los mensajes de registro disponibles en la Referencia de Logging.
Usa buckets de registros restringidos y predeterminados para cumplir con las políticas de retención de datos
El uso de buckets “restringidos” y “predeterminados” garantiza un panorama claro del uso de datos restringido y no restringido. Es posible que algunos de los datos de registro que Fleet Engine envía a Google Maps Platform solo se retengan durante un período limitado, según las Condiciones Específicas del Servicio de Movilidad. Para asegurarte de conservar los datos restringidos solo durante el tiempo permitido, estos datos deben etiquetarse como TOS_RESTRICTED (Fleet Engine ya lo hace) y registrarse en un bucket dedicado llamado "restringido".
Desde allí, puedes controlar durante cuánto tiempo se retiene y borrar definitivamente los datos de forma automática al momento de su vencimiento mediante la configuración de Cloud Logging. Por ejemplo, los registros de uso restringido solo deben retenerse durante 30 días.
Registra todos los datos restantes sin restricciones en el bucket "predeterminado", en el que se podrán conservar durante más tiempo, como se define en los Términos específicos del servicio de movilidad (por lo general, durante 1 año). El uso de buckets “restringidos” y “predeterminados” garantiza un panorama claro del uso de datos restringido y no restringido.
Envía todos los datos de registro restantes sin restricciones al bucket “predeterminado”, en el que pueden permanecer indefinidamente.
Combina los registros restringidos y no restringidos para obtener una vista completa
Los registros de uso restringido contienen los datos de uso restringido y una referencia al registro predeterminado para que se puedan considerar juntos. El registro de uso restringido contiene el insertId del registro predeterminado como referencia en el campo parent_insert_id. Puedes usar este campo para unir los datos de ambos registros y obtener el panorama completo.
Consulta la documentación para ver todos los mensajes de registro y esquemas disponibles en la Referencia de Logging.
Habilitar Cloud Logging
Fleet Engine habilita de forma automática los registros predeterminados para clientes de movilidad nuevos a partir de los proyectos creados el 10 de febrero de 2022. Puedes confirmar si el registro está habilitado mediante la siguiente consulta en el Explorador de registros :
resource.type:"fleetengine.googleapis.com"
Si no ves ningún registro para esa consulta, es posible que Cloud Logging no se haya habilitado para tu proyecto. Comunícate con el equipo de asistencia si deseas habilitar la función.
Habilita registros de uso restringido
Los registros de uso restringido se habilitan a pedido. Para habilitar estos registros en tu proyecto de Google Cloud, completa los siguientes pasos:
Prepara tu proyecto para recibir registros de uso restringido
- En la consola de Google Cloud, abre la página Enrutador de registros.
- Actualiza el bucket de registros _Default para excluir los registros de uso restringido.
- Selecciona el _Bucket de registro predeterminado y, luego, elige Editar receptor.
- En la sección “Elige registros para filtrar fuera del receptor”, haz clic en el botón “Agregar exclusión”:
- Nombre del filtro de exclusión: ExcludeRestrictedLogs
- Filtro de exclusión: labels.restriction="TOS_RESTRICTED"
- Haz clic en “Actualizar receptor”.
- Actualiza el bucket de registro restringido para almacenar los registros de uso restringido.
- En la página Enrutador de registros, selecciona “Crear receptor”.
- Crea un receptor con la siguiente configuración:
- Detalles del receptor:
- Nombre: RestrictedLogs
- Descripción: registros de uso restringido de Routes Fleet Engine
- Destino del receptor:
- Servicio del receptor: Bucket de Logging
- Selecciona un bucket de registros: Crea un bucket de registros nuevo
- Nombre: Restringido
- Descripción: Contiene registros de uso restringido de Fleet Engine
- Período de retención: 30 días
- Nota: El período de retención no debe superar los 30 días.
- Registros para incluir en el receptor: déjalos vacíos
- Registros para filtrar fuera del receptor: Haz clic en “Agregar exclusión”.
- Nombre del filtro de exclusión: ExcludeNonRestrictedLogs
- Filtro de exclusión: NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliveryFleet") NO (labels.restriction = "TOS_RESTRICTED")
- Haz clic en “Crear un receptor”.
- Detalles del receptor:
Comunícate con el equipo de asistencia para habilitar los registros de uso restringido
Luego, comunícate con el equipo de asistencia y proporciona la siguiente información en la solicitud de asistencia:
- IDs de los proyectos que se habilitarán:
- Dirección de correo electrónico de la persona que solicita el cambio:
- Nota: Esta persona debe tener acceso de edición a los proyectos de Google Cloud enumerados.
- Si habilitas el Contenido de Google Maps de uso restringido en Cloud Logging, aceptas cumplir con las condiciones de Google Maps Platform y las condiciones específicas del servicio de movilidad, incluidos los requisitos de almacenamiento en caché y uso permitido en relación con el Contenido de Google Maps. Sí / No
Una vez que el equipo de asistencia al cliente recibe tu solicitud, envía la confirmación de que se habilitó el registro para el proyecto
Dividir registros en la nube
Cloud Logging limita el tamaño de los registros entrantes a 256 KB. El servicio descarta los registros más allá de ese umbral. Para garantizar que Cloud Logging conserve registros grandes, Fleet Engine puede dividirlos en una serie de registros por debajo del umbral de 256 KB. Esos registros tienen un prefijo insertId común para indicar el orden en el que el servicio dividió el registro más pequeño del registro original de gran tamaño. Luego, puedes volver a unirlos en función de su insertId.
Para acceder al registro original sin dividir, combina los registros divididos según sus insertId en el orden original en que se dividieron, como lo indica su índice en la entrada de registro de Cloud.
La estructura de registros divididos es la misma que la que se menciona en la guía sobre entradas de registros de auditoría dividida para los registros de auditoría de Cloud. La principal diferencia para los registros divididos en Fleet Logging es que la división se produce en el campo jsonPayload, en lugar de hacerlo en el campo protoPayload. Consulta el ejemplo de división que se muestra en la siguiente sección.
Tipos de registros admitidos
Fleet Engine solo admite la división de registros para los siguientes tipos de registros cuyo tamaño supera los 256 KB:
Ejemplo de estructura 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
}
}
Accede a tus registros
Los registros de Cloud se estructuran en torno al formato LogEntry. Fleet Engine envía registros a Cloud Logging con el resource.type de LogEntry establecido en fleetengine.googleapis.com. Puedes usar el Explorador de registros para escribir consultas y ver tus registros.
Por ejemplo, para ver todas las RPC a Fleet Engine que mostraron un error, usa la siguiente consulta del Explorador de registros:
resource.type:"fleetengine.googleapis.com"
severity=ERROR
Si quieres ver los registros de las RPC realizadas al método UpdateVehicle para el
proyecto example-project-id, usa la siguiente consulta del Explorador de registros:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle"
En el siguiente ejemplo, se muestra una LogEntry para el registro UpdateVehicle. La solicitud y la respuesta de RPC se encuentran dentro 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.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"
}
Si se muestra un error de RPC, el campo responseVehicle se borra, y el campo errorResponse se configura y se propaga dentro de 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 obtener más información sobre el lenguaje de consulta de registro, consulta Lenguaje de consulta de Logging . Si deseas obtener información sobre cómo puedes usar tus registros para crear métricas, consulta Descripción general de las métricas basadas en registros.
Administra los costos de los registros
Una vez que se habilita el registro, eres responsable de configurar la forma en la que deseas enrutar, almacenar y retener tus registros. Es posible que se generen cargos adicionales de Google Cloud por la transferencia y retención de registros si superas los límites de uso y retención sin cargo. Sin embargo, puedes controlar los costos de los registros mediante una de las siguientes opciones:
Reduce el uso de registros
Puedes limitar la cantidad de transferencia de datos de registro si excluyes ciertas entradas de registro.
Exportar o enrutar registros
Puedes enrutar los registros a otros destinos de Google Cloud o externos para evitar los costos predeterminados de transferencia y almacenamiento. Asegúrate de desactivar la transferencia de registros, como se describe en la siguiente sección, para evitar costos de transferencia.
Desactiva la transferencia de registros para evitar cargos
Es preferible reducir el uso de registros, o bien exportarlos o enrutarlos, en lugar de desactivar la transferencia de registros. Sin embargo, si no pretendes usar registros de Fleet Engine, puedes desactivar la transferencia para evitar posibles cargos de Cloud Logging. De forma predeterminada, los registros de Fleet Engine se enrutan al bucket de registros _Default.
El siguiente comando actualiza el bucket de registro predeterminado para no transferir los registros de 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 obtener más información, consulta Exclusiones de Cloud Logging y Cómo excluir registros. Exportaciones de Cloud Logging y Exporta registros
Usar el Explorador de registros
Para usar el Explorador de registros, abre Cloud Console, selecciona Logging y, luego, Explorador de registros. Para ver una lista de todos los registros de Fleet Engine disponibles, haz clic en el tipo de recurso Fleet Engine. Algunos registros de la API están etiquetados con un ID de viaje y un ID de vehículo. Puedes usar estas etiquetas para seleccionar registros de los viajes o vehículos que te interesan.
Filtrar registros por ID de vehículo
En el Explorador de registros, puedes usar la siguiente consulta para restringir los registros a un vehículo específico:
resource.type="fleetengine.googleapis.com/Fleet"
labels.vehicle_id="vehicle_id"
Filtrar registros por ID de viaje
En el Explorador de registros, puedes usar la siguiente consulta para restringir los registros a un viaje específico:
resource.type="fleetengine.googleapis.com/Fleet"
labels.trip_id=~"trip_id"
Filtra los registros de un vehículo durante un período específico
En el Explorador de registros, puedes usar la siguiente consulta para restringir los registros a los de un vehículo durante un 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"
Ejemplo de métricas basadas en registros
En el siguiente ejemplo, se muestra cómo usar métricas basadas en registros para hacer un seguimiento de la cantidad de viajes creados a lo largo del tiempo.
En la consola de Cloud, selecciona Logging y, luego, Explorador de registros para abrirlo. Luego, aplica el siguiente filtro:
resource.type="audited_resource" resource.labels.method="maps.fleetengine.v1.TripService.ReportBillableTrip"En el panel Resultados de la consulta, selecciona el menú desplegable Acciones y, luego, selecciona Crear métrica.
En el diálogo Editor de métricas, haz lo siguiente:
- Especifica un nombre de métrica (por ejemplo, billable_trips).
- Especifica una descripción de métrica (por ejemplo, La cantidad de llamadas de viajes facturables).
- Deja en blanco la opción Unidades. _ Deja la opción Tipo como Contador.
Luego, selecciona el botón Crear métrica.
En la página de métricas basadas en registros, deberías ver un mensaje que confirma que la métrica se creó correctamente y que la métrica nueva debería aparecer en la sección Métricas definidas por el usuario. La métrica se propagará ahora a medida que se generen registros coincidentes.
Selecciona el menú desplegable vertical a la derecha de la métrica nueva y, luego, selecciona Ver en el Explorador de métricas.
En el panel izquierdo, debajo de Build Your Query, configura el tipo de recurso como Fleet Engine y busca la métrica billable_trips.
El gráfico de la derecha muestra la tarifa de llamadas billable_trips.
Usar BigQuery
BigQuery es una herramienta potente para realizar análisis. Se puede usar para almacenar registros a largo plazo y realizar consultas ad hoc similares a los de SQL en los datos.
Enruta los registros a BigQuery
Para aprovechar BigQuery, los registros se deben enrutar a un almacén de datos de BigQuery de la siguiente manera:
En la consola de Cloud, selecciona Logging y, luego, Explorador de registros.
Crea un filtro que aísle los registros de Fleet Engine. En el explorador de campos de registros, selecciona el tipo de recurso Fleetengine.googleapis.com/Fleet.
En el panel Resultados de la consulta, haz clic en el menú desplegable Acciones y elige Crear receptor.
En el diálogo Seleccionar el servicio del receptor, elige Conjunto de datos de BigQuery.
En el cuadro de diálogo Editar receptor, especifica las siguientes opciones:
- Especifica un nombre de receptor (por ejemplo, FleetEngineLogsSink).
- Deja Servicio del receptor como BigQuery.
- Selecciona la opción Usar tablas particionadas. Esto aumentará el rendimiento de las consultas.
- En Destino del receptor, selecciona Crear nuevo conjunto de datos de BigQuery y, luego, especifica un nombre para el conjunto de datos de BigQuery (por ejemplo, FleetEngineLogs).
- Haz clic en el botón Crear receptor.
Ahora tus registros deberían comenzar a propagarse en el conjunto de datos de BigQuery. Puedes ver los datos en la sección BigQuery de Cloud Console.
Se propagarán automáticamente varias tablas del conjunto de datos FleetEngineLogs, una para cada tipo de registro:
- CreateVehicle
- GetVehicle
- ListVehicles
- SearchVehicles
- UpdateVehicle
- CreateTrip
- GetTrip
- UpdateTrip
- ListTrips
Los nombres de las tablas usan el siguiente patrón:
project_id.data_set.log_name
Por ejemplo, si el proyecto se llama test_project y el nombre del conjunto de datos es FleetEngineLogs, la tabla CreateTrip tiene el siguiente nombre:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_trip
Consultas de ejemplo
En esta sección, se muestran ejemplos de las consultas que puedes crear.
Viajes creados por hora
La siguiente consulta cuenta la cantidad de registros de CreateTrips y los 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
Cantidad de paradas por vehículo por hora
La siguiente consulta genera un recuento de las paradas en las que entregó un vehículo, desglosadas por hora.
Por ejemplo, esta consulta podría indicarnos que en la última hora:
- El vehículo A completó 10 paradas en la hora 12 y 8 paradas en la hora 13.
- El vehículo B completó 5 paradas en la hora 11 y 7 paradas en la hora 12.
El vehículo C completó 12 paradas en la hora 13 y 9 paradas en la 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
Paneles de Data Studio
BigQuery se puede integrar en herramientas de inteligencia empresarial y se pueden crear paneles para las estadísticas empresariales.
En el siguiente ejemplo, se muestra cómo crear un panel en el que se puedan visualizar recorridos y movimientos de vehículos en un mapa.
Inicia un panel de Data Studio nuevo y selecciona BigQuery como la conexión de datos.
Selecciona Consulta personalizada y elige el proyecto de Cloud al que se debe facturar.
Ingresa la siguiente consulta en el cuadro 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`Selecciona el tipo de gráfico Bubble Map y, luego, el campo de ubicación.
Selecciona Crear campo.
Asígnale un nombre al campo y agrega la siguiente fórmula: CONCAT(lat, ",", lng).
A continuación, establece el tipo de texto en Geo->Latitude, Longitude.
Puedes agregar controles al panel para filtrar los datos. Por ejemplo, selecciona el filtro Período.
Edita la casilla de período para seleccionar un período predeterminado.
Puedes agregar controles de lista desplegables adicionales para Vehicle_id.
Con estos controles, puedes visualizar el movimiento del vehículo o el movimiento en un viaje.