記錄

「Fleet Engine」提供簡單的記錄服務，可讓您儲存其 API 要求與回應酬載。您可以利用這些記錄檔對整合進行偵錯、建立監控指標，並分析流量模式。

Fleet Engine 會將記錄檔做為平台記錄檔傳送至 Cloud Logging，方便您使用 Cloud Logging 工具存取記錄。

Fleet Engine 記錄的內容

Fleet Engine 會將多項資訊傳送至 Cloud Logging，例如：

  • 所有通過驗證的 REST 和 gRPC 要求與回應
  • 錯誤回應
  • 由 Driver SDK 對 Fleet Engine 發出的呼叫所發出的要求、回應和錯誤訊息。

如需可用記錄訊息和結構定義的說明文件，請參閱 Logging 參考資料。

使用受限制和預設的記錄檔值區，以符合資料保留政策

使用「限制」和「預設」值區可確保清楚瞭解限制和不受限的數據用量。根據行動管理服務專屬條款，Fleet Engine 傳送至 Google 地圖平台的部分記錄資料可能只保留一段時間。為確保您僅在允許的時間內保留受限資料，Google 建議您將受限資料標示為 TOS_RESTRICTED，並傳送至名為「受限制」的專屬值區。您可以透過 Cloud Logging 設定控管資料的保留時間長度，並在保留期限過後自動清除資料。舉例來說，受限制的使用記錄只能保留 30 天。

將所有剩餘的未受限記錄資料傳送至「預設」值區，該值區可以無限期保留。

合併受限制和未受限制的記錄檔，以便取得完整檢視畫面

限制使用的記錄含有受限制使用的資料，以及預設記錄的參照，因此系統會將這些資料視為會一併考慮。限制使用記錄的 parent_insert_id 欄位中包含預設記錄的 InsertId 做為參照。您可以使用這個欄位彙整兩份記錄的資料，並取得完整資訊。

請參閱 Logging 參考資料中所有可用記錄訊息和結構定義的說明文件。

啟用 Cloud Logging

Fleet Engine 會從 2022 年 2 月 10 日建立的專案開始，自動為新的行動性客戶啟用預設記錄。您可以在「記錄檔探索工具」中使用以下查詢，確認是否已啟用記錄功能：

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

如果未看到該查詢的任何記錄檔，表示您的專案可能未啟用 Cloud Logging。如需啟用這項功能，請與支援團隊聯絡。

啟用限制使用記錄

系統會應要求啟用限制使用的記錄。如要為 GCP 專案啟用這些記錄檔，請完成下列步驟：

為專案準備接收使用限制記錄檔

  1. 在 Google Cloud 控制台中，開啟「記錄檔路由器」頁面。
  2. 更新_Default Logging 值區，排除受限制的使用記錄檔。
    1. 選取 _Default Logging 值區，然後選擇「Edit 接收器」。
    2. 在「選擇要篩除接收器的記錄檔」區段，按一下「新增排除條件」按鈕：
    3. 「排除」篩選器名稱：排除受限制的記錄
    4. 排除篩選器：labels.restriction="TOS_RESTRICTED"
    5. 按一下「更新接收器」。
  3. 更新受限制的記錄值區，以便儲存使用限制記錄檔。
    1. 在「記錄檔路由器」頁面中，選取 [建立接收器]。
    2. 使用以下設定建立接收器：
    3. 接收器詳細資料：
      1. 名稱：Restrictedlogs
      2. 說明：Routes Fleet Engine 受限使用記錄
    4. 接收器目的地：
      1. 接收器服務：Logging 值區
      2. 選取記錄檔值區：建立新的記錄檔值區
      3. 名稱：受限制
      4. 說明：包含 Fleet Engine 限制使用記錄
      5. 保留期限：30 天
      6. 注意：保留期限不得超過 30 天。
    5. 要納入接收器的記錄：保留空白
    6. 要從接收器中排除的記錄：按一下「新增排除條件」。
      1. 「排除」篩選器名稱：排除非受限制的記錄
      2. 排除篩選器：NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliverFleet") NOT (labels.restriction = "TOS_RESTRICTED")
    7. 按一下「建立接收器」

請與支援團隊聯絡，啟用限制使用記錄

接著，請與支援團隊聯絡，並在支援要求中提供下列資訊：

  1. 要啟用的專案 ID：
  2. 要求變更者的電子郵件地址：
    1. 注意事項：這位使用者必須具備上述 GCP 專案的編輯權限。
  3. 在 Cloud Logging 中啟用「受限制的 Google 地圖內容」，即表示您同意遵守《Google 地圖平台條款》和行動資費服務專屬條款，包括與 Google 地圖內容相關的快取和許可使用規定。是/否

支援團隊收到要求後，會傳送確認訊息，通知你專案已啟用記錄功能

存取記錄

Cloud 記錄的結構是以 LogEntry 格式為基礎。當 LogEntry 的 resource.type 設為 fleetengine.googleapis.com 時，Fleet Engine 會將記錄檔傳送至 Cloud Logging。您可以使用記錄檔探索工具撰寫查詢，藉此查看記錄檔。

舉例來說，如要查看傳回錯誤的所有 RPC 至 Fleet Engine，請使用下列 Logs Explorer 查詢：

resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR

如要查看針對專案 example-project-id 的 UpdateDeliveryVehicle 方法進行的 RPC 記錄，請使用下列 Logs Explorer 查詢：

logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_delivery_vehicle"

以下範例顯示 UpdateDeliveryVehicle 記錄的 LogEntry。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 欄位，並在 jsonPayload 中設定並填入 errorResponse 欄位：

    {
      "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"
    }

如要進一步瞭解 Logging 查詢語言，請參閱 Logging 查詢語言。如要瞭解如何使用記錄檔建立指標，請參閱記錄指標總覽。

管理記錄費用

啟用記錄功能後，請負責設定您要如何轉送、儲存及保留記錄檔。如果超出免費用量和保留限制，則記錄擷取和保留作業可能會產生額外的 Google Cloud Platform 費用。不過，您可以採用下列其中一種做法來控管記錄費用：

減少記錄用量

您可以排除特定記錄項目，藉此限制記錄檔資料擷取量。

匯出或路徑記錄

您可以將記錄檔轉送至其他 GCP 或外部目的地，以避免預設的擷取和儲存空間費用。請務必按照下列步驟關閉記錄檔擷取功能，以免擷取費用。

關閉記錄檔擷取功能以免產生費用

比起關閉記錄檔擷取功能，我們建議減少記錄用量或匯出/轉送記錄檔。不過，如果不想使用 Fleet Engine 記錄檔，請關閉擷取功能，避免產生 Cloud Logging 費用。根據預設，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 Logging 排除和排除記錄檔。Cloud Logging 匯出作業和匯出記錄檔

使用記錄檔探索工具

如要使用記錄檔探索工具，請開啟 Cloud 控制台，依序選取「Logging」和「記錄檔探索工具」。如要查看所有可用 Fleet Engine 記錄的清單，請按一下 [Fleet Engine] 資源類型。部分 Delivery API 記錄會標示工作 ID 和運送車輛 ID。您可以使用這些標籤，選取您感興趣的工作或車輛記錄。

記錄檔標籤

依運送車輛 ID 篩選記錄

在記錄檔探索工具中，您可以使用下列查詢，將記錄限制在特定車輛： none resource.type="fleetengine.googleapis.com/DeliveryFleet" labels.delivery_vehicle_id="delivery_vehicle_id" 篩選車輛

依工作 ID 篩選記錄

在記錄檔探索工具中，您可以使用以下查詢，將記錄限制為特定工作： none resource.type="fleetengine.googleapis.com/DeliveryFleet" labels.task_id=~"task_id" 注意：為了確保查詢篩選器能擷取所有記錄，請在查詢中使用 =~ 運算子。如果有多項工作指派給車輛，工作 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. 在 Cloud 控制台中，依序選取「Logging」和「記錄檔探索工具」，以開啟記錄檔探索工具。然後套用下列篩選器：

    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. 在「Query Results」窗格中，選取「Actions」下拉式選單，然後選取「Create Metric」。

    建立指標

  3. 在「指標編輯器」對話方塊中：

    • 指定指標名稱 (例如 billable_tasks)。
    • 指定指標說明 (例如「The number of Billable Tasks」)。
    • 將「Units」選項留空。_ 將「類型」選項保留為「計數器」。

    接著選取「建立指標」按鈕。

  4. 「記錄指標」頁面上會顯示一則訊息，確認指標已成功建立，且新指標應該會顯示在「使用者定義指標」區段中。系統會在產生相符記錄時填入該指標。

  5. 選取新指標右側的垂直下拉式選單，然後選取「View in Metrics Explorer」(在 Metrics Explorer 中查看)。

    查看指標

  6. 在左側窗格的「Build Your Query」下方，將資源類型設為「Fleet Engine」，然後搜尋 billing_tasks 指標。

    搜尋指標

    右側圖表顯示 billing_tasks 呼叫的速率。

使用 BigQuery

BigQuery 是能執行數據分析的強大工具。可用於儲存長期記錄檔，以及對資料執行類似 SQL 的臨時查詢。

將記錄檔轉送至 BigQuery

如要利用 BigQuery，您必須將記錄檔轉送至 BigQuery 資料儲存庫，如下所示：

  1. 在 Cloud 控制台中，依序選取「Logging」和「記錄檔探索工具」。

  2. 建立可以區隔 Fleet Engine 記錄檔的篩選器。在「記錄檔欄位探索工具」中，選取「Fleetengine.googleapis.com/DeliverFleet」資源類型。

    建立篩選器

  3. 在「查詢結果」窗格中，按一下「動作」下拉式選單，然後選擇「建立接收器」。

    建立接收器

  4. 在「選取接收器服務」對話方塊中，選取「BigQuery 資料集」。

    選取接收器

  5. 在「編輯接收器」對話方塊中，指定下列選項：

    • 指定接收器名稱 (例如 FleetEngineLogsSink)。
    • 將接收器服務保留為 BigQuery。
    • 選取「使用分區資料表」選項。這麼做會提高查詢效能。
    • 在「接收器目的地」下方，選取「建立新的 BigQuery 資料集」，然後指定 BigQuery 資料集名稱 (例如「FleetEngine 記錄」)。
    • 按一下 [Create Sink] (建立接收器) 按鈕。

    編輯接收器

您的記錄檔現在應會開始填入 BigQuery 資料集。您可以在 Cloud 控制台的 BigQuery 區段中查看資料。

BigQuery 區段

系統會自動填入 FleetEngine Logs 資料集下的多個資料表，每個記錄類型各有一個資料表：

  • CreateDeliveryVehicle
  • GetDeliveryVehicle
  • ListDeliveryVehicle
  • UpdateDeliveryVehicle
  • CreateTask
  • GetTask
  • UpdateTask
  • ListTasks
  • SearchTasks

資料表名稱採用以下模式：

project_id.data_set.log_name

例如，如果專案的名稱為 test_project，資料集名稱為 FleetEngine 記錄，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

每輛車每小時的轉機次數

下列查詢會產生車輛提供服務的停靠站計數，並按照小時細分。

舉例來說，以下查詢可能指出在過去一小時內：

  • 車輛 A 在第 12 小時完成了 10 個停靠站，第 13 小時完成了 8 個停靠站。
  • 車輛 B 在第 11 小時完成了 5 個停靠站，在 12 小時完成了 7 個停靠站。

  • 車輛 C 在第 13 小時完成了 12 個停靠站，14 小時完成了 9 個停靠站。

    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

數據分析資訊主頁

BigQuery 可與商業智慧工具及資訊主頁整合，方便您建立商業分析用途。

以下範例說明如何建構資訊主頁，以在地圖上視覺化呈現工作和車輛動作。

  1. 啟動新的數據分析資訊主頁，然後選取 BigQuery 做為數據連線。

    數據連線

  2. 依序選取「自訂查詢」和要計費的 Cloud 專案。

    選取專案

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

    然後將類型設為「地理區域->緯度, 經度」。

    組合類型

  4. 你可以在資訊主頁中新增控制項來篩選資料。例如，您可以選取日期範圍篩選器。

    新增控制項

  5. 編輯日期範圍方塊來選取預設日期範圍。

    日期範圍

  6. 您可以為 Delivery_vehicle_id 新增其他下拉式清單控制項。

    下拉式清單

您可以利用這些控制項，以視覺化方式呈現車輛在運送過程或運送中的動作。