Fleet Engine 提供了一项简单的日志记录服务,可让您保存 API 请求和响应载荷。借助这些日志,您可以调试 集成、创建监控指标并分析流量模式。
Fleet Engine 将日志作为平台发送 将日志复制到 Cloud 日志记录,以便您可以使用 用于访问它们的日志记录工具。
Fleet Engine 可记录的内容
Fleet Engine 将多条信息发送到 Cloud Logging,例如:
- 所有经过身份验证的 REST 和 gRPC 请求和响应
- 错误响应
- 来自驾驶员发起的通话的请求、响应和错误消息 SDK 添加到 Fleet Engine。
- 为受支持的日志类型拆分日志:
<ph type="x-smartling-placeholder">
- </ph>
- SearchVehicles
请参阅 Logging 中可用的日志消息和架构的文档 参考文档。
使用受限日志存储分区和默认日志存储分区以遵守数据保留政策
使用“受限”和“default”可确保您的集群 “受限”和“不受限”的数据流量使用方式Fleet Engine 会将一些日志数据 发送到 Google Maps Platform 的请求只能保留有限的一段时间, 根据 Mobility Service Specific(移动服务专用) 条款。 为了确保受限数据的保留时长不超过允许的时长, 此类数据应标记为 TOS_RESTRICTED(Fleet Engine 已执行此操作) 并记录到名为“受限”的专用存储分区中
在此处,您可以控制数据的保留时长,并在以下时间自动完全清除数据 使用 Cloud Logging 设置指定到期时间。例如,限制使用日志 只会保留 30 天。
将所有剩余的不受限数据记录到“默认值”中您可以将其 根据移动服务专用 条款 (通常为 1 年)。使用“受限”和“default”存储分区可确保 数据使用受限和不受限的图片。
将所有剩余的不受限日志数据发送到“default”该存储分区可以 无限期保留。
通过合并受限和不受限日志获取完整视图
受限使用日志包含受限使用数据以及对
默认日志,这样就可以将它们一起考虑。限制使用日志
包含默认日志的 insertId,作为 parent_insert_id
中的引用
字段。您可以使用此字段联接来自两个日志的数据,
请参阅 Logging 中所有可用的日志消息和架构的文档 参考文档。
启用 Cloud Logging
Fleet Engine 会自动为新的 Mobility 客户启用默认日志, 从 2022 年 2 月 10 日创建的项目开始。您可以确认 通过在日志中使用以下查询启用日志记录功能 探索器:
resource.type:"fleetengine.googleapis.com"
如果您没有看到该查询的任何日志,则说明 Cloud Logging 可能尚未 。联系 支持服务 即可启用该功能
启用受限使用日志
根据请求启用使用受限日志。要为您的 Google 代码启用这些日志, Cloud 项目中,请完成以下步骤:
准备您的项目以接收使用限制日志
- 在 Google Cloud 控制台中,打开“日志路由器”页面。
- 更新 _Default 日志记录存储分区,以排除仅限使用的日志。
- 选择 _Default 日志记录存储分区,然后选择修改接收器。
- 在“选择要从接收器中过滤掉的日志”部分,点击“添加”
排除项”按钮:
<ph type="x-smartling-placeholder">
- </ph>
- 排除项过滤条件名称:ExcludeRestrictedLogs
- 排除项过滤条件:labels.restriction="TOS_RESTRICTED"
- 点击“更新接收器”。
- 更新受限日志记录存储分区以存储仅限使用的日志。
- 在“日志路由器”页面中,选择“创建接收器”。
- 创建具有以下设置的接收器:
<ph type="x-smartling-placeholder">
- </ph>
- 接收器详情:
<ph type="x-smartling-placeholder">
- </ph>
- 名称:RestrictedLogs
- 说明:Routes Fleet Engine 使用限制日志
- 接收器目标位置:
<ph type="x-smartling-placeholder">
- </ph>
- 接收器服务:Logging 存储分区
- 选择日志存储分区:创建新的日志存储分区
<ph type="x-smartling-placeholder">
- </ph>
- 名称:受限
- 说明:包含 Fleet Engine 使用限制日志
- 保留期限:30 天
<ph type="x-smartling-placeholder">
- </ph>
- 注意:保留期限不得超过 30 天。
- 要包含在接收器中的日志:留空
- 要从接收器中过滤掉的日志:点击“添加排除项”
<ph type="x-smartling-placeholder">
- </ph>
- 排除项过滤条件名称:ExcludeNonRestrictedLogs
- 排除过滤条件:NOT (resource.type = "fleetengine.googleapis.com/Fleet"OR resource.type = “fleetengine.googleapis.com/DeliveryFleet”)而非 (labels.restriction = "TOS_RESTRICTED”)
- 点击“创建接收器”
- 接收器详情:
<ph type="x-smartling-placeholder">
如需启用使用限制日志,请与支持团队联系
然后,联系 支持并提供 请在支持请求中提供以下信息:
- 要启用的项目 ID:
- 请求更改的用户的电子邮件地址:
<ph type="x-smartling-placeholder">
- </ph>
- 注意:此人应拥有 Google Cloud 项目的修改权限 。
- 在 Cloud Logging 中启用限制使用的 Google 地图内容,即表示您同意 遵守 Google Maps Platform 条款和移动服务 具体 条款, 包括与 Google 相关的缓存和允许的使用要求 地图内容。有/无
支持团队收到您的请求后,会发送确认信息, 已为您的项目启用
拆分云日志
Cloud Logging 将传入日志的大小限制为 256KB。该服务会删除日志 超过该阈值。为确保 Cloud Logging 保留大型日志,舰队 Engine 可以将它们拆分为一系列小于 256KB 的日志。此类日志 共同点 insertId 前缀来指明服务将较小的日志从 原始超大型日志。然后,您可以根据其 insertId。
如需访问原始的未拆分日志,请按如下顺序合并拆分日志: insertIds 它们最初的拆分顺序,即它们在 Cloud 日志条目。
拆分日志结构与拆分审核中提到的结构相同
日志条目指南
Cloud Audit Logs。舰队日志记录中拆分日志的主要区别在于
拆分发生在 jsonPayload
字段中,而不是在 protoPayload
中
字段。请参阅下一部分中展示的分屏示例。
支持的日志类型
Fleet Engine 仅支持对以下日志类型进行日志拆分 如果日志大小超过 256KB,则会发生此错误:
拆分日志结构示例
// 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
格式。Fleet Engine 使用 LogEntry 的
resource.type
已设为 fleetengine.googleapis.com
。您可以使用日志
从
编写查询来查看日志。
例如,要查看 Fleet Engine 中返回了错误的所有 RPC,请使用 以下日志浏览器查询:
resource.type:"fleetengine.googleapis.com"
severity=ERROR
如需查看对 UpdateVehicle
方法的 RPC 进行
项目 example-project-id,请使用以下日志浏览器查询:
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
字段
已清除 errorResponse
字段,并在 jsonPayload
中填充了字段:
{
"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"
}
如需详细了解日志记录查询语言,请参阅日志记录查询 语言。 如需了解如何使用日志创建指标,请参阅概览 基于日志的 指标。
管理日志记录费用
启用日志记录后,您需要按照自己希望的方式进行设置 以路由、存储和保留日志。您可能会产生额外的 Google Cloud 费用 日志的 charges 超过 费用。但是,您可以通过执行以下任一操作来控制日志记录费用:
减少日志记录的使用
您可以通过排除某些日志条目来限制日志数据提取量。
导出或路由日志
您可以将日志路由到其他 Google Cloud 或外部目标位置,以避免 默认注入和存储费用请务必关闭日志注入,因为 避免注入费用。
关闭日志注入以避免产生费用
减少日志记录,或者导出或路由日志,而不是关闭 停用日志提取但是,如果您不打算使用 Fleet Engine 日志, 关闭注入功能可以避免产生潜在的 Cloud Logging 费用。默认情况下 Fleet Engine 日志会路由到 _Default 日志存储分区。
以下命令将 _Default 日志记录存储分区更新为不注入舰队 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 资源类型。有些 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,然后选择日志浏览器以打开 Logs Explorer然后应用以下过滤条件:
resource.type="audited_resource" resource.labels.method="maps.fleetengine.v1.TripService.ReportBillableTrip"
在“查询结果”窗格中,选择操作下拉菜单,然后选择 创建指标。
在“指标编辑器”对话框中:
- 指定指标名称(例如 billable_trips)。
- 指定指标说明(例如,可结算行程的数量 调用)。
- 将 Units(单位)选项留空。_ 将类型选项保留为 计数器。
然后选择创建指标按钮。
在“基于日志的指标”页面上,您应该会看到一条消息, 已成功创建指标,新指标应会显示在 “用户定义指标”部分。该指标现在将填充为匹配的 会生成日志。
选择新指标右侧的垂直下拉菜单,然后 选择在 Metrics Explorer 中查看。
在左侧窗格中的“构建查询”下,将资源类型设置为舰队 引擎,然后搜索 billingable_trips 指标。
右侧图表显示了 billingable_trips 调用的费率。
通过 BigQuery
BigQuery 是用于执行分析的强大工具。它可以用来存储 保存长期日志,并对数据执行类似 SQL 的临时查询。
将日志路由到 BigQuery
要利用 BigQuery,日志必须路由到 BigQuery 数据存储区, 如下:
在 Cloud 控制台中,选择 Logging,然后选择 Logs Explorer。
创建用于隔离 Fleet Engine 日志的过滤器。在“日志字段浏览器”中 选择 Fleetengine.googleapis.com/Fleet 资源类型。
在“查询结果”窗格中,点击“操作”下拉菜单,然后选择创建 接收器。
在“选择接收器服务”对话框中,选择 BigQuery 数据集。
在“修改接收器”对话框中,指定以下选项:
- 指定接收器名称(例如 FleetEngineLogsSink)。
- 将接收器服务保留为 BigQuery。
- 选择使用分区表选项。这将提升查询 性能
- 在接收器目标位置下,选择新建 BigQuery 数据集,然后 指定 BigQuery 数据集名称(例如 FleetEngineLogs)。
- 点击创建接收器按钮。
您的日志现在应该开始填充 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 可以与商业智能工具和信息中心集成, 进行业务分析
以下示例展示了如何构建针对哪些行程和车辆的信息中心 移动情况可以在地图上显示。
启动新的数据洞察信息中心,并选择 BigQuery 作为数据 连接。
选择“自定义查询”,然后选择它应该关联到的 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)。
然后将类型设置为地理->纬度, 经度。
您可以通过向信息中心添加控件来过滤数据。例如,选择 “日期范围”过滤条件
修改日期范围框以选择默认日期范围。
您可以为 vehicle_id 添加其他下拉列表控件。
通过这些控件,您可以直观地看到车辆的移动或 在行程中的移动。