AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

使用 AWS IoT 设置 CloudWatch Logs

当消息从您的设备通过消息代理和规则引擎传递时,AWS IoT 会发送关于每条消息的进度事件。要查看这些日志,您必须配置 AWS IoT 以生成由 CloudWatch 使用的日志。

有关 CloudWatch Logs 的更多信息,请参阅CloudWatch Logs

要启用 AWS IoT 日志记录,您必须创建一个 IAM 角色,将该角色注册到 AWS IoT,然后配置 AWS IoT 日志记录。

注意

在启用 AWS IoT 日志记录之前,请务必了解 CloudWatch Logs 访问权限。拥有 CloudWatch Logs 访问权限的用户能够从您的设备查看调试信息。有关更多信息,请参阅 Amazon CloudWatch Logs 的身份验证和访问控制

创建日志记录角色

使用 IAM 控制台可创建日志记录角色。

  1. 从导航窗格中,选择角色,然后选择创建新角色

  2. 选择 AWS 服务角色;对于服务角色类型,选择 AWS IoT

  3. 选择 AWSIoTLogging 角色,然后选择下一步

  4. 键入角色的名称和描述,然后选择创建角色

日志记录角色策略

以下策略文档提供了角色策略和信任策略,借助这些策略,AWS IoT 可代表您向 CloudWatch 提交日志。

注意

在您创建日志记录角色时已为您创建这些文档。

角色策略:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:PutMetricFilter", "logs:PutRetentionPolicy" ], "Resource": [ "*" ] } ] }

信任策略:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

日志级别

日志级别指定了将生成哪些类型的日志。

ERROR

导致操作失败的任何错误。

日志仅包含 ERROR 信息。

WARN

可能导致系统中出现不一致问题,但不会导致操作失败的所有情况。

日志包括 ERROR 和 WARN 信息。

INFO

有关事物流的高级别信息。

日志包括 INFO、ERROR 和 WARN 信息。

DEBUG

可能有助于调试问题的信息。

日志包括 DEBUG、INFO、ERROR 和 WARN 信息。

DISABLED

所有日志记录均处于禁用状态。

配置 AWS IoT 日志记录

您可以通过两种方式配置日志记录,即全局日志记录和精细日志记录。全局日志记录为所有日志设置一个日志记录级别,而无论是什么资源触发了日志。精细日志记录可让您为一种特定资源或一组资源设置日志记录级别。当前仅支持事物组。

全局日志记录

使用 set-logging-options CLI 命令可为您的账户设置日志记录选项。set-logging-options 包含两个参数:

roleArn

您的日志记录角色 ARN。日志记录角色将向 AWS IoT 授予对 CloudWatch Logs 的写入权限。

logLevel

要使用的日志级别。有效值为:ERROR、WARN、INFO、DEBUG 或 DISABLED

例如:

aws iot set-logging-options --logging-options-payload roleArn="arn:aws:iam::<your-aws-account-num>:role/<IoTLoggingRole>",logLevel="<INFO>"

您可以使用 get-logging-options CLI 命令来获取当前日志记录选项。

精细日志记录

可通过精细日志记录为目标指定日志记录级别。目标由资源类型和资源名称定义。目前,AWS IoT 支持将事物组作为目标。可通过精细日志记录为特定的事物组设置日志记录级别。假设我们有一个名为“Phones”的事物组,该组包含代表不同类型的电话的事物。然后,我们创建另一个名为“MobilePhones”的事物组,并将其设置为“Phones”事物组的子级。利用精细日志记录功能,您可以为“Phones”组 (以及任何子组) 中的所有事物配置一个日志记录级别,并为“MobilePhones”组中的事物配置另一个日志记录级别。在此示例中,我们已为“MobilePhones”组中的事物分配了两个不同的日志记录级别 (一个来自“Phones”事物组的日志记录级别,另一个来自“MobilePhones”事物组) – 不过,为子事物组指定的日志记录级别将覆盖为父事物组指定的日志记录级别。

使用 set-v2-logging-options CLI 命令可启用精细日志记录,并设置默认日志记录级别。它接受以下可选参数:

--role-arn

一个允许 AWS IoT 写入到您的 CloudWatch Logs 的 IAM 角色。如果未指定此参数,则 AWS IoT 将使用与您的账户关联的日志记录角色。在创建日志记录角色时,它将与您的账户关联。有关更多信息,请参阅 创建日志记录角色

--default-log-level

在未指定日志记录级别的情况下使用的日志记录级别。有效值为:DEBUGINFOERRORWARNDISABLED

--disable-all-logging

如果设置为 true,则将禁用所有日志记录。

get-v2-logging-options CLI 命令返回配置的 IAM 日志记录角色、默认日志记录级别和 disableAllLogs 值。

使用 set-v2-logging-level CLI 命令可为目标配置精细日志记录。它接受以下参数:

--log-target

一个 JSON 文档,其中包含您为其配置日志记录的实体的资源类型和名称。AWS IoT 目前支持将 THING_GROUP 作为资源类型。您最多可配置 10 个日志记录目标。

--log-level

为指定资源生成日志时使用的日志记录级别。有效值为:DEBUGINFOERRORWARNDISABLED

使用 list-v2-logging-levels CLI 命令可获取当前配置的精细日志记录级别的列表。调用 delete-v2-logging-level CLI 命令可删除日志记录级别。使用 delete-v2-logging-level 命令可删除精细日志记录级别。

CloudWatch 日志条目格式

AWS IoT 的每个组件均会生成自己的日志。每个日志条目均有一个 eventType,指示哪项操作导致生成了日志。此部分介绍以下 AWS IoT 组件所生成的日志:

所有 CloudWatch Logs 都具有以下通用属性:

timestamp

客户端连接到 AWS IoT 消息代理的时间的 UNIX 时间戳。

logLevel

所使用的日志级别。有关更多信息,请参阅 日志级别

traceId

一个随机生成的标识符,可用于将特定请求的所有日志关联起来。

accountId

您的 AWS 账户 ID。

status

请求的状态。

eventType

已为其生成日志的事件类型。以下各部分列出了每个事件的事件类型的值。

消息代理日志

AWS IoT 消息代理会生成以下事件的日志:

Connect 日志更多信息 (1)
Connect 日志

在 MQTT 客户端进行连接时,AWS IoT 消息代理会生成 Connect 日志。

更多信息 (1)

例如:

{ "timestamp": "2017-08-10 15:37:23.476", "logLevel": "INFO", "traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb", "accountId": "123456789012", "status": "Success", "eventType": "Connect", "protocol": "MQTT", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外,Connect 日志条目还包含以下属性:

eventType

Connect (针对连接日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

clientId

发出请求的客户端的 ID。

principalId

发出请求的委托人的 ID。

sourceIp

请求的源 IP 地址。

sourcePort

请求的源端口。

Subscribe 日志更多信息 (2)
Subscribe 日志

在 MQTT 客户端订阅主题时,AWS IoT 消息代理会生成 Subscribe 日志。

更多信息 (2)

例如:

{ "timestamp": "2017-08-10 15:39:04.413", "logLevel": "INFO", "traceId": "7aa5c38d-1b49-3753-15dc-513ce4ab9fa6", "accountId": "123456789012", "status": "Success", "eventType": "Subscribe", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/#", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外,Subscribe 日志条目还包含以下属性:

eventType

Subscribe (针对订阅日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

topicName

已订阅主题的名称。

clientId

发出请求的客户端的 ID。

principalId

发出请求的委托人的 ID。

sourceIp

请求的源 IP 地址。

sourcePort

请求的源端口。

Publish-In 日志更多信息 (3)
Publish-In 日志

在 AWS IoT 消息代理收到 MQTT 消息时,该代理会生成 Publish-In 日志。

更多信息 (3)

例如:

{ "timestamp": "2017-08-10 15:39:30.961", "logLevel": "INFO", "traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699", "accountId": "123456789012", "status": "Success", "eventType": "Publish-In", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/get", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外,Publish-In 日志条目还包含以下属性:

eventType

Publish-In (在消息代理收到消息时)。

status

请求的状态。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

topicName

已订阅主题的名称。

clientId

发出请求的客户端的 ID。

principalId

发出请求的委托人的 ID。

sourceIp

请求的源 IP 地址。

sourcePort

请求的源端口。

Publish-Out 日志更多信息 (4)
Publish-Out 日志

在 AWS IoT 消息代理发布 MQTT 消息时,该代理会生成 Publish-Out 日志。

更多信息 (4)

例如:

{ "timestamp": "2017-08-10 15:39:30.961", "logLevel": "INFO", "traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699", "accountId": "123456789012", "status": "Success", "eventType": "Publish-Out", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/get", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外,Publish-Out 日志条目还包含以下属性:

eventType

Publish-Out (在消息代理发布消息时)。

status

请求的状态。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

topicName

已订阅主题的名称。

clientId

发出请求的客户端的 ID。

principalId

发出请求的委托人的 ID。

sourceIp

请求的源 IP 地址。

sourcePort

请求的源端口。

Disconnect 日志更多信息 (5)
Disconnect 日志

在 MQTT 客户端断开连接时,AWS IoT 消息代理会生成 Disconnect 日志。

更多信息 (5)

例如:

{ "timestamp": "2017-08-10 15:37:23.476", "logLevel": "INFO", "traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb", "accountId": "123456789012", "status": "Success", "eventType": "Disconnect", "protocol": "MQTT", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外,Disconnect 日志条目还包含以下属性:

eventType

Disconnect (针对连接日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

clientId

发出请求的客户端的 ID。

principalId

发出请求的委托人的 ID。

sourceIp

请求的源 IP 地址。

sourcePort

请求的源端口。

Device Shadow 日志

AWS IoT Device Shadow 服务会生成以下事件的日志:

GetThingShadow 日志更多信息 (6)
GetThingShadow 日志

在收到影子的获取请求时,Device Shadow 服务会生成 GetThingShadow 日志。

更多信息 (6)

例如:

{ "timestamp": "2017-08-09 17:56:30.941", "logLevel": "INFO", "traceId": "b575f19a-97a2-cf72-0ed0-c64a783a2504", "accountId": "123456789012", "status": "Success", "eventType": "GetThingShadow", "protocol": "MQTT", "deviceShadowName": "MyThing", "topicName": "$aws/things/MyThing/shadow/get" }

除了所有 CloudWatch Logs 通用的属性之外,GetThingShadow 日志条目还包含以下属性:

eventType

GetThingShadow (针对 GetThingShadow 日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

deviceShadowName

所请求的影子的名称。

topicName

发布请求时所基于的主题的名称。

UpdateThingShadow 日志更多信息 (7)
UpdateThingShadow 日志

在收到设备的影子的更新请求时,Device Shadow 服务会生成 UpdateThingShadow 日志。

更多信息 (7)

例如:

{ "timestamp": "2017-08-07 18:43:59.436", "logLevel": "INFO", "traceId": "d0074ba8-0c4b-a400-69df-76326d414c28", "accountId": "123456789012", "status": "Success", "eventType": "UpdateThingShadow", "protocol": "MQTT", "deviceShadowName": "Jack", "topicName": "$aws/things/Jack/shadow/update" }

除了所有 CloudWatch Logs 通用的属性之外,UpdateThingShadow 日志条目还包含以下属性:

eventType

UpdateThingShadow (针对更新影子日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

deviceShadowName

要更新的影子的名称。

topicName

发布请求时所基于的主题的名称。

DeleteThingShadow 日志更多信息 (8)
DeleteThingShadow 日志

在收到设备的影子的删除请求时,Device Shadow 服务会生成 DeleteThingShadow 日志。

更多信息 (8)

例如:

{ "timestamp": "2017-08-07 18:47:56.664", "logLevel": "INFO", "traceId": "1a60d02e-15b9-605b-7096-a9f584a6ad3f", "accountId": "123456789012", "status": "Success", "eventType": "DeleteThingShadow", "protocol": "MQTT", "deviceShadowName": "Jack", "topicName": "$aws/things/Jack/shadow/delete" }

除了所有 CloudWatch Logs 通用的属性之外,DeleteThingShadow 日志条目还包含以下属性:

eventType

DeleteThingShadow (针对 DeleteThingShadow 日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

deviceShadowName

要更新的影子的名称。

topicName

发布请求时所基于的主题的名称。

规则引擎日志

AWS IoT 规则引擎服务会生成以下事件的日志:

规则匹配日志更多信息 (9)
规则匹配日志

在消息代理收到与规则匹配的消息时,AWS IoT 规则引擎会生成 RuleMatch 日志。

更多信息 (9)

例如:

{ "timestamp": "2017-08-10 16:32:46.002", "logLevel": "INFO", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "RuleMatch", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外,RuleMatch 日志条目还包含以下属性:

eventType

RuleMatch (针对规则匹配日志)。

clientId

发出请求的客户端的 ID。

topicName

已订阅主题的名称。

ruleName

匹配规则的名称。

principalId

发出请求的委托人的 ID。

函数执行日志更多信息 (10)
函数执行日志

在规则的 SQL 查询调用外部函数时,规则引擎会生成 FunctionExecution 日志。在规则的操作向 AWS IoT 或其他 Web 服务发出 HTTP 请求 (例如,调用 get_thing_shadowmachinelearning_predict) 时,将调用外部函数。

更多信息 (10)

FunctionExecution 日志看起来与以下内容类似:

{ "timestamp": "2017-07-13 18:33:51.903”, "logLevel": "DEBUG”, "traceId": "180532b7-0cc7-057b-687a-5ca1824838f5”, "status": "Success”, "eventType": "FunctionExecution”, "clientId": "N/A”, "topicName":"rules/test”, "ruleName": "ruleTestPredict”, "ruleAction": "MachinelearningPredict”, "resources": { "ModelId": "predict-model” }, "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167” }

除了所有 CloudWatch Logs 通用的属性之外,FunctionExecution 日志条目还包含以下属性:

eventType

FunctionExecution (针对规则匹配日志)。

clientId

N/A (针对 FunctionExecution 日志)。

topicName

已订阅主题的名称。

ruleName

匹配规则的名称。

resources

规则的操作所使用的资源的集合。

principalId

发出请求的委托人的 ID。

开始执行日志更多信息 (11)
开始执行日志

在 AWS IoT 规则引擎开始调用规则的操作时,该引擎会生成 StartingExecution 日志。

更多信息 (11)

例如:

{ "timestamp": "2017-08-10 16:32:46.002", "logLevel": "DEBUG", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "StartingRuleExecution", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "ruleAction": "RepublishAction", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外,StartingExecution 日志条目还包含以下属性:

eventType

StartingRuleExecution (针对开始规则执行日志)。

clientId

发出请求的客户端的 ID。

topicName

已订阅主题的名称。

ruleName

匹配规则的名称。

ruleAction

已调用操作的名称。

principalId

发出请求的委托人的 ID。

规则执行日志更多信息 (12)
规则执行日志

在 AWS IoT 规则引擎调用规则的操作时,该规则引擎会生成 RuleExecution 日志。

更多信息 (12)

例如:

{ "timestamp": "2017-08-10 16:32:46.070", "logLevel": "INFO", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "RuleExecution", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "ruleAction": "RepublishAction", "resources": { "RepublishTopic": "rules/republish" }, "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外,RuleExecution 日志条目还包含以下属性:

eventType

RuleExecution (针对规则执行日志)。

clientId

发出请求的客户端的 ID。

topicName

已订阅主题的名称。

ruleName

匹配规则的名称。

ruleAction

已调用操作的名称。

resources

规则的操作所使用的资源的集合。

principalId

发出请求的委托人的 ID。

任务日志

AWS IoT 任务服务会生成以下事件的日志:

获取任务执行日志更多信息 (13)
获取任务执行日志

在任务服务收到任务执行请求时,AWS IoT 规则引擎会生成 GetJobExecution 日志。

更多信息 (13)

例如:

{ "timestamp": "2017-08-10 19:08:05.813", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "GetJobExecution", "protocol": "MQTT", "clientId": "thingOne", "topicName": "$aws/things/thingOne/jobs/get", "details": "The request status is SUCCESS." }

除了所有 CloudWatch Logs 通用的属性之外,GetJobExecution 日志条目还包含以下属性:

eventType

GetJobExecution (针对获取任务执行日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

clientId

发出请求的客户端的 ID。

topicName

已订阅主题的名称。

details

来自任务服务的其他信息。

描述任务执行日志更多信息 (14)
描述任务执行日志

在任务服务收到描述任务执行的请求时,AWS IoT 规则引擎会生成 DescribeJobExecution 日志。

更多信息 (14)

例如:

{ "timestamp": "2017-08-10 19:13:22.841", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "DescribeJobExecution", "protocol": "MQTT", "clientId": "thingOne", "jobId": "002", "topicName": "$aws/things/thingOne/jobs/002/get", "clientToken": "myToken", "details": "The request status is SUCCESS." }

除了所有 CloudWatch Logs 通用的属性之外,GetJobExecution 日志条目还包含以下属性:

eventType

DescribeJobExecution (针对描述任务执行日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

clientId

发出请求的客户端的 ID。

jobId

任务执行的任务 ID。

topicName

发出请求所使用的主题。

clientToken

客户端令牌。

details

来自任务服务的其他信息。

更新任务执行日志更多信息 (15)
更新任务执行日志

在任务服务收到更新任务执行的请求时,AWS IoT 规则引擎会生成 UpdateJobExecution 日志。

更多信息 (15)

例如:

{ "timestamp": "2017-08-10 19:25:14.758", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "UpdateJobExecution", "protocol": "MQTT", "clientId": "thingOne", "jobId": "002", "topicName": "$aws/things/thingOne/jobs/002/update", "clientToken": "myClientToken", "versionNumber": "1", "details": "The destination status is IN_PROGRESS. The request status is SUCCESS." }

除了所有 CloudWatch Logs 通用的属性之外,UpdateJobExecution 日志条目还包含以下属性:

eventType

UpdateJobExecution (针对更新任务执行日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

clientId

发出请求的客户端的 ID。

jobId

任务执行的任务 ID。

topicName

发出请求所使用的主题。

clientToken

客户端令牌。

versionNumber

任务执行的版本。

details

来自任务服务的其他信息。

报告最终任务执行计数更多信息 (16)
报告最终任务执行计数

在任务完成时,AWS IoT 任务服务会生成 ReportFinalJobExecutionCount 日志。

更多信息 (16)

例如:

{ "timestamp": "2017-08-10 19:44:16.776", "logLevel": "INFO", "accountId": "123456789012", "status": "Success", "eventType": "ReportFinalJobExecutionCount", "protocol": "MQTT", "jobId": "002", "details": "Job 002 completed. QUEUED job execution count: 0 IN_PROGRESS job execution count: 0 FAILED job execution count: 0 SUCCESS job execution count: 1 CANCELED job execution count: 0 REJECTED job execution count: 0 REMOVED job execution count: 0" }

除了所有 CloudWatch Logs 通用的属性之外,ReportFinalJobExecutionCount 日志条目还包含以下属性:

eventType

ReportFinalJobExecutionCount (针对报告最终任务执行计数日志)。

protocol

发出请求时使用的协议。有效值为 MQTTHTTP

jobId

任务执行的任务 ID。

details

来自任务服务的其他信息。