本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 配置 AWS IoT 日志 必须先使用 AWS IoT 控制台、CLI 或 API 启用日志记录，然后才能监控和记录 AWS IoT 活动。您可以在三个 AWS IoT 级别上配置日志记录：账户级别、事件级别或资源特定级别。V2 日志仅提供事件级和特定资源的日志记录。使用 V1 日志记录的客户必须迁移到 V2 才能访问这些功能。查看[详情](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2)。 在考虑如何配置 AWS IoT 日志记录时，除非另有说明，否则账户级别的日志记录配置将决定如何记录 AWS IoT 活动。首先，您可能需要获取默认[日志级别](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level)为 INFO 或 DEBUG 的详细日志。查看初始日志后，您可以将默认日志级别更改为不那么详细的级别，例如账户或事件级别的 WARN 或 ERROR，并对可能需要更多关注的资源设置更详细的特定于资源的日志级别。日志级别可随时更改。 本主题介绍云端登录。 AWS IoT有关设备端日志记录和监控的信息，请参阅[将设备端日志上传](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch.html)到。 CloudWatch 有关日志记录和监控的信息 AWS IoT Greengrass，请参阅[中的日志和监控 AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/v2/developerguide/logging-and-monitoring.html)。 ## 配置 V2 登录 AWS IoT ### 确定您的日志版本 NotConfiguredException 如果未启用 [V2 日志记录，则 GetV2 LoggingOptions API](https://docs.aws.amazon.com/iot/latest/apireference/API_GetV2LoggingOptions.html) 会返回一个。如果正在使用 V1 日志记录或未配置任何日志记录，则会发生此错误。 ### 了解 V2 日志功能 V2 日志记录提供两项关键功能：事件级日志记录和特定于资源的日志记录。事件级别的日志记录支持有针对性的日志配置以及可自定义的日志级别和 CloudWatch 日志组目标。特定资源的日志允许您按事物组、源 IP、客户端 ID 或委托人 ID 筛选日志。这些功能共同提供了对物联网操作的精细控制和全面可见性，通过消除不必要的日志活动来提高日志可搜索性并降低成本。 ### 从 V1 迁移到 V2 [您可以通过 C AWS LI 或 SDK 使用 Setv2 LoggingOptions API 迁移到 V2 日志记录。](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html)迁移后， AWS IoT 自动将所有日志路由到 CloudWatch 日志组 “AWSIotLogsv2”。重要：如果您的下游应用程序或资源消耗了 “日AWSIot志” 中的信息，请更新它们以使用相应的日志组路径。 ## 配置日志记录角色和策略 在启用登录功能之前 AWS IoT，您必须创建一个 IAM 角色和一个策略，该策略 AWS IoT 允许您代表您向 CloudWatch 日志组写入 AWS IoT 日志活动。您还可以在[AWS IoT 控制台的 “日志” 部分](https://console.aws.amazon.com/iot/home#/settings/logging)生成具有所需策略的 IAM 角色。 **注意** 在启用 AWS IoT 日志记录之前，请确保您了解 CloudWatch 日志访问权限。有权访问 CloudWatch 日志的用户可以从您的设备中查看调试信息。有关更多信息，请参阅 [Amazon CloudWatch 日志的身份验证和访问控制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html)。 如果您预计 AWS IoT Core 由于负载测试而出现高流量模式，请考虑禁用 IoT 日志以防止限制。如果检测到高流量，我们的服务可能会禁用您账户中的日志记录。 以下内容显示了如何为 AWS IoT Core 资源创建日志记录角色和策略。 ### 创建日志记录角色 要创建日志记录角色，请打开 [IAM 控制台的角色中心](https://console.aws.amazon.com/iam/home#/roles)并选择 **Create role**（创建角色）。 1. 在**选择受信任的实体**下，选择 **AWS 服务**。然后在**使用案例**下，选择 **IoT**。如果您看不到 **IoT**，请在**其他 AWS 服务的使用案例：**下拉菜单中输入并搜索 **IoT**。选择**下一步**。 1. 在 **Add permissions**（添加权限）页面上，您将看到自动附加到服务角色的策略。选择**下一步**。 1. 在 **Name, review, and create**（命名、检查和创建）页面上，为此角色输入 **Role name**（角色名称）和 **Role description**（角色描述），然后选择 **Create role**（创建角色）。 ### 日志记录角色策略 以下策略文件提供了允许代表您 AWS IoT 向其提交日志条目的角色策略和信任策略。 CloudWatch 如果您使用自定义日志组配置事件级 CloudWatch 日志记录，则必须更新角色策略以包含自定义资源 ARN。 如果您还 适用于 LoRaWAN 的 AWS IoT Core 允许提交日志条目，则会看到一份为您创建的策略文档，其中记录了这两项活动。 **注意** 在您创建日志记录角色时已为您创建这些文档。这些文档包含变量* `${partition}`, ** `${region}` *、和* `${accountId}` *，必须将其替换为自己的值。 将分区替换为该区域的分区。 将区域替换为您使用的 AWS 区域。确保您使用的 AWS 区域与在设备上配置 AWS CLI 时使用的区域相同。 用您的账户 ID 替换 AWS 账户 ID。 角色策略： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:PutMetricFilter", "logs:PutRetentionPolicy", "iot:GetLoggingOptions", "iot:SetLoggingOptions", "iot:SetV2LoggingOptions", "iot:GetV2LoggingOptions", "iot:SetV2LoggingLevel", "iot:ListV2LoggingLevels", "iot:DeleteV2LoggingLevel" ], "Resource": [ "arn:aws:logs:us-east-1:123456789012:log-group:AWSIotLogsV2:*" ] } ] } ``` 仅记录 AWS IoT Core 活动的信任策略： **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` AWS IoT 由于 IAM 角色权限不足， CloudWatch 日志可能无法将日志发布到日志。发生这种情况时，请检查[ CloudWatch 日志指标](https://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html#logging-metrics)以调查故障并对其进行故障排除。 ## 在 AWS IoT （控制台）中配置日志记录 本节介绍如何使用 AWS IoT 控制台配置 AWS IoT 日志记录。您可以设置账户级别、事件级别和特定资源的日志记录。 **要配置 AWS IoT 记录，请执行以下操作：** 1. 登录 AWS IoT 控制台。有关更多信息，请参阅 [打开控制 AWS IoT 台](setting-up.md#iot-console-signin)。 1. 在左侧导航窗格中，选择 “**日志**”（以前是 “设置” 下的部分）。 1. 配置账户级日志记录：账户级别的日志记录适用于您的所有 AWS IoT 队列（设备或终端节点），除非被事件级别或特定资源的设置所覆盖。 1. 在 “账户级日志记录” 下，选择 “**管理账户级日志记录**” 以进行更新。 1. 选择 “启用日志记录” 复选框以开始向其发送日志 CloudWatch。如果未选中 “启用日志记录”，则无论事件级别或资源级别的日志记录配置如何，都 AWS IoT 不会向 CloudWatch 日志组发送任何日志。 1. 在 **IAM 日志角色**下，从下拉列表中选择一个现有角色。您可以**查看角色详细信息**以检查角色权限。或者，选择**创建新角色**来设置新的 IAM 角色。日志角色提供的策略允许代表您 AWS IoT 向提交日志条目。 CloudWatch 如果您使用自定义日志组配置事件级 CloudWatch 日志记录，则必须更新角色策略以包含该日志组的 ARN。 1. 选择与要在**日志中显示[的日志条目的详细级别](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level)相对应的 “默认** CloudWatch 日志” 级别。注意：日志级别 “DEBUG” 提供了最多的细节，但会增加 CloudWatch 成本。 CloudWatch 无法在账户级别配置日志组目标。但是，您可以为各个事件类型指定自定义日志组，如下一节所述。 1. 选择 “**更新日志记录**” 以保存您的更改。 1. 事件级日志允许您有选择地捕获相关事件的日志，并将其定向到专用的 CloudWatch 日志组。这使您可以灵活地按用例组织日志，以提高可发现性，与不同的受众共享，并通过启用日志和根据事件重要性设置日志级别来降低 CloudWatch 成本。 配置**事件级别的日志记录：事件级别**的日志记录会捕获特定 AWS IoT 事件，例如客户端身份验证尝试。这些设置会覆盖账户级别的日志记录。 1. 在 “**事件级日志记录**” 部分下，选择 “**管理事件级日志记录**” 以进行更新。 1. 默认情况下，事件类型继承账户级别的日志配置。注意：配置特定资源的日志记录后，它会覆盖账户和事件级别的设置。 1. 要修改单个事件的设置，请单击相应事件行中的值。您可以调整日志级别和 CloudWatch 日志组目标。指定自定义 CloudWatch 日志组目标时，必须验证 IAM 角色策略是否包含新日志组的权限。如果不更新角色策略，则无法 AWS IoT 将日志写入自定义日志组。做出选择后，单击复选标记以确认您的选择。**“已修改” 列将显示 “是”**，以指示待处理的更改。 1. 单击 “**更新日志**” 以应用您的更改，或者选择 “**取消**” 放弃。 1. 配置特定于资源的覆盖：资源特定的覆盖将日志设置应用于选定的资源。资源可以是事物组、源 IP、客户端 ID 或委托人 ID。特定于资源的日志配置会覆盖账户级别和事件级别的设置。启用后，它会在为指定资源配置的日志级别为所有事件类型生成日志。例如，您可以为特定事物设置调试级别的日志记录，同时为所有其他事物保留信息级别的日志记录。 1. 在 “**资源特定覆盖” 部分中选择 “添加特定于资源的替代**”。 1. 选择日志目标：事物组、源 IP、客户端 ID 或主体 ID。 1. 为所选目标类型输入相应的日志目标值。 1. 从 “特定于资源的日志级别” 部分的下拉菜单中选择所需的日志级别。 1. 单击 “**提交**” 添加改写，或单击 “**取消”** 放弃更改。 1. 要修改现有的特定于资源的替代，请选中资源旁边的复选框，然后单击 “移除” 以删除覆盖或单击 “编辑” 进行修改。 启用日志记录后，请访问 [在 CloudWatch 控制台中查看 AWS IoT 日志](cloud-watch-logs.md#viewing-logs) 以了解有关查看日志条目的更多信息。 ## 配置账户和事件级别登录 ( AWS IoT CLI) 本节介绍如何使用 CLI 为 AWS IoT 配置全局日志。 您可以选择配置事件级别的日志记录。事件级别的日志记录捕获事件级别的日志信息，例如身份验证和授权或证书创建事件。您可以在事件级别自定义日志级别和 CloudWatch 日志组目标。与账户级日志相比，事件级别的日志记录在更具针对性的级别上运行，因此会覆盖账户级别的日志记录设置。这种分层方法允许您根据事件的操作重要性和成本考虑因素为不同类型的事件维护不同的日志记录策略。 **注意** 您需要提供要使用角色的 Amazon 资源名称（ARN）。如果需要创建用于日志记录的角色，请参阅 [创建日志记录角色](#create-logging-role)，然后继续操作。为任何事件类型指定自定义 CloudWatch日志组时，请确保您的日志记录角色具有目标日志组所需的权限。 用于调用 API 的委托人对于您的日志记录角色必须具有[传递角色权限](pass-role.md)。 您也可以使用 API 中与此处显示的 CLI 命令相对应的方法，对 AWS API 执行此过程。 **使用 CLI 配置默认日志记录 AWS IoT** 1. 使用 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html) 命令为您的账户设置日志记录选项。 ``` aws iot set-v2-logging-options \ --event-configurations event-configuration-list \ --role-arn logging-role-arn \ --default-log-level log-level ``` 其中： **--role-arn** 授予在日志中写入日志 AWS IoT 权限的角色 ARN。 CloudWatch 初始设置需要角色ARN配置。 **--default-log-level** 要使用的[日志级别](#log-level)。有效值为：`ERROR``WARN`、`INFO`、`DEBUG`、或`DISABLED`。 Default-log-level初始设置需要进行配置。 **--no-disable-all-logs** 一个可选参数，用于启用所有 AWS IoT 日志记录。使用此参数可在当前禁用日志记录时启用日志记录。 **--disable-all-logs** 一个可选参数，用于禁用所有 AWS IoT 日志记录。使用此参数可在当前启用日志记录时禁用日志记录。 **--event-configurations** 此参数是可选的，允许您为各个事件类型自定义日志设置： + EventType：覆盖账户级别设置的事件类型 + LogLevel：使用 “调试”、“信息”、“错误”、“警告” 或 “已禁用” 来覆盖账户级别的设置 + LogDestination：为 CloudWatch 日志传输指定自定义日志组 您可以为每种事件类型单独配置日志级别和日志目标。如果未指定，则事件将继承账户级别的设置 ``` aws iot set-v2-logging-options \ --event-configurations "[{\"eventType\":\"Publish-In\",\"logLevel\":\"INFO\",\"logDestination\":\"examplePublishInLogGroup\"}]" ``` 1. 使用 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/get-v2-logging-options.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/get-v2-logging-options.html) 命令获取当前日志记录选项。 ``` aws iot get-v2-logging-options \ --verbose ``` 其中： **--verbose** 一个可选参数，用于检索所有 EventType 及其配置。 启用日志记录后，请访问 [在 CloudWatch 控制台中查看 AWS IoT 日志](cloud-watch-logs.md#viewing-logs) 以了解有关查看日志条目的更多信息。 **注意** AWS IoT 继续支持旧命令（**set-logging-options**和**get-logging-options**），以便在您的账户上设置和获取全局登录。请注意，使用这些命令时，生成的日志将包含纯文本而不是 JSON 有效载荷，并且日志记录延迟通常会更高。将不会再对这些较早命令的实施进行更多改进。我们建议您使用 [“v2” 版本](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2)来配置日志记录选项，并在可能的情况下更改使用旧版本的旧版应用程序。 ## 在 ( AWS IoT CLI) 中配置特定于资源的替代 本节介绍如何使用 CLI 为 AWS IoT 配置特定于资源的替代。资源特定的覆盖允许您为由事物组、客户端 ID、源 IP 或委托人 ID 标识的特定资源指定日志级别。启用特定资源的日志记录后，它会覆盖账户级别和事件级别的设置。所有事件类型都将在配置的日志级别为指定资源生成日志，即使这些事件在事件级别配置中被禁用。 事物组可包含其它事物组以创建分层关系。此流程介绍如何配置单个事物组的日志记录。您可以将此流程应用于层次结构中的父事物组，以配置层次结构中所有事物组的日志记录。您也可以将此流程应用于子事情组，以覆盖其父级的日志记录配置。 一个事物可以是一个事物组的成员。这种成员资格允许该事物继承应用于该事物组的配置、策略和设置。事物组用于集体管理和应用设置到多个事物，而不是单独处理每个事物。当您的客户端 ID 与事物名称匹配时， AWS IoT Core 会自动将客户端会话与相应的事物资源相关联。这允许客户端会话继承应用于该事物所属事物组的配置和设置，包括日志记录级别。如果您的客户端 ID 与事物名称不匹配，您可以启用独占事物附件来建立关联。有关更多信息，请参阅 [将 AWS IoT 事物关联到 MQTT 客户端连接](exclusive-thing.md)。 除了事物组之外，您还可以录入目标，例如设备的客户端 ID、源 IP 和主体 ID。 **注意** 您需要提供要使用角色的 Amazon 资源名称（ARN）。如果需要创建用于日志记录的角色，请参阅 [创建日志记录角色](#create-logging-role)，然后继续操作。 用于调用 API 的委托人对于您的日志记录角色必须具有[传递角色权限](pass-role.md)。 您也可以使用 API 中与此处显示的 CLI 命令相对应的方法，对 AWS API 执行此过程。 **使用 CLI 为以下各项配置特定于资源的替代 AWS IoT** 1. 在配置特定资源的日志记录之前，使用以下命令启用账户级日志记录：aws iot set-v2-logging-options 命令 1. 使用[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-level.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-level.html)命令配置特定于资源的替代。有关事物组配置，请参阅以下示例： ``` aws iot set-v2-logging-level \ --log-target targetType=THING_GROUP,targetName=thing_group_name \ --log-level log_level ``` **--log-target** 您要配置日志记录的资源的类型和名称。`targetType` 值必须是下列项之一：`THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`。log-target 参数值可以是文本（如前面的命令示例所示），也可以是 JSON 字符串，如以下示例所示。 ``` aws iot set-v2-logging-level \ --log-target '{"targetType": "THING_GROUP","targetName": "thing_group_name"}' \ --log-level log_level ``` **--log-level** 为指定资源生成日志时使用的日志记录级别。有效值为：**DEBUG**、**INFO**、**ERROR**、**WARN** 和 **DISABLED**。 1. 使用 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-v2-logging-levels.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-v2-logging-levels.html) 命令列出当前配置的日志记录级别。 ``` aws iot list-v2-logging-levels ``` 1. 使用 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-v2-logging-level.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-v2-logging-level.html) 命令删除资源特定的日志记录级别，比如下面的例子。 ``` aws iot delete-v2-logging-level \ --target-type "THING_GROUP" \ --target-name "thing_group_name" ``` ``` aws iot delete-v2-logging-level \ --target-type=CLIENT_ID --target-name=ClientId1 ``` **--target-type** `target-type` 值必须是下列项之一：`THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`。 **--target-name** 要删除日志记录级别的事物组的名称。 ## 日志级别 这些日志级别确定记录的事件，并应用于默认日志级别和资源特定的日志级别。 ERROR 导致操作失败的任何错误。 示例：由于证书过期，无法对设备进行身份验证。 日志仅包含 ERROR 信息。 警告 可能导致系统中出现不一致问题，但不会导致操作失败的所有情况。 示例：接近消息速率限制。 日志包括 ERROR 和 WARN 信息。 INFO 有关事物流的高级别信息。 示例：客户端成功订阅了 MQTT 主题。 日志包括 INFO、ERROR 和 WARN 信息。 调试 可能有助于调试问题的信息。 示例：物联网规则引擎检测到一条发布到规则主题 “规则/测试” 的消息并成功开始执行。该规则配置为 RepublishAction。 日志包括 DEBUG、INFO、ERROR 和 WARN 信息。 DISABLED 所有日志记录均处于禁用状态。