Fleet Engine предлагает простую службу ведения журналов, которая позволяет сохранять запросы API и полезные данные ответов. С помощью этих журналов вы можете отлаживать интеграцию, создавать показатели мониторинга и анализировать модели трафика.
Fleet Engine отправляет журналы в виде журналов платформы в Cloud Logging , чтобы вы могли использовать инструменты Cloud Logging для доступа к ним.
Что регистрирует Fleet Engine
Fleet Engine отправляет в Cloud Logging несколько фрагментов информации, например:
- Все аутентифицированные запросы и ответы REST и gRPC.
- Реакции на ошибки
- Запросы, ответы и сообщения об ошибках от вызовов, инициированных Driver SDK к Fleet Engine.
Разделить журналы для поддерживаемых типов журналов:
Доступные сообщения журнала и схему см. в документации по журналированию .
Используйте сегменты журналов с ограниченным доступом и сегменты по умолчанию для соблюдения политик хранения данных.
Использование сегментов «ограниченно» и «по умолчанию» обеспечивает четкое представление об ограниченном и неограниченном использовании данных. Некоторые данные журнала, которые Fleet Engine отправляет на платформу Google Maps, могут храниться только в течение ограниченного периода времени в соответствии с Особыми условиями мобильного сервиса . Чтобы гарантировать, что вы сохраняете данные с ограниченным доступом только в течение разрешенного периода времени, такие данные должны быть помечены как TOS_RESTRICTED (Fleet Engine уже делает это) и регистрироваться в выделенном сегменте под названием «restricted».
Отсюда вы можете контролировать продолжительность его хранения и автоматически удалять его по истечении срока действия с помощью настроек облачного журнала. Например, журналы ограниченного использования следует хранить только в течение 30 дней.
Запишите все оставшиеся неограниченные данные в корзину «по умолчанию», где они могут храниться в течение более длительного периода, как определено в Особых условиях использования мобильных услуг (обычно в течение 1 года). Использование сегментов «ограниченно» и «по умолчанию» обеспечивает четкое представление об ограниченном и неограниченном использовании данных.
Получите полное представление, объединив журналы с ограниченным и неограниченным доступом.
Журналы ограниченного использования содержат данные ограниченного использования и ссылку на журнал по умолчанию, чтобы их можно было рассматривать вместе. Журнал ограниченного использования содержит идентификатор вставки журнала по умолчанию в качестве ссылки в поле parent_insert_id . Вы можете использовать это поле, чтобы объединить данные из обоих журналов и получить полную картину.
См. документацию по всем доступным сообщениям журнала и схеме в Справочнике по журналированию .
Включение облачного ведения журнала
Fleet Engine автоматически включает журналы по умолчанию для новых клиентов Mobility, начиная с проектов, созданных 10 февраля 2022 года. Вы можете проверить, включено ли ведение журналов, используя следующий запрос в обозревателе журналов :
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
Если вы не видите журналов для этого запроса, возможно, для вашего проекта не включено ведение журнала в облаке. Если вы хотите включить эту функцию, обратитесь в службу поддержки .
Включить журналы ограниченного использования
Журналы ограниченного использования включаются по запросу. Чтобы включить эти журналы для вашего проекта Google Cloud, выполните следующие действия:
Подготовьте свой проект к получению журналов ограниченного использования.
- В консоли Google Cloud откройте страницу Log Router.
- Обновите сегмент журналирования _Default, чтобы исключить журналы ограниченного использования.
- Выберите сегмент журналирования _Default, а затем выберите «Редактировать приемник» .
- В разделе «Выбор журналов для фильтрации из приемника» нажмите кнопку «Добавить исключение»:
- Имя фильтра исключения: ExcludeRestrictedLogs
- Фильтр исключения: labels.restriction="TOS_RESTRICTED"
- Нажмите «Обновить сток».
- Обновите сегмент ограниченного журнала, чтобы хранить журналы ограниченного использования.
- На странице Маршрутизатор журналов выберите «Создать приемник».
- Создайте приемник со следующими настройками:
- Детали раковины:
- Имя: RestrictedLogs
- Описание: Журналы ограниченного использования Routes Fleet Engine.
- Назначение раковины:
- Служба раковины: Ведро для лесозаготовок
- Выберите сегмент журнала: Создать новый сегмент журнала.
- Название: Ограничено
- Описание: Содержит журналы ограниченного использования Fleet Engine.
- Срок хранения: 30 дней
- Примечание. Срок хранения не должен превышать 30 дней.
- Журналы для включения в сток: оставьте пустыми
- Журналы для фильтрации из приемника: нажмите «Добавить исключение».
- Имя фильтра исключения: ExcludeNonRestrictedLogs.
- Фильтр исключения: НЕ (resource.type = "fleetengine.googleapis.com/Fleet" ИЛИ resources.type = "fleetengine.googleapis.com/DeliveryFleet") НЕ (labels.restriction = "TOS_RESTRICTED")
- Нажмите «Создать раковину»
- Детали раковины:
Обратитесь в службу поддержки, чтобы включить журналы ограниченного использования.
Затем обратитесь в службу поддержки и предоставьте следующую информацию в своем запросе на поддержку:
- Идентификаторы проектов, которые позволяют:
- Адрес электронной почты лица, запрашивающего изменение:
- Примечание. Этот человек должен иметь доступ к редактированию перечисленных проектов Google Cloud.
- Включив Контент Google Maps с ограниченным использованием в Cloud Logging, вы соглашаетесь соблюдать условия платформы Google Maps и специальные условия службы мобильных устройств , включая требования к кэшированию и разрешенному использованию в отношении Контента Google Maps. Да нет
Как только служба поддержки получит ваш запрос, она отправит подтверждение того, что для вашего проекта включено ведение журнала.
Разделение облачных журналов
Cloud Logging ограничивает размер входящих журналов до 256 КБ. Служба удаляет журналы, превышающие этот порог. Чтобы гарантировать, что Cloud Logging сохраняет большие журналы, Fleet Engine может разделить их на серию журналов размером менее 256 КБ. Такие журналы имеют общий префикс InsertId , указывающий порядок, в котором служба отделяет меньший журнал от исходного журнала увеличенного размера. Затем вы можете снова соединить их вместе на основе их InsertId .
Чтобы получить доступ к исходному неразделенному журналу, объедините разделенные журналы по их InsertId в исходном порядке, в котором они были разделены, как указано их индексом в записи облачного журнала.
Структура разделенного журнала аналогична структуре, упомянутой в руководстве по записям журнала разделенного аудита для журналов облачного аудита. Основное отличие разделения журналов в Fleet Logging заключается в том, что разделение происходит в поле jsonPayload , а не в поле protoPayload . См. пример разделения, показанный в следующем разделе.
Поддерживаемые типы журналов
Fleet Engine поддерживает разделение журналов только для следующих типов журналов, размер которых превышает 256 КБ:
Пример структуры разделенного журнала
// 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
}
}
Доступ к вашим журналам
Облачные журналы структурированы на основе формата LogEntry . Fleet Engine отправляет журналы в Cloud Logging, при этом для resource.type LogEntry установлено значение fleetengine.googleapis.com . Вы можете использовать обозреватель журналов для написания запросов для просмотра журналов.
Например, чтобы просмотреть все вызовы RPC для Fleet Engine, возвратившие ошибку, используйте следующий запрос Logs Explorer:
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
Чтобы просмотреть журналы RPC, выполненных в методе UpdateDeliveryVehicle для проекта example-project-id, используйте следующий запрос Logs Explorer:
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle"
В следующем примере показан LogEntry для журнала UpdateDeliveryVehicle . Запрос и ответ RPC расположены внутри поля 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"
}
Если возвращается ошибка RPC, поле responseDeliveryVehicle очищается, а поле errorResponse устанавливается и заполняется в 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"
}
Дополнительные сведения о языке запросов журналирования см. в разделе Язык запросов журналирования . Информацию о том, как использовать журналы для создания метрик, см. в разделе Обзор метрик на основе журналов .
Управляйте затратами на регистрацию
После включения ведения журнала вы несете ответственность за настройку способа маршрутизации, хранения и хранения журналов. С вас может взиматься дополнительная плата Google Cloud за прием и хранение журналов, если вы превысите ограничения на использование и хранение бесплатно. Однако вы можете контролировать затраты на ведение журнала, выполнив одно из следующих действий:
Уменьшите использование журналов
Вы можете ограничить объем приема данных журнала, исключив определенные записи журнала.
Экспортировать или маршрутизировать журналы
Вы можете направлять журналы в другие Google Cloud или внешние места назначения, чтобы избежать затрат на прием и хранение по умолчанию. Обязательно отключите прием журналов, как описано в следующем разделе, чтобы избежать затрат на прием.
Отключите прием журналов, чтобы избежать расходов.
Сокращение использования журналов, а также экспорт или маршрутизация журналов предпочтительнее, чем отключение приема журналов. Однако, если вы не собираетесь использовать журналы Fleet Engine, вы можете избежать потенциальных расходов на ведение журналов в облаке, отключив прием. По умолчанию журналы Fleet Engine направляются в корзину журналов _Default.
Следующая команда обновляет сегмент журналов _Default, чтобы журналы 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"''
Дополнительные сведения см. в разделах «Исключения облачного ведения журналов» и «Исключение журналов» . Экспорт облачных журналов и экспорт журналов
Используйте обозреватель журналов
Чтобы использовать обозреватель журналов, откройте Cloud Console, выберите «Ведение журналов» , а затем «Обозреватель журналов» . Чтобы просмотреть список всех доступных журналов Fleet Engine, щелкните Тип ресурса Fleet Engine . Некоторые журналы API доставки помечены идентификатором задачи и идентификатором средства доставки. Вы можете использовать эти метки для выбора журналов по интересующим вас задачам или транспортным средствам.
Фильтрация журналов по идентификатору средства доставки
В обозревателе журналов можно использовать следующий запрос, чтобы ограничить журналы конкретным транспортным средством: none resource.type="fleetengine.googleapis.com/DeliveryFleet" labels.delivery_vehicle_id="delivery_vehicle_id"
Фильтрация журналов по идентификатору задачи
В обозревателе журналов можно использовать следующий запрос, чтобы ограничить журналы конкретной задачей: none resource.type="fleetengine.googleapis.com/DeliveryFleet" labels.task_id=~"task_id"
Фильтрация журналов по транспортному средству за определенный период времени
В обозревателе журналов вы можете использовать следующий запрос, чтобы ограничить журналы только для транспортного средства за определенный период времени: 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"
Пример показателей на основе журнала
В следующем примере показано, как использовать метрики на основе журналов для отслеживания количества задач, созданных с течением времени.
В облачной консоли выберите «Ведение журналов» , а затем «Обозреватель журналов» , чтобы открыть обозреватель журналов. Затем примените следующий фильтр:
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")На панели «Результаты запроса» выберите раскрывающийся список «Действия» , а затем выберите « Создать метрику» .
В диалоговом окне Редактор метрик:
- Укажите имя метрики (например, billable_tasks ).
- Укажите описание метрики (например, «Количество оплачиваемых задач »).
- Оставьте параметр «Единицы измерения» пустым. _ Оставьте для параметра «Тип» значение « Счетчик» .
Затем нажмите кнопку «Создать метрику» .
На странице «Метрики на основе журналов» вы должны увидеть сообщение, подтверждающее успешное создание метрики, а новая метрика должна появиться в разделе «Метрики, определяемые пользователем». Теперь метрика будет заполняться по мере создания соответствующих журналов.
Выберите вертикальный раскрывающийся список справа от новой метрики, а затем выберите «Просмотреть в обозревателе метрик» .
На левой панели в разделе «Создание запроса» установите для параметра «Тип ресурса» значение «Fleet Engine» и найдите метрику billable_tasks.
На графике справа показана частота вызовов billable_tasks.
Использование BigQuery
BigQuery — мощный инструмент для проведения аналитики. Его можно использовать для хранения долгосрочных журналов и для выполнения специальных SQL-запросов к данным.
Маршрутизация журналов в BigQuery
Чтобы воспользоваться преимуществами BigQuery, журналы необходимо направить в хранилище данных BigQuery следующим образом:
В облачной консоли выберите «Ведение журналов» , а затем «Обозреватель журналов» .
Создайте фильтр, изолирующий журналы Fleet Engine. В проводнике полей журналов выберите тип ресурса Fleetengine.googleapis.com/DeliveryFleet .
На панели «Результаты запроса» щелкните раскрывающийся список «Действия» и выберите «Создать приемник» .
В диалоговом окне «Выбор службы приемника» выберите набор данных BigQuery .
В диалоговом окне «Редактировать приемник» укажите следующие параметры:
- Укажите имя приемника (например, FleetEngineLogsSink ).
- Оставьте Sink Service как BigQuery .
- Выберите параметр «Использовать секционированные таблицы» . Это повысит производительность запросов.
- В разделе «Назначение приемника» выберите « Создать новый набор данных BigQuery» , а затем укажите имя набора данных BigQuery (например, FleetEngineLogs ).
- Нажмите кнопку «Создать раковину» .
Теперь ваши журналы должны начать заполнять набор данных BigQuery. Вы можете просмотреть данные в разделе BigQuery Cloud Console.
Несколько таблиц в наборе данных FleetEngineLogs будут заполнены автоматически, по одной для каждого типа журнала:
- СоздатьДоставкуТранспортное средство
- ПолучитьДоставкаАвтомобиль
- СписокДоставкаАвтомобиль
- ОбновлениеДоставкаАвтомобиль
- Создать задачу
- GetTask
- Обновление задачи
- Список задач
- Поиск задач
В именах таблиц используется следующий шаблон:
project_id.data_set.log_name
Например, если проект называется test_project , а имя набора данных — FleetEngineLogs , таблица CreateTask будет иметь следующее имя:
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_task
Примеры запросов
В этом разделе показаны примеры запросов, которые вы можете создать.
Задач создано в час
Следующий запрос подсчитывает количество журналов CreateTasks и группирует их по часам. 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 #### Количество остановок на транспортное средство в час
Следующий запрос генерирует количество остановок, пройденных транспортным средством, с разбивкой по часам.
Например, этот запрос может указать, что за последний час:
- Транспортное средство А совершило 10 остановок за 12-й час и 8 остановок за 13-й час.
- Транспортное средство B совершило 5 остановок за 11 час и 7 остановок за 12 час.
Транспортное средство C совершило 12 остановок за 13-й час и 9 остановок за 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
Уровень успешных первых родов
Следующий запрос, который показывает процент успеха при первой попытке доставки.
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
Панели управления Datastudio
BigQuery можно интегрировать с инструментами бизнес-аналитики, а для бизнес-аналитики можно создавать информационные панели.
В следующем примере показано, как создать информационную панель, на которой задачи и движения транспортных средств можно визуализировать на карте.
Запустите новую панель управления Datastudio и выберите BigQuery в качестве подключения к данным.
Выберите «Пользовательский запрос» и выберите облачный проект, которому должен быть выставлен счет.
Введите следующий запрос в поле запроса.
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`
Выберите тип диаграммы « Пузырьковая карта» , а затем выберите поле местоположения.
Выберите Создать поле .
Назовите поле и добавьте следующую формулу: CONCAT(lat, ",", lng) .
Затем установите тип Geo->Latitude, Longitude .
Вы можете добавить элементы управления на панель мониторинга для фильтрации данных. Например, выберите фильтр «Диапазон дат».
Отредактируйте поле диапазона дат, чтобы выбрать диапазон дат по умолчанию.
Вы можете добавить дополнительные элементы управления раскрывающимся списком для Delivery_vehicle_id.
С помощью этих элементов управления вы можете визуализировать движение транспортного средства или движение внутри доставки.