查看设备日志

Cloud IoT Core 可以选择将设备活动日志发送到 Cloud Logging。设备活动日志包含设备连接和错误等信息。这些称为事件。

系统不会记录身份验证失败的情况。设备必须通过 Cloud IoT Core 的身份验证才能生成事件日志。

设备事件生命周期

所有 Cloud IoT Core 设备都遵循类似的生命周期，并发生以下事件。其中一些事件及其底层详细信息会在设备日志中捕获。

连接到 Cloud IoT Core。
发送和接收遥测和/或状态事件。
断开与 Cloud IoT Core 的连接。

这些事件发生和记录的方式取决于设备是使用 MQTT 网桥还是 HTTP 网桥。

记录设备活动

Cloud IoT Core 使用日志级别来确定将哪些设备事件发送到 Cloud Logging。您可以为注册表及其所有设备或个别设备设置设备日志级别。为注册表设置的日志级别适用于注册表中的所有设备。为单个设备设置的日志级别会替换其注册表的设置。

下表介绍了可用的设备日志级别：

日志级别	说明
无	系统不会收集设备事件日志。
`ERROR`	捕获所有 `ERROR` 事件，例如发布失败。如需查看 `ERROR` 事件的完整列表，请参阅记录的设备事件列表。
`INFO`（仅限 MQTT）	捕获所有 `INFO` 事件，例如通过 MQTT 建立的连接和断开连接的情况。还会捕获所有 `ERROR` 事件。如需查看 `INFO` 事件的完整列表，请参阅记录的设备事件列表。
`DEBUG`	捕获所有 `DEBUG` 事件，例如发布、订阅和检测信号。有助于精确定位特定设备的问题。还会捕获所有 `ERROR` 和 `INFO` 事件。如需查看 `DEBUG` 事件的完整列表，请参阅记录的设备事件列表。如需了解详情，请参阅设备调试日志记录。

记录的设备事件列表

下表显示了：

系统会记录哪些设备事件。
Cloud Logging 中记录的事件的 eventType。
是否记录每个事件的成功和/或失败。
必须在注册表或设备上设置的日志级别才能记录事件。

MQTT 网桥

设备事件	`eventType`	成功	失败
向服务器进行身份验证	不适用	不记录^*	不记录
连接到服务器	`CONNECT`	`INFO`	`ERROR`
断开与服务器的连接	`DISCONNECT`	`INFO`	不记录
将设备连接到网关	`ATTACH_TO_GATEWAY`	`INFO`	`ERROR`
将设备与网关分离	`DETACH_FROM_GATEWAY`	`INFO`	`ERROR`
将遥测事件或状态发布到服务器	`PUBLISH`（针对 `/devices/{device-id}/events` 或 `/devices/{device-id}/state` MQTT 主题）	`DEBUG`	`ERROR`
接收配置更新	`PUBLISH`（在 `/devices/{device-id}/config` MQTT 主题上）	`DEBUG`	`ERROR`
订阅 Pub/Sub 配置主题	`SUBSCRIBE`	`DEBUG`	`ERROR`
退订 Pub/Sub 配置主题	`UNSUBSCRIBE`	`DEBUG`	`ERROR`
从服务器收到的 PUBACK	`PUBACK`	`DEBUG`	`ERROR`
不断发送发送到服务器的 ping	`PINGREQ`	`DEBUG`	`ERROR`
从服务器发送至设备的命令	`PUBLISH`	`DEBUG`	`ERROR`
命令 PUBACK 已发送到服务器	`PUBACK`	`DEBUG`	`ERROR`

^*如果 MQTT 身份验证成功，设备将连接到 Cloud IoT Core 并记录一个 CONNECT 事件，而不是“对服务器进行身份验证”事件。

HTTP 网桥

设备事件	`methodName`	成功	失败
向服务器进行身份验证	不适用	不记录^**	不记录
发布遥测事件	`google.cloud.iot.v1.PublishEvent`	`DEBUG`	`ERROR`
设置设备状态	`google.cloud.iot.v1.SetDeviceState`	`DEBUG`	`ERROR`
接收配置更新	`google.cloud.iot.v1.GetDeviceConfig`	`DEBUG`	`ERROR`

^** 如果 HTTP 身份验证成功，则设备连接到 Cloud IoT Core，并且记录相关请求消息（如果收到配置则记录 GET；如果发布消息则记录 POST）。

启用、更改和停用设备日志记录

当您在 Google Cloud Console 或使用 gcloud 工具中创建或修改注册表或设备时，可以选择向 Cloud Logging 报告哪些类型的日志。

设置注册表的日志级别

您可以使用 Google Cloud Console 或 gcloud 为注册表启用、更改或停用设备日志。注册表日志设置会自动应用于注册表中的所有设备。

控制台

如需创建或修改注册表并设置其日志级别，请执行以下操作：

转到 Google Cloud Console 中的注册表页面。
转到注册表页面
点击页面顶部的创建注册表。

如需修改现有注册表，请在注册表页面上点击其 ID，然后点击页面顶部的修改注册表。
在 Stackdriver Logging 下，选择日志级别。
点击创建（如果创建新注册表）或更新（如果修改现有注册表）。

gcloud

如需创建注册表并设置其日志级别，请运行带有 --log-level 标志的 gcloud iot registries create 命令：

gcloud iot registries create REGISTRY_ID \
    --project=PROJECT_ID \
    --region=REGION \
    [--event-notification-config=topic=TOPIC,[subfolder=SUBFOLDER] [--event-notification-config=...]]
    [--state-pubsub-topic=STATE_PUBSUB_TOPIC] \
    --log-level={NONE|INFO|ERROR|DEBUG}

如需更新设备的日志级别，请运行带有 --log-level 标志的 gcloud iot registries update 命令：

gcloud iot registries update REGISTRY_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --log-level={NONE|INFO|ERROR|DEBUG}

为设备设置日志级别

您可以使用 Google Cloud Console 或 gcloud 为设备启用、更改或停用设备日志。设备的日志级别会替换其注册表的日志级别。

控制台

如需为新设备或现有设备设置日志级别，请执行以下操作：

转到 Google Cloud Console 中的注册表页面。
转到注册表页面
点击设备的注册表的 ID。
在左侧的注册表菜单中，点击设备。
如需创建新设备，请点击创建设备。

如需修改现有设备，请在设备页面上点击其 ID，然后点击页面顶部的修改设备。
在 Stackdriver Logging 下，选择日志级别。
点击创建（如果是创建新设备）或更新（如果是修改现有设备）。

gcloud

如需创建设备和设置日志级别，请运行带有 --log-level 标志的 gcloud iot devices create 命令：

gcloud iot devices create DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --public-key path=PUBLIC_KEY,type=TYPE \
    --log-level={NONE|INFO|ERROR|DEBUG}

如需更新设备的日志级别，请运行带有 --log-level 标志的 gcloud iot devices update 命令：

gcloud iot devices update DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --log-level={NONE|INFO|ERROR|DEBUG}

查看日志

您可以在 Google Cloud 控制台的日志浏览器中查看项目的设备活动日志。在日志名称菜单中选择 device_activity。

如需了解详情，请参阅使用日志浏览器。

API

如需通过 Logging API 读取日志条目，请参阅 entries.list。

gcloud

如需使用 gcloud 读取日志条目，请参阅读取日志条目。

导出设备日志

您可以按照导出其他类型日志的方式导出设备日志。如需详细了解如何导出日志，请参阅导出日志。

以下示例说明了您可能需要导出设备日志的原因：

如需长时间保留设备日志或使用更强大的搜索功能，您可以将设备日志的副本导出到 Cloud Storage、BigQuery 或 Pub/Sub。使用 Pub/Sub，您可以将内容导出到其他应用、其他代码库和第三方。
如需管理整个组织范围内与您相关的设备日志，您可以创建聚合导出接收器，以便从组织中的任何项目或所有项目导出日志。

设备日志记录限制

设备日志配额和限制适用于项目级别。它们会单独测量，不计入其他 Cloud Logging 配额和限制。如果设备日志配额用尽，其他服务的 Cloud Logging 配额不受影响。反之亦然。

设备日志配额基于两个因素：

每秒记录的设备事件数。事件包括发布、连接、断开连接等。
每分钟记录的设备事件的总大小（以字节为单位）。

如果超出任一设备日志配额，则设备日志会暂停。

如需查看设备日志配额和限制的列表，请参阅配额和限制。

最佳做法

设备调试日志记录

如已记录设备事件列表所示，为注册表或单个设备设置 DEBUG 日志级别可能会生成大量日志记录信息。因此，如果您为拥有大量设备的注册表启用了调试日志记录功能，日志记录可能会由于日志的高速和数量而被丢弃。

例如，假设您有一个包含 100000 台设备的注册表，并且为注册表设置了调试日志级别。如果每台设备每秒发布一个遥测事件，则每秒只记录 100000 个遥测事件中的 1000 个。这是因为，如配额和限制中所示，记录的最大条目数为每秒 1000 条。

为获得最佳效果，请仅在短时间内或为少量设备启用调试日志记录功能。

排查写入日志时的错误

首次为项目启用 Google Cloud IoT Core API 时，系统会自动为项目的新服务帐号分配一个角色 (cloudiot.serviceAgent)，该角色支持将日志写入 Cloud Logging。如果您稍后从相关项目服务帐号中移除此默认角色，则可能会遇到错误。如果您无法将设备活动写入 Cloud Logging，请完成以下步骤：

在 Google Cloud Console 的 IAM 页面上，验证 Cloud IoT Core Service Agent 角色是否显示在相关项目服务帐号的成员列表中。（查找以 @gcp-sa-cloudiot.iam.gserviceaccount.com 结尾的项目服务帐号。）
如果 Cloud IoT Core Service Agent 角色未显示在成员列表中，请使用 gcloud 将 cloudiot.serviceAgent 角色添加到相关项目服务帐号中。此角色包含将日志写入 Cloud Logging 的权限。

运行以下命令，将 cloudiot.serviceAgent 角色添加到您的项目中。如需查找 PROJECT_ID 和 PROJECT_NUMBER，请参阅识别项目。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudiot.iam.gserviceaccount.com \
  --role=roles/cloudiot.serviceAgent
```