Fleet Engine には、API リクエストとレスポンスのペイロードを保存できるシンプルなロギング サービスが用意されています。これらのログを使用して、統合のデバッグ、モニタリング指標の作成、トラフィック パターンの分析を行うことができます。
Fleet Engine は、ログをプラットフォーム ログとして Cloud Logging に送信し、Cloud Logging ツールを使用してアクセスできるようにします。
Fleet Engine が記録する内容
Fleet Engine は、次のような複数の情報を Cloud Logging に送信します。
- 認証済みのすべての REST および gRPC リクエストとレスポンス
- Error responses(エラー応答)
- Driver SDK が開始した呼び出しから Fleet Engine へのリクエスト、レスポンス、エラー メッセージ。
サポートされているログタイプでログを分割:
利用可能なログメッセージとスキーマについては、Logging リファレンスをご覧ください。
制限付きのログバケットとデフォルトのログバケットを使用してデータ保持ポリシーに準拠する
「制限付き」バケットと「デフォルト」バケットを使用すると、制限付きと無制限のデータ使用を明確に把握できます。Fleet Engine が Google Maps Platform に送信するログデータの一部は、モビリティ サービス固有の規約に従い、限られた期間のみ保持される場合があります。制限付きデータを許可された期間のみ保持するには、このようなデータには 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/DeliveryFleet"
そのクエリのログが表示されない場合は、プロジェクトで Cloud Logging が有効になっていない可能性があります。この機能を有効にする場合は、サポートにお問い合わせください。
制限付き使用ログを有効にする
使用制限付きログは、リクエストに応じて有効になります。Google Cloud プロジェクトでこれらのログを有効にするには、次の手順を行います。
使用制限のあるログを受信できるようにプロジェクトを準備する
- Google Cloud コンソールで、[ログルーター] ページを開きます。
- _Default ロギング バケットを更新して、使用制限のあるログを除外します。
- _Default ロギング バケットを選択し、[シンクを編集] を選択します。
- [シンクに含めないログの選択] セクションで、[除外を追加] ボタンをクリックします。
- 除外フィルタ名: ExcludeRestrictedLogs
- 除外フィルタ: labels.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 Maps Platform 利用規約とモビリティ サービス固有の規約(Google マップ コンテンツに関連するキャッシュ保存や使用許可の要件を含む)を遵守することに同意したことになります。○ / ×
サポートチームがリクエストを受信すると、プロジェクトのロギングが有効になっていることを伝える確認が送信されます。
クラウドログの分割
Cloud Logging では、受信ログのサイズが 256 KB に制限されます。サービスは、このしきい値を超えるログをドロップします。Cloud Logging がサイズの大きいログを保持できるように、Fleet Engine は 256 KB のしきい値未満の一連のログに分割できます。このようなログには共通の insertId 接頭辞があり、サービスが元のサイズ超過のログから小さなログを分割した順序を示しています。その後、insertId に基づいて再度結合できます。
分割されていない元のログにアクセスするには、Cloud ログエントリのインデックスで示されているように、分割された元の順序で insertId で分割ログをマージします。
分割ログの構造は、Cloud Audit Logs の監査ログエントリの分割ガイドで説明されている構造と同じです。フリート ロギングの分割ログの主な違いは、分割が protoPayload
フィールドではなく jsonPayload
フィールドで行われることです。次のセクションに示す分割例をご覧ください。
サポートされているログタイプ
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 にログを送信します。ログ エクスプローラを使用して、ログを表示するためのクエリを作成できます。
たとえば、エラーを返した Fleet Engine へのすべての RPC を表示するには、次のログ エクスプローラ クエリを使用します。
resource.type:"fleetengine.googleapis.com/DeliveryFleet"
severity=ERROR
プロジェクト example-project-id の UpdateDeliveryVehicle
メソッドに対して行われた RPC のログを表示するには、次のログ エクスプローラ クエリを使用します。
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 コンソールを開き、[ロギング]、[ログ エクスプローラ] の順に選択します。使用可能なすべての 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 コンソールで、[ロギング]、[ログ エクスプローラ] の順に選択してログ エクスプローラを開きます。次に、以下のフィルタを適用します。
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")
[クエリ結果] ペインで、[アクション] プルダウンを選択し、[指標を作成] を選択します。
[指標エディタ] ダイアログで、次の操作を行います。
- 指標名を指定します(例: billable_tasks)。
- 指標の説明(課金対象タスクの数など)を指定します。
- [単位] オプションは空白のままにします。[タイプ] オプションは [カウンタ] のままにします。
次に、[指標を作成] ボタンを選択します。
[ログベースの指標] ページに、指標が正常に作成されたことを示すメッセージが表示され、[ユーザー定義指標] セクションに新しい指標が表示されます。一致するログが生成されると、指標にデータが入力されます。
新しい指標の右側にある垂直プルダウンを選択し、[Metrics Explorer で表示する] を選択します。
左側のペインの [クエリの作成] で、リソースタイプを [Fleet Engine] に設定し、billingable_tasks 指標を検索します。
右側のグラフは、billingable_tasks 呼び出しの割合を示しています。
BigQuery の使用
BigQuery は分析を行うための強力なツールです。より長いログを保存したり、データに対してアドホック SQL のようなクエリを実行したりできます。
BigQuery へのログのルーティング
BigQuery を活用するには、次のようにログを BigQuery データストアに転送する必要があります。
Cloud コンソールで、[ロギング]、[ログ エクスプローラ] の順に選択します。
Fleet Engine ログを分離するフィルタを作成します。ログ フィールド エクスプローラで、[Fleetengine.googleapis.com/DeliveryFleet] リソースタイプを選択します。
[クエリ結果] ペインで、[操作] プルダウンをクリックし、[シンクを作成] を選択します。
[シンクサービスの選択] ダイアログで、[BigQuery データセット] を選択します。
[シンクの編集] ダイアログで、次のオプションを指定します。
- シンク名を指定します(例: FleetEngineLogsSink)。
- シンクサービスは [BigQuery] のままにします。
- [パーティション分割テーブルを使用する] オプションを選択します。これにより クエリのパフォーマンスが向上します
- [シンクの宛先] で、[新しい BigQuery データセットを作成する] を選択し、BigQuery データセット名を指定します(例: FleetEngineLogs)。
- [シンクを作成] ボタンをクリックします。
これで、BigQuery データセットへのログの記録が開始されます。このデータは Cloud コンソールの BigQuery セクションに表示されます。
FleetEngineLogs データセットの下に、ログタイプごとに 1 つのテーブルが自動的に入力されます。
- 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
クエリの例
このセクションでは、作成できるクエリの例を示します。
1 時間あたりに作成されるタスク
次のクエリは、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 台 1 時間あたりの経由地数
次のクエリは、車両が運行した停車地の数を時間別に生成します。
たとえば、このクエリは過去 1 時間で次のことが行われたことを示している可能性があります。
- 車両 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 はビジネス インテリジェンス ツールと統合でき、ビジネス分析用のダッシュボードを作成できます。
次の例は、タスクと車両の動きを地図に可視化できるダッシュボードを作成する方法を示しています。
新しいデータポータル ダッシュボードを起動し、データ接続として BigQuery を選択します。
[カスタムクエリ] を選択し、課金先の 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 については、プルダウン リスト コントロールを追加できます。
これらの制御により、車両の動きや配送内の動きを可視化できます。