Fleet Engine 提供了一项简单的日志记录服务，可让您保存其 API 请求和响应载荷。借助这些日志，您可以调试集成、创建监控指标和分析流量模式。
Fleet Engine 将日志作为平台日志发送到 Cloud Logging，以便您可以使用 Cloud Logging 工具访问这些日志。
Fleet Engine 可记录的内容
Fleet Engine 会向 Cloud Logging 发送多条信息，例如：
- 所有经过身份验证的 REST 和 gRPC 请求和响应
- 错误响应
- 由驱动程序 SDK 向 Fleet Engine 发起的调用所生成的请求、响应和错误消息。
为受支持的日志类型拆分日志：
如需了解可用的日志消息和架构，请参阅 Logging 参考。
使用受限日志存储分区和默认日志存储分区以遵守数据保留政策
使用“受限”和“默认”存储分区可确保清楚地了解受限和不受限的数据用量。根据移动服务专用条款，Fleet Engine 发送到 Google Maps Platform 的部分日志数据只能保留有限的一段时间。为了确保受限数据的保留时长不超过允许的时长，应将此类数据标记为 TOS_RESTRICTED（Fleet Engine 已执行此操作），并记录到名为“受限”的专用存储分区中。
然后，您可以使用 Cloud Logging 设置来控制数据的保留时长，并在到期时自动完全清除数据。例如，使用限制的日志应仅保留 30 天。
将所有剩余的不受限数据记录到“默认”存储分区中，按照移动服务专用条款的规定，这些数据可以在默认存储分区中保留更长时间（通常保留 1 年）。使用“受限”和“默认”存储分区可确保清楚了解受限和不受限的流量使用情况。
通过合并受限和不受限日志获取完整视图
受限使用日志包含受限使用数据和对默认日志的引用，以便可以一起加以考虑。限制使用日志将默认日志的 insertId 作为引用包含在 parent_insert_id 字段中。您可以使用此字段联接两个日志中的数据并获得完整信息。
如需了解所有可用的日志消息和架构，请参阅 Logging 参考。
启用 Cloud Logging
Fleet Engine 会自动为新的 Mobility 客户启用默认日志，从 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 将传入日志的大小限制为 256KB。该服务会丢弃超出该阈值的日志为确保 Cloud Logging 保留大型日志，Fleet Engine 可以将其拆分为一系列小于 256KB 的日志。此类日志具有一个共同的 insertId 前缀，以指示服务从超大的原始日志中拆分较小的日志的顺序。然后，您可以根据它们的 insertId 重新联接在一起。
如需访问原始的未拆分日志，请按 insertId 按照它们的原始拆分顺序（如 Cloud 日志条目中的索引所示）合并拆分日志。
拆分日志结构与 Cloud Audit Logs 拆分审核日志条目指南中提到的结构相同。舰队日志记录中拆分日志的主要区别在于，拆分发生在 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。您可以使用日志浏览器编写用于查看日志的查询。
例如，如需查看 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"
}
如需详细了解日志记录查询语言，请参阅日志记录查询语言。如需了解如何使用日志创建指标，请参阅基于日志的指标概览。
管理日志记录费用
启用日志记录功能后，您需要自行设置如何路由、存储和保留日志。如果您超过了免费的用量和保留限制，则可能需要为日志提取和保留支付额外的 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，然后选择 Logs Explorer。如需查看所有可用的 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 Console 中，选择 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")在“查询结果”窗格中，选择操作下拉菜单，然后选择创建指标。
在“指标编辑器”对话框中：
- 指定指标名称（例如 billable_tasks）。
- 指定指标说明（例如，可计费任务的数量）。
- 将 Units（单位）选项留空。_ 将类型选项保留为计数器。
然后选择创建指标按钮。
在“基于日志的指标”页面上，您应该会看到一条消息，确认指标已成功创建，并且新指标应显示在“用户定义的指标”部分中。现在，在生成匹配日志时，系统会填充该指标。
选择新指标右侧的垂直下拉菜单，然后选择在 Metrics Explorer 中查看。
在左侧窗格中的“Build Your Query”下，将资源类型设置为 Fleet Engine，然后搜索 billable_tasks 指标。
右侧图表显示了 billable_tasks 调用率。
使用 BigQuery
BigQuery 是用于执行分析的强大工具。它可用于存储长期日志，以及对数据执行类似 SQL 的临时查询。
将日志路由到 BigQuery
为了利用 BigQuery，日志必须路由到 BigQuery 数据存储区，如下所示：
在 Cloud 控制台中，选择 Logging，然后选择 Logs Explorer。
创建用于隔离 Fleet Engine 日志的过滤器。在日志字段浏览器中，选择 Fleetengine.googleapis.com/DeliveryFleet 资源类型。
在“查询结果”窗格中，点击“操作”下拉菜单，然后选择创建接收器。
在“选择接收器服务”对话框中，选择 BigQuery 数据集。
在“修改接收器”对话框中，指定以下选项：
- 指定接收器名称（例如 FleetEngineLogsSink）。
- 将接收器服务保留为 BigQuery。
- 选择使用分区表选项。这将提升查询性能。
- 在“接收器目标位置”下，选择新建 BigQuery 数据集，然后指定 BigQuery 数据集名称（例如 FleetEngineLogs）。
- 点击创建接收器按钮。
您的日志现在应该开始填充 BigQuery 数据集。您可以在 Cloud 控制台的 BigQuery 部分查看这些数据。
系统会自动填充 FleetEngineLogs 数据集下的多个表，每个表对应一种日志类型：
- 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
数据洞察信息中心
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)。
然后将类型设置为地理->纬度, 经度。
您可以通过向信息中心添加控件来过滤数据。例如，选择“日期范围”过滤条件
修改日期范围框以选择默认日期范围。
您可以为 delivery_vehicle_id 添加其他下拉列表控件。
借助这些控件，您可以直观了解车辆的移动或配送过程中的移动。