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 年) 所定義。使用「受限制」和「預設」值區，可確保設有限制和不受限的數據用量。
將所有剩餘的不受限記錄資料傳送到「預設」值區，該值區可以無限期地停留。
合併限制與無限制的記錄檔，即可查看完整資料
限制用途的記錄含有使用限制資料和預設記錄的參照，如此可以將這些記錄一併納入考量。受限用途記錄在 parent_insert_id 欄位中包含預設記錄的 insertId 做為參照。您可以使用這個欄位彙整這兩個記錄中的資料，並取得完整資訊。
如要瞭解所有可用記錄訊息和結構定義，請參閱 Logging 參考資料。
啟用 Cloud Logging
Fleet Engine 會自動從 2022 年 2 月 10 日建立的專案開始，為新的行動性客戶啟用預設記錄檔。您可以在記錄檔探索工具中使用下列查詢，確認是否已啟用記錄功能：
resource.type:"fleetengine.googleapis.com"
如果沒有看到該查詢的任何記錄檔，表示專案可能未啟用 Cloud Logging。如要啟用這項功能，請與支援團隊聯絡。
啟用限制用途的記錄檔
已啟用限制用途的記錄檔，應要求啟用。如要為 Google Cloud 專案啟用這些記錄檔，請完成下列步驟：
為專案做好接收限制的準備
- 在 Google Cloud 控制台中，開啟「記錄檔路由器」頁面。
- 更新 _Default 記錄值區以排除限制用途的記錄檔。
- 選取 _Default 記錄值區，然後選擇 [Edit logs] (編輯接收器)。
- 在「選擇要從接收器篩選出的記錄檔」專區中，按一下「新增排除條件」按鈕：
- 「排除」篩選器名稱：ExcludeRestrictedLogs
- 「排除」篩選器：label.restriction="TOS_RESTRICTED"
- 按一下「更新接收器」。
- 更新受限制的記錄值區，以便儲存限制用途的記錄檔。
- 在「記錄檔路由器」頁面中，選取 [建立接收器]。
- 請使用下列設定建立接收器：
- 接收器詳細資料：
- 名稱：RestrictedLogs
- Description： 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 能保留大型記錄檔，機群引擎可將這些記錄檔分割為 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": {
"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
}
}
存取記錄檔
Cloud 記錄的結構是以 LogEntry 格式為基礎。在 LogEntry 的 resource.type 設為 fleetengine.googleapis.com 的情況下，Fleet Engine 會將記錄傳送至 Cloud Logging。您可以使用記錄檔探索工具撰寫查詢，查看記錄檔。
舉例來說，如要查看傳回錯誤給 Fleet Engine 的所有遠端程序呼叫 (RPC)，請使用下列記錄檔探索工具查詢：
resource.type:"fleetengine.googleapis.com"
severity=ERROR
如要查看專案 example-project-id 中 UpdateVehicle 方法所發出的 RPC 記錄，請使用下列記錄檔探索工具查詢：
logName="projects/project-id/logs/fleetengine.googleapis.com%2Fupdate_vehicle"
以下範例顯示 UpdateVehicle 記錄的 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.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"
}
如果傳回遠端程序呼叫 (RPC) 錯誤，系統會清除 responseVehicle 欄位，並在 jsonPayload 中設定並填入 errorResponse 欄位：
{
"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"
}
如要進一步瞭解記錄查詢語言，請參閱 Logging 查詢語言。如要瞭解如何使用記錄建立指標，請參閱記錄指標總覽。
管理 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] (Fleet Engine) 資源類型。部分 API 記錄標有行程 ID 和車輛 ID。您可以使用這些標籤，選取感興趣的行程或車輛記錄。
依車輛 ID 篩選記錄
在記錄檔探索工具中，您可以使用下列查詢，將記錄限制在特定車輛：
resource.type="fleetengine.googleapis.com/Fleet"
labels.vehicle_id="vehicle_id"
依行程 ID 篩選記錄
在記錄檔探索工具中，您可以使用下列查詢，將記錄限制在特定行程：
resource.type="fleetengine.googleapis.com/Fleet"
labels.trip_id=~"trip_id"
篩選特定時間範圍內的車輛記錄檔
在「記錄檔探索工具」中，您可以使用下列查詢，將特定時間範圍內的車輛記錄限制為單一車輛：
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"
記錄指標範例
以下範例說明如何使用記錄指標追蹤一段時間內的行程數量。
在 Cloud 控制台中，依序選取「Logging」和「記錄檔探索工具」以開啟記錄檔探索工具。然後套用下列篩選器：
resource.type="audited_resource" resource.labels.method="maps.fleetengine.v1.TripService.ReportBillableTrip"在「Query Results」窗格中，選取「Actions」下拉式選單，然後選取「Create Metric」。
在「指標編輯工具」對話方塊中：
- 指定指標名稱 (例如 billable_trips)。
- 指定指標說明 (例如 The number of Billable Trip 呼叫 s)。
- 將「Units」選項留空。_ 將「Type」選項保留為「Counter」。
接著，選取「建立指標」按鈕。
「記錄指標」頁面應會顯示訊息，確認已成功建立指標，且「使用者定義指標」部分應會顯示新指標。現在系統會在產生相符的記錄檔時填入指標。
選取新指標右側的垂直下拉式選單，然後選取「View in Metrics Explorer」。
在左側窗格的「Build Your Query」下方，將資源類型設定為「Fleet Engine」，然後搜尋 billing_trips 指標。
右側的圖表會顯示 billing_trips 呼叫的費率。
使用 BigQuery
BigQuery 是強大的分析工具。也可用於儲存長期記錄檔，以及對資料執行類似 SQL 的臨時查詢。
將記錄檔轉送至 BigQuery
如要利用 BigQuery，您必須將記錄轉送至 BigQuery 資料儲存庫，如下所示：
在 Cloud 控制台中，依序選取「Logging」和「記錄檔探索工具」。
建立可隔離 Fleet Engine 記錄檔的篩選器。在記錄檔欄位探索工具中，選取「Fleetengine.googleapis.com/Fleet」資源類型。
在「Query Results」(查詢結果) 窗格中，按一下「Actions」(動作) 下拉式選單並選擇 [Create Sink] (建立接收器)。
在「選取接收器服務」對話方塊中，選取「BigQuery 資料集」。
在「Edit Sink」(編輯接收器) 對話方塊中指定下列選項：
- 指定接收器名稱 (例如 FleetEngineLogsSink)。
- 將「接收器服務」保留為 BigQuery。
- 選取「Use Partitioned Tables」選項。這可提升查詢效能。
- 在「接收器目的地」下方，選取「建立新的 BigQuery 資料集」，然後指定 BigQuery 資料集名稱 (例如「FleetEngineLogs」)。
- 按一下 [建立接收器] 按鈕。
您的記錄檔現在應該會開始填入 BigQuery 資料集。您可以在 Cloud 控制台的「BigQuery」專區中查看這些資料。
FleetEngineLogs 資料集下的數個資料表會自動填入，每個記錄類型各有一個資料表：
- CreateVehicle
- GetVehicle
- ListVehicles
- SearchVehicles
- UpdateVehicle
- CreateTrip
- GetTrip
- UpdateTrip
- ListTrips
資料表名稱採用以下模式：
project_id.data_set.log_name
例如，如果專案名為 test_project，資料集名稱為 FleetEngineLogs，則 CreateTrip 資料表名稱會如下所示：
test_project.FleetEngineLogs.fleetengine_googleapis_com_create_trip
查詢範例
本節將提供可建立查詢的範例。
每小時建立的行程數
下列查詢會計算 CreateTrips 記錄的數量，並按小時分組。
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
每輛車每小時的停靠次數
下列查詢會產生車輛提供的停靠站計數，並按小時細分。
舉例來說，以下查詢可以告訴我們過去一小時內：
- 車輛 A 在一小時 12 時完成 10 個停靠站，13 小時內有 8 個停靠站。
- 車輛 B 在小時 11 時完成了 5 個停靠站，並於 12 小時內完成 7 個停靠站。
車輛 C 在小時 13 時完成了 12 個停靠站，14 小時內完成 9 個停靠站。
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
數據分析資訊主頁
BigQuery 可與商業智慧工具整合，且可建立資訊主頁來進行商業分析。
下例說明如何建立資訊主頁，在地圖上以視覺化方式呈現交通路線和車輛移動情形。
啟動新的 Datastudio 資訊主頁，然後選取 BigQuery 做為數據連線。
選取「Custom Query」，接著選取要支付費用的 Cloud 專案。
在查詢方塊中輸入下列查詢。
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`選取「泡泡圖」做為圖表類型，然後選取位置欄位。
選取「建立欄位」。
為欄位命名，並新增下列公式：CONCAT(lat, ",", lng)。
然後將類型設為 Geo->Latitude, Longitude。
您可以在資訊主頁中新增控制項，以便篩選資料。例如選取「日期範圍」篩選器
編輯日期範圍方塊即可選取預設日期範圍。
您可以加入其他 car_id 的下拉式清單控制項。
只要使用這些控制項，您就能透過視覺化的方式呈現車輛移動或行程中的移動情形。