Fleet Engine 提供簡易的記錄服務，可讓您儲存其 API 要求和回應酬載。您可以利用這些記錄檔，針對整合作業進行偵錯、建立監控指標及分析流量模式。
Fleet Engine 會將記錄以平台記錄檔的形式傳送至 Cloud Logging，以便您可以使用 Cloud Logging 工具進行存取。
Fleet Engine 記錄檔
Fleet Engine 會將多項資訊傳送至 Cloud Logging，例如：
- 所有已驗證的 REST 和 gRPC 要求和回應
- 錯誤回應
- 透過驅動程式 SDK 對 Fleet Engine 發出的呼叫發出的要求、回應和錯誤訊息。
針對支援的記錄類型分割記錄檔：
如要瞭解可用的記錄訊息和結構定義，請參閱 Logging 參考資料。
使用受限制和預設的記錄檔值區，以符合資料保留政策
使用「受限制」和「預設」值區，可確保您清楚瞭解受限和未受限的數據用量。根據《行動不便服務專屬條款》，Fleet Engine 傳送至 Google 地圖平台的部分記錄資料只能在限定時間內保留一段時間。為確保您只保留受限資料的時間，這類資料應標示為 TOS_RESTRICTED (Fleet Engine 已執行這項操作)，並記錄名為「受限制」的專屬值區。
透過此工具，您可以控制保留時間長短，並使用 Cloud Logging 設定在到期時自動清除資料。例如，受限制用途的記錄只能保留 30 天。
將所有未受限的資料記錄到「預設」值區，並依據《行動不便服務專屬條款》的定義，保留更長的保留期限 (通常為 1 年)。使用「受限制」和「預設」值區可確保您清楚瞭解受限和未受限的數據用量。
合併受限制和不受限的記錄檔，完整掌握全局
受限制使用記錄包含受限制使用的資料，以及預設記錄的參照，以便系統一併將這些資料納入考量。受限制的使用記錄包含預設記錄的 insertId 做為 parent_insert_id 欄位中的參照。您可以使用這個欄位來彙整兩份記錄中的資料，以取得完整結果。
如要查看所有可用的記錄訊息和結構定義，請參閱 Logging 參考資料。
啟用 Cloud Logging
Fleet Engine 會從 2022 年 2 月 10 日開始建立的專案開始，自動為新的行動管理客戶啟用預設記錄。您可以在「記錄檔探索工具」中使用下列查詢，確認記錄功能是否已啟用：
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
如果您沒有看見該查詢的任何記錄檔，表示您的專案可能尚未啟用 Cloud Logging。如需啟用這項功能，請與支援團隊聯絡。
啟用受限制的使用記錄
受限制的使用記錄會按要求啟用。如要為 Google Cloud 專案啟用這些記錄檔，請完成下列步驟：
準備讓專案接收受限制的記錄檔
- 在 Google Cloud 控制台中，開啟「記錄檔路由器」頁面。
- 更新 _Default 記錄值區，排除受限制的使用記錄檔。
- 選取 _Default logging 值區，然後選擇 [Edit 接收器] (編輯接收器)。
- 在「Choose logs to filter out of PowerShell」(選擇要篩除接收器的記錄檔) 專區中，按一下「Add 排除」(新增排除條件) 按鈕：
- 排除篩選器名稱：ExcludeRestrictedLogs
- 排除篩選器：label.restriction="TOS_RESTRICTED"
- 按一下「更新接收器」。
- 更新限制記錄值區，以便儲存受限制的使用記錄檔。
- 在「記錄檔路由器」頁面中，選取 [建立接收器]。
- 使用下列設定建立接收器：
- 接收器詳細資料：
- 名稱：RestrictedLogs
- 說明：Routes Fleet Engine 限制用途記錄檔
- 接收器目的地：
- 接收器服務：Logging 值區
- 選取記錄檔值區：建立新的記錄檔值區
- 名稱：限制
- 說明：包含 Fleet Engine 限制使用記錄檔
- 保留期限：30 天
- 注意：保留期限不得超過 30 天。
- 要納入接收器的記錄：留空
- 用於篩除接收器的記錄：點選「新增排除條件」
- 排除篩選器名稱：ExcludeNonRestrictedLogs
- 排除篩選條件：NOT (resource.type = "fleetengine.googleapis.com/Fleet" OR resource.type = "fleetengine.googleapis.com/DeliveryFleet") NOT (labels.restriction = "TOS_RESTRICTED")
- 按一下「建立接收器」
- 接收器詳細資料：
與支援團隊聯絡，啟用受限制的使用記錄
接著與支援團隊聯絡，並在支援要求中提供下列資訊：
- 要啟用的專案 ID：
- 要求變更的使用者電子郵件地址：
- 注意：這位使用者應具備所列 Google Cloud 專案的編輯權限。
- 在 Cloud Logging 中啟用受限制的 Google 地圖內容，即代表您同意遵守《Google 地圖平台條款》和《行動不便服務專屬條款》，包括與 Google 地圖內容相關的快取和許可用途規定。是/否
支援團隊收到您的要求後，會傳送確認訊息，確認專案已啟用記錄功能
分割雲端記錄檔
Cloud Logging 會將傳入記錄檔的大小限制在 256 KB。服務會捨棄超過該門檻的記錄檔。如要確保 Cloud Logging 會保留大型記錄檔，Fleet Engine 可將記錄檔分割為低於 256 KB 門檻的一系列記錄檔。這類記錄具有通用的 insertId 前置字串，表示服務從原始超大型記錄檔中拆分較小的記錄的順序。接著，您就可以根據其 insertId 將兩者重新彙整。
如要存取原始的未分割記錄，請按照分割記錄的原始順序，按照其分割的原始順序合併分割記錄的 insertId，如雲端記錄項目中的索引所示。
分割記錄結構與 Cloud 稽核記錄的分割稽核記錄項目指南中提及的結構相同。在機群記錄功能中，分割記錄的主要差異在於，分割是在 jsonPayload 欄位，而不是 protoPayload 欄位。請參閱下一節中的分割範例。
支援的記錄類型
Fleet Engine 僅適用於下列記錄檔類型，且記錄大小超過 256 KB 的記錄分割功能：
分割記錄檔結構範例
// 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
}
}
存取記錄
Cloud 記錄檔是以 LogEntry 格式建構而成。Fleet Engine 會在 LogEntry 的 resource.type 設為 fleetengine.googleapis.com 的情況下，將記錄傳送至 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 查詢語言。如要瞭解如何使用記錄建立指標，請參閱記錄指標總覽。
管理記錄費用
啟用記錄功能後，您必須負責設定轉送、儲存及保留記錄的方式。如果超出用量和保留限制，您可能會產生額外的 Google Cloud 費用，用於擷取記錄與保留記錄檔。不過，您可以採取下列其中一種做法來控制記錄費用：
減少記錄用量
您可以排除特定記錄項目，限制記錄資料擷取的次數。
匯出或轉送記錄
您可以將記錄檔轉送至其他 Google Cloud 或外部目的地，以避免產生預設擷取和儲存空間費用。為了避免擷取費用，請務必關閉記錄擷取功能 (如下節所述)。
關閉記錄檔擷取功能以免產生費用
比起關閉記錄擷取功能，建議減少記錄用量，或是匯出或轉送記錄檔。不過，如果您不想使用 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 篩選記錄
在記錄檔探索工具中，您可以使用下列查詢，將記錄限制在特定車輛中：
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
依工作 ID 篩選記錄檔
在記錄檔探索工具中，您可以使用下列查詢，將記錄限制為特定工作：
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.task_id=~"task_id"
篩選特定時間範圍內的車輛記錄
在記錄檔探索工具中，您可以使用下列查詢，將記錄限制在特定時間範圍內的車輛記錄：
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"
記錄指標範例
以下範例說明如何使用記錄指標追蹤隨時間建立的工作數量。
在 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")在「Query Results」窗格中，選取「Actions」下拉式選單，然後選取「Create Metric」。
在「指標編輯工具」對話方塊中：
- 指定指標名稱 (例如 billable_tasks)。
- 指定指標說明 (例如「可計費任務數量」)。
- 將「Units」選項留空。_ 將「Type」(類型) 選項保留為「Counter」(計數器)。
接著，選取「建立指標」按鈕。
在「記錄指標」頁面上，您應該會看到確認指標建立成功的訊息，且新指標應該會顯示在「使用者定義指標」區段中。系統會在產生相符的記錄時填入指標。
選取新指標右側的垂直下拉式選單，然後選取「View in Metrics Explorer」(在 Metrics Explorer 中查看)。
在左側窗格中的「Build Your Query」下方，將「Resource Type」設為「Fleet Engine」，然後搜尋 Bill_tasks 指標。
右圖顯示 billing_tasks 呼叫的速率。
使用 BigQuery
BigQuery 是一項功能強大的工具，可用於執行數據分析。可用於儲存長期記錄檔，並針對資料執行類似 SQL 的即時查詢。
將記錄檔轉送至 BigQuery
如要使用 BigQuery，必須將記錄檔轉送至 BigQuery 資料儲存庫，如下所示：
在 Cloud 控制台中，依序選取「Logging」和「記錄檔探索工具」。
建立篩選 Fleet Engine 記錄檔的篩選器。在「記錄檔欄位探索工具」中，選取 Fleetengine.googleapis.com/DeliveryFleet 資源類型。
在「Query Results」(查詢結果) 窗格中，按一下「Actions」(動作) 下拉式選單，然後選取「Create Sink」(建立接收器)。
在「選取接收器服務」對話方塊中，選取「BigQuery 資料集」。
在「Edit Sink」(編輯接收器) 對話方塊中，指定下列選項：
- 指定接收器名稱 (例如 FleetEngineLogsSink)。
- 將接收器服務保留為 BigQuery。
- 選取「使用分區資料表」選項。這可提高查詢效能。
- 在「Sink Destination」(接收器目的地) 下方，選取 [Create New BigQuery Dataset] (建立新的 BigQuery 資料集)，然後指定 BigQuery 資料集名稱 (例如「FleetEngineLogs」)。
- 按一下 [Create Sink] (建立接收器) 按鈕。
記錄檔現在應該會開始填入 BigQuery 資料集。您可以在 Cloud 控制台的「BigQuery」區段查看資料。
FleetEngineLogs 資料集內的多個資料表將自動填入，每種記錄類型都有一個：
- CreateDeliveryVehicle
- GetDeliveryVehicle
- ListDeliveryVehicle
- UpdateDeliveryVehicle
- CreateTask
- GetTask
- UpdateTask
- ListTasks
- SearchTasks
資料表名稱採用以下模式：
project_id.data_set.log_name
例如，如果專案名稱為 test_project，且資料集名稱為 FleetEngineLogs，CreateTask 資料表會使用下列名稱：
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_task
查詢範例
本節列出您可以建立的查詢範例。
每小時建立的工作數量
下列查詢會計算 CreateTasks 記錄檔數，並按照小時分組。
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
每輛車每小時的轉機次數
下列查詢會產生車輛服務站的停靠站計數，並按小時細分。
舉例來說，這項查詢可能指出過去 1 小時內：
- 車輛 A 在一小時 12 小時內完成 10 個停靠站，13 小時內停靠 8 次。
- 車輛 B 在一小時內在 11 小時內完了 5 個停靠站，12 小時內搭乘 7 個停靠站。
車輛 C 在一小時內完成了 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 可與商業智慧工具和資訊主頁整合，以利進行業務分析。
下例說明如何建構資訊主頁，列出可在地圖上以視覺化方式呈現的工作和車輛動作。
啟動新的 Datastudio 資訊主頁，然後選取 BigQuery 做為數據連線。
選取「Custom Query」(自訂查詢)，然後選取要付費的 Cloud 專案。
在查詢方塊中輸入下列查詢。
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 新增其他下拉式清單控制項。
您可以利用這些控制項，以視覺化方式呈現車輛的移動狀況或運送過程。