логирование

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, могут храниться только в течение ограниченного периода времени в соответствии с Особыми условиями мобильного сервиса . Чтобы гарантировать, что вы храните данные с ограниченным доступом только в течение разрешенного периода времени, Google рекомендует пометить данные с ограниченным доступом как TOS_RESTRICTED и отправить их в специальный контейнер под названием «Ограниченный». Отсюда вы можете контролировать продолжительность его хранения и автоматически удалять его по истечении срока действия с помощью настроек облачного журнала. Например, журналы ограниченного использования следует хранить только в течение 30 дней.

Отправьте все оставшиеся неограниченные данные журнала в корзину «по умолчанию», где они могут оставаться неопределенное время.

Получите полное представление, объединив журналы с ограниченным и неограниченным доступом.

Журналы ограниченного использования содержат данные ограниченного использования и ссылку на журнал по умолчанию, чтобы их можно было рассматривать вместе. Журнал ограниченного использования содержит идентификатор вставки журнала по умолчанию в качестве ссылки в поле parent_insert_id . Вы можете использовать это поле, чтобы объединить данные из обоих журналов и получить полную картину.

См. документацию по всем доступным сообщениям журнала и схеме в Справочнике по журналированию .

Включение облачного ведения журнала

Fleet Engine автоматически включает журналы по умолчанию для новых клиентов Mobility, начиная с проектов, созданных 10 февраля 2022 года. Вы можете проверить, включено ли ведение журналов, используя следующий запрос в обозревателе журналов :

resource.type:"fleetengine.googleapis.com/DeliveryFleet"

Если вы не видите журналов для этого запроса, возможно, для вашего проекта не включено ведение журнала в облаке. Если вы хотите включить эту функцию, обратитесь в службу поддержки .

Включить журналы ограниченного использования

Журналы ограниченного использования включаются по запросу. Чтобы включить эти журналы для вашего проекта GCP, выполните следующие действия:

Подготовьте свой проект к получению журналов ограниченного использования.

  1. В консоли Google Cloud откройте страницу Log Router.
  2. Обновите сегмент журналирования _Default, чтобы исключить журналы ограниченного использования.
    1. Выберите сегмент журналирования _Default, а затем выберите «Редактировать приемник» .
    2. В разделе «Выбор журналов для фильтрации из приемника» нажмите кнопку «Добавить исключение»:
    3. Имя фильтра исключения: ExcludeRestrictedLogs
    4. Фильтр исключения: labels.restriction="TOS_RESTRICTED"
    5. Нажмите «Обновить сток».
  3. Обновите сегмент ограниченного журнала, чтобы хранить журналы ограниченного использования.
    1. На странице Маршрутизатор журналов выберите «Создать приемник».
    2. Создайте приемник со следующими настройками:
    3. Детали раковины:
      1. Имя: RestrictedLogs
      2. Описание: Журналы ограниченного использования Routes Fleet Engine.
    4. Назначение раковины:
      1. Служба раковины: Ведро для лесозаготовок
      2. Выберите сегмент журнала: Создать новый сегмент журнала.
      3. Название: Ограничено
      4. Описание: Содержит журналы ограниченного использования Fleet Engine.
      5. Срок хранения: 30 дней
      6. Примечание. Срок хранения не должен превышать 30 дней.
    5. Журналы для включения в сток: оставьте пустыми
    6. Журналы для фильтрации из приемника: нажмите «Добавить исключение».
      1. Имя фильтра исключения: ExcludeNonRestrictedLogs.
      2. Фильтр исключения: НЕ (resource.type = "fleetengine.googleapis.com/Fleet" ИЛИ resources.type = "fleetengine.googleapis.com/DeliveryFleet") НЕ (labels.restriction = "TOS_RESTRICTED")
    7. Нажмите «Создать раковину»

Обратитесь в службу поддержки, чтобы включить журналы ограниченного использования.

Затем обратитесь в службу поддержки и предоставьте следующую информацию в своем запросе на поддержку:

  1. Идентификаторы проектов, которые позволяют:
  2. Адрес электронной почты лица, запрашивающего изменение:
    1. Примечание. Этот человек должен иметь доступ к редактированию перечисленных выше проектов GCP.
  3. Включив Контент Google Maps с ограниченным использованием в Cloud Logging, вы соглашаетесь соблюдать условия платформы Google Maps и специальные условия службы мобильных устройств , включая требования к кэшированию и разрешенному использованию в отношении Контента Google Maps. Да нет

Как только служба поддержки получит ваш запрос, она отправит подтверждение того, что для вашего проекта включено ведение журнала.

Доступ к вашим журналам

Облачные журналы структурированы на основе формата 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 Platform, если вы превысите ограничения на использование и хранение бесплатно. Однако вы можете контролировать затраты на ведение журнала, выполнив одно из следующих действий:

Уменьшите использование журналов

Вы можете ограничить объем приема данных журнала, исключив определенные записи журнала.

Экспортировать или маршрутизировать журналы

Вы можете направлять журналы в другие GCP или внешние места назначения, чтобы избежать затрат на прием и хранение по умолчанию. Обязательно отключите прием журналов, как описано ниже, чтобы избежать затрат на прием.

Отключите прием журналов, чтобы избежать расходов.

Сокращение использования журналов, а также экспорт или маршрутизация журналов предпочтительнее, чем отключение приема журналов. Однако, если вы не собираетесь использовать журналы 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" Примечание. Значения времени в этом примере указаны в формате всемирного координированного времени (UTC). Чтобы указать часовой пояс, замените букву Z в конце отметки времени на +hh:mm или -hh:mm . Дополнительную информацию см. в документации Cloud .

Пример показателей на основе журнала

В следующем примере показано, как использовать метрики на основе журналов для отслеживания количества задач, созданных с течением времени.

  1. В облачной консоли выберите «Ведение журналов» , а затем «Обозреватель журналов» , чтобы открыть обозреватель журналов. Затем примените следующий фильтр:

    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")

  2. На панели «Результаты запроса» выберите раскрывающийся список «Действия» , а затем выберите «Создать метрику» .

    Создать метрику

  3. В диалоговом окне Редактор метрик:

    • Укажите имя метрики (например, billable_tasks ).
    • Укажите описание метрики (например, «Количество оплачиваемых задач »).
    • Оставьте параметр «Единицы измерения» пустым. _ Оставьте для параметра «Тип» значение «Счетчик» .

    Затем нажмите кнопку «Создать метрику» .

  4. На странице «Метрики на основе журналов» вы должны увидеть сообщение, подтверждающее успешное создание метрики, а новая метрика должна появиться в разделе «Метрики, определяемые пользователем». Теперь метрика будет заполняться по мере создания соответствующих журналов.

  5. Выберите вертикальный раскрывающийся список справа от новой метрики, а затем выберите «Просмотреть в обозревателе метрик» .

    Посмотреть показатель

  6. На левой панели в разделе «Создание запроса» установите для параметра «Тип ресурса» значение «Fleet Engine » и найдите метрику billable_tasks.

    Поисковый показатель

    На графике справа показана частота вызовов billable_tasks.

Использование BigQuery

BigQuery — мощный инструмент для проведения аналитики. Его можно использовать для хранения долгосрочных журналов и для выполнения специальных SQL-запросов к данным.

Маршрутизация журналов в BigQuery

Чтобы воспользоваться преимуществами BigQuery, журналы необходимо направить в хранилище данных BigQuery следующим образом:

  1. В облачной консоли выберите «Ведение журналов» , а затем «Обозреватель журналов» .

  2. Создайте фильтр, изолирующий журналы Fleet Engine. В проводнике полей журналов выберите тип ресурса Fleetengine.googleapis.com/DeliveryFleet .

    Создать фильтр

  3. На панели «Результаты запроса» щелкните раскрывающийся список «Действия» и выберите «Создать приемник» .

    Создать раковину

  4. В диалоговом окне «Выбор службы приемника» выберите набор данных BigQuery .

    Выберите раковину

  5. В диалоговом окне «Редактировать приемник» укажите следующие параметры:

    • Укажите имя приемника (например, FleetEngineLogsSink ).
    • Оставьте Sink Service как BigQuery .
    • Выберите параметр «Использовать секционированные таблицы» . Это повысит производительность запросов.
    • В разделе «Назначение приемника» выберите «Создать новый набор данных BigQuery» , а затем укажите имя набора данных BigQuery (например, FleetEngineLogs ).
    • Нажмите кнопку «Создать раковину» .

    Изменить раковину

Теперь ваши журналы должны начать заполнять набор данных BigQuery. Вы можете просмотреть данные в разделе BigQuery Cloud Console.

Раздел BigQuery

Несколько таблиц в наборе данных 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 можно интегрировать с инструментами бизнес-аналитики, а для бизнес-аналитики можно создавать информационные панели.

В следующем примере показано, как создать информационную панель, на которой задачи и движения транспортных средств можно визуализировать на карте.

  1. Запустите новую панель управления Datastudio и выберите BigQuery в качестве подключения к данным.

    Подключение для передачи данных

  2. Выберите «Пользовательский запрос» и выберите облачный проект, которому должен быть выставлен счет.

    Выберите проект

  3. Введите следующий запрос в поле запроса.

    Введите запрос

    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`

  1. Выберите тип диаграммы «Пузырьковая карта» , а затем выберите поле местоположения.

    Тип диаграммы

  2. Выберите Создать поле .

    Создать поле

  3. Назовите поле и добавьте следующую формулу: CONCAT(lat, ",", lng) .

    Затем установите тип Geo->Latitude, Longitude .

    Тип установки

  4. Вы можете добавить элементы управления на панель мониторинга для фильтрации данных. Например, выберите фильтр «Диапазон дат».

    Добавить элементы управления

  5. Отредактируйте поле диапазона дат, чтобы выбрать диапазон дат по умолчанию.

    Диапазон дат

  6. Вы можете добавить дополнительные элементы управления раскрывающимся списком для Delivery_vehicle_id.

    Выпадающий список

С помощью этих элементов управления вы можете визуализировать движение транспортного средства или движение внутри доставки.