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
- 说明：路由 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 仅支持对日志大小超过 256KB 的以下日志类型进行日志拆分：
拆分日志结构示例
// 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 将日志发送到 Cloud Logging，并将 LogEntry 的 resource.type 设置为 fleetengine.googleapis.com。您可以使用日志浏览器编写用于查看日志的查询。
例如，如需查看 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 或外部目标位置，以避免产生默认的提取和存储费用。请务必关闭日志提取（如下一部分所述），以免产生提取费用。
关闭日志提取以免产生费用
与关闭日志提取相比，首选减少日志记录，或者导出或路由日志。但是，如果您不打算使用 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 导出和导出日志
使用日志浏览器
如需使用 Logs Explorer，请打开 Cloud Console，选择 Logging，然后选择 Logs Explorer。如需查看所有可用 Fleet Engine 日志的列表，请点击 Fleet Engine 资源类型。某些 Delivery API 日志标有任务 ID 和送货车辆 ID。您可以使用这些标签为您感兴趣的任务或车辆选择日志。
按送货车辆 ID 过滤日志
在日志浏览器中，您可以使用以下查询将日志限制为特定车辆：none
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.delivery_vehicle_id="delivery_vehicle_id"
按任务 ID 过滤日志
在日志浏览器中，您可以使用以下查询将日志限制为仅执行特定任务：none
resource.type="fleetengine.googleapis.com/DeliveryFleet"
labels.task_id=~"task_id"
过滤特定时间段内车辆的日志
在日志浏览器中，您可以使用以下查询将日志限制为特定时间段内车辆的日志：none
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 中查看。
在左侧窗格的“构建查询”下，将“资源类型”设置为 Fleet Engine，然后搜索 billingable_tasks 指标。
右侧图表显示了 billingable_tasks 调用率。
使用 BigQuery
BigQuery 是用于执行分析的强大工具。它可用于存储长期日志以及对数据执行类似 SQL 的临时查询。
将日志路由到 BigQuery
如需利用 BigQuery，必须将日志路由到 BigQuery 数据存储区，如下所示：
在 Cloud 控制台中，选择 Logging，然后选择日志浏览器。
创建用于隔离 Fleet Engine 日志的过滤条件。在日志字段浏览器中，选择 Fleetengine.googleapis.com/DeliveryFleet 资源类型。
在“查询结果”窗格中，点击“操作”下拉菜单，然后选择创建接收器。
在“选择接收器服务”对话框中，选择 BigQuery 数据集。
在“修改接收器”对话框中，指定以下选项：
- 指定接收器名称（例如 FleetEngineLogsSink）。
- 将接收器服务保留为 BigQuery。
- 选择 Use Partitioned Tables 选项。这将提高查询性能。
- 在接收器目标位置下，选择新建 BigQuery 数据集，然后指定 BigQuery 数据集名称（例如 FleetEngineLogs）。
- 点击创建接收器按钮。
您的日志现在应该开始填充 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 日志的数量并按小时对其进行分组。sql
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 添加其他下拉列表控件。
通过这些控件，您可以直观了解车辆的移动情况或货物的移动情况。