記錄

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

Fleet Engine 以 platform 形式傳送記錄 紀錄至雲端 Logging，因此您可以使用 記錄工具來存取。

Fleet Engine 記錄的內容

Fleet Engine 將多項資訊傳送至 Cloud Cloud 記錄，例如：

  • 所有經過驗證的 REST 和 gRPC 要求與回應
  • 錯誤回應
  • 駕駛人發起呼叫的要求、回應和錯誤訊息 部署至 Fleet Engine 的 SDK

  • 分割支援的記錄類型記錄：

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

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

使用「受限制」和「default」確保能清楚瞭解 限制及不受限的數據用量Fleet Engine 的一些記錄資料 傳送至 Google 地圖平台的 只會保留一段限定時間 根據行動性服務專屬規範 條款。 為確保只保留受限資料的時間 這類資料應標示為 TOS_RESTRICTED (目前已為 Fleet Engine 提供) 並記錄到名為「受限制」的專屬值區

您可以在這裡控制資料的保留時間，以及自動清除保留期限 存取 Cloud Logging 到期舉例來說，限制用途記錄 只會保留 30 天

將所有剩餘的未受限資料記錄為「預設」可以 延長保留時間 (定義請見行動性服務專屬規範) 條款 (通常需要 1 年)。使用「受限制」和「default」值區 顯示受限制和不受限數據用量的相片。

合併限制與無限制的記錄檔，即可查看完整資料

限制用途的記錄含有使用限制的資料，以及 預設記錄檔，這樣就能將這些物件一併納入考量。限制用途記錄 parent_insert_id 中包含預設記錄的 insertId 做為參照 ] 欄位。您可以使用這個欄位彙整兩個記錄中的資料，並取得 完整的圖片

如要瞭解所有可用記錄訊息和結構定義，請參閱 Logging 記錄 參考資料。

啟用 Cloud Logging

Fleet Engine 會自動為新的行動性客戶啟用預設記錄， 要從 2022 年 2 月 10 日建立的專案開始您可以確認 系統會在「記錄」中執行下列查詢，啟用記錄功能 探險家：

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

如果沒有看到該查詢的任何記錄檔，表示 Cloud Logging 可能尚未 。聯絡 支援 即可啟用這項功能。

啟用限制用途的記錄檔

已啟用限制用途的記錄檔，應要求啟用。為了替 Google Cloud 專案，請完成下列步驟：

為專案做好接收限制的準備

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

與支援團隊聯絡，啟用受限用途記錄檔

然後聯絡 支援服務，並提供 在支援要求中提供下列資訊：

  1. 要啟用的專案 ID：
  2. 要求變更者的電子郵件地址：
    1. 注意：這位使用者應具有 Google Cloud 專案的編輯權限 。
  3. 在 Cloud Logging 中啟用受限的 Google 地圖內容，即表示您同意 遵循 Google 地圖平台 條款和行動性服務條款 特定 條款， 包括與 Google 相關的快取和許可使用需求 「Google 地圖內容」。是/否

支援團隊收到要求後，會傳送確認通知給你 您的專案已啟用

分割雲端記錄檔

Cloud Logging 將傳入記錄檔的大小限制為 256 KB。服務捨棄記錄檔 超過這個門檻為確保 Cloud Logging 能保留大型記錄檔，機群 引擎可以將這些記錄檔分割為 256 KB 門檻以下的一系列記錄檔。這類記錄檔 具有共通點 insertId 前置字串，表示服務按照 原始超大型記錄檔然後您可以根據參與者 insertId。

如要存取原始的未分割記錄檔，請依 insertIds 之前先列出其索引 Cloud 記錄項目

分割記錄結構與分割稽核作業中提及的結構相同 記錄項目指南 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。您可以使用記錄檔 探索工具 並撰寫查詢來查看記錄檔

舉例來說，如要查看傳回錯誤的所有 Fleet Engine 遠端程序呼叫 (RPC)，請使用 下列記錄檔探索工具查詢：

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

如要查看針對 UpdateDeliveryVehicle 方法發出的 RPC 記錄 專案 example-project-id 並使用下列記錄檔探索工具查詢：

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 欄位會 已清除，且 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"
    }

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

管理 Logging 費用

啟用記錄功能後，請視需要設定 以便轉送、儲存及保留記錄檔您可能需要支付額外的 Google Cloud 費用 對記錄的 charges 如果超出免付費用量和保留限制 費用。不過，您可以執行下列其中一項操作來控管記錄費用：

減少記錄用量

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

匯出或路徑記錄

您可以將記錄檔轉送至其他 Google Cloud 或外部目的地，以免發生 預設擷取和儲存空間費用請務必關閉記錄擷取功能， 來避免擷取費用。

停用記錄擷取功能可避免產生費用

建議減少記錄用量，或匯出或轉送記錄檔 則在記錄擷取作業中關閉應用程式。但如果您不想使用 Fleet Engine 記錄， 可以關閉擷取功能，避免產生 Cloud Logging 費用。根據預設 Fleet Engine 記錄會轉送至 _Default 記錄檔值區。

下列指令會更新 _Default 記錄值區，使其不擷取機群 引擎記錄檔

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"

記錄指標範例

以下範例說明如何使用記錄指標追蹤 以及持續建立的工作

  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. 在「查詢結果」窗格中，選取「動作」下拉式選單，然後選取 建立指標。

    建立指標

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

    • 指定指標名稱 (例如 billable_tasks)。
    • 指定指標說明 (例如「可計費的數量」 Tasks)。
    • 將「Units」選項留空。_ 將「Type」選項保留為 計數器：

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

  4. 在「記錄指標」頁面上，您應該會看到確認訊息 指標建立成功，新指標就會顯示在 「使用者定義指標」專區。指標現在會填入相符 來產生

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

    查看指標

  6. 在左側窗格中「Build Your Query」下方，將資源類型設為「Fleet」 引擎並搜尋 billing_tasks 指標。

    搜尋指標

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

使用 BigQuery

BigQuery 是強大的分析工具。可用來儲存 以及對資料執行類似 SQL 的臨時查詢

將記錄檔轉送至 BigQuery

為了能運用 BigQuery，記錄必須轉送至 BigQuery 資料儲存庫， 如下：

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

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

    創作 濾網

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

    創作 洗手台

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

    選取 洗手台

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

    • 指定接收器名稱 (例如 FleetEngineLogsSink)。
    • 將「接收器服務」保留為 BigQuery。
    • 選取「Use Partitioned Tables」選項。這會增加查詢 才需進行
    • 在「接收器目的地」下方選取「建立新的 BigQuery 資料集」，然後 指定 BigQuery 資料集名稱 (例如，FleetEngineLogs)。
    • 按一下 [建立接收器] 按鈕。

    編輯 洗手台

您的記錄檔現在應該會開始填入 BigQuery 資料集。您會看到 資料。

BigQuery 區段

系統會在 FleetEngineLogs 資料集內填入數個資料表 會自動為每種記錄類型提供一個 ID：

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

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

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

每輛車每小時的停靠次數

下列查詢會產生車輛提供的停靠站計數和毀損 每小時降幅

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

  • 車輛 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

Datastudio 資訊主頁

BigQuery 可與商業智慧工具和資訊主頁整合， 建立用於商業分析

以下範例說明如何建立資訊主頁，以便處理各項工作和車輛 可透過地圖視覺化

  1. 啟動新的 Datastudio 資訊主頁，然後選取 BigQuery 做為資料 以獲得最佳效能和最安全的連線

    資料 連線

  2. 選取「Custom Query」，接著選擇目標雲端專案 計費。

    選取 專案

  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 新增額外的下拉式清單控制項。

    下拉式選單 清單

這些控制項可讓你以視覺化方式呈現車輛或 運送過程中的動態