终止支持通知：2026 年 10 月 7 日， AWS 将停止对的支持。 AWS IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 AWS IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # CloudWatch 指标连接器 CloudWatch 指标[连接器](connectors.md)将来自 Greengrass 设备的自定义指标发布到亚马逊。 CloudWatch该连接器提供了一个用于发布 CloudWatch 指标的集中式基础架构，您可以使用该基础架构来监控和分析 Greengrass 核心环境，并对本地事件采取行动。有关更多信息，请参阅[亚马逊* CloudWatch 用户指南中的使用亚马逊 CloudWatch *指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。 此连接器以 MQTT 消息形式接收指标数据。连接器会对位于同一命名空间中的指标进行批处理，并定期将其发布到 CloudWatch 。 此连接器具有以下版本。 | 版本 | 进行筛选 | | --- | --- | | 5 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/5` | | 4 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4` | | 3 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/3` | | 2 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/2` | | 1 | `arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/1` | 有关版本更改的信息，请参阅[更改日志](#cloudwatch-metrics-connector-changelog)。 ## 要求 此连接器具有以下要求： ------ #### [ Version 3 - 5 ] + AWS IoT Greengrass 核心软件 v1.9.3 或更高版本。 + [Python](https://www.python.org/) 版本 3.7 或 3.8 已安装在核心设备上，并已添加到 PATH 环境变量中。 **注意** 要使用 Python 3.8，请运行以下命令来创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。 ``` sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7 ``` 这会将设备配置为满足 AWS IoT Greengrass的 Python 要求。 + [Greengrass 组角色](group-role.md)，配置为允许执行 `cloudwatch:PutMetricData` 操作，如以下示例 AWS Identity and Access Management IAM policy 中所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "cloudwatch:PutMetricData" ], "Effect": "Allow", "Resource": "*" } ] } ``` ------ 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 有关 CloudWatch 权限的更多信息，请参阅 IA *M 用户指南*中的 A [mazon CloudWatch 权限参考](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html)。 ------ #### [ Versions 1 - 2 ] + AWS IoT Greengrass 核心软件 v1.7 或更高版本。 + [Python](https://www.python.org/) 版本 2.7 已安装在核心设备上，并已添加到 PATH 环境变量中。 + [Greengrass 组角色](group-role.md)，配置为允许执行 `cloudwatch:PutMetricData` 操作，如以下示例 AWS Identity and Access Management IAM policy 中所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "cloudwatch:PutMetricData" ], "Effect": "Allow", "Resource": "*" } ] } ``` ------ 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 有关 CloudWatch 权限的更多信息，请参阅 IA *M 用户指南*中的 A [mazon CloudWatch 权限参考](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html)。 ------ ## 连接器参数 该连接器提供以下参数： ------ #### [ Versions 4 - 5 ] `PublishInterval` 发布给定命名空间的批处理指标之前等待的最长秒数。最大值为 900。要将连接器配置为一收到指标便发布（而不进行批处理），请指定 0。 连接器在同一命名空间中收到 20 个指标后或在指定的时间间隔之后发布到。 CloudWatch 连接器不保证发布事件的顺序。 AWS IoT 控制台中的显示名称：**发布间隔** 必需：`true` 类型：`string` 有效值：`0 - 900` 有效模式：`[0-9]|[1-9]\d|[1-9]\d\d|900` `PublishRegion` AWS 区域 要向其发布 CloudWatch 指标的。该值会覆盖默认 Greengrass 指标区域。该值仅在发布跨区域指标时是必需的。 AWS IoT 控制台中的显示名称：**发布区域** 必需：`false` 类型：`string` 有效模式：`^$|([a-z]{2}-[a-z]+-\d{1})` `MemorySize` 要分配给连接器的内存 (KB)。 AWS IoT 控制台中的显示名称：**内存大小** 必需：`true` 类型：`string` 有效模式：`^[0-9]+$` `MaxMetricsToRetain` 替换为新指标之前所有命名空间内可在内存中保存的指标的最大数量。最小值为 2000。 此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时，最旧的指标将被新的指标所替换。给定命名空间中的指标仅被同一命名空间中的指标所替换。 如果连接器的宿主进程中断，则不会保存指标。例如，在组部署或设备重新启动期间，可能会发生此中断。 AWS IoT 控制台中的显示名称：**要保留的最大指标** 必需：`true` 类型：`string` 有效模式：`^([2-9]\d{3}|[1-9]\d{4,})$` `IsolationMode` 此连接器的[容器化](connectors.md#connector-containerization)模式。默认值为`GreengrassContainer`，这意味着连接器在 AWS IoT Greengrass 容器内的隔离运行时环境中运行。 组的默认容器化设置不适用于连接器。 AWS IoT 控制台中的显示名称：**容器隔离模式** 必需：`false` 类型：`string` 有效值：`GreengrassContainer` 或 `NoContainer` 有效模式：`^NoContainer$|^GreengrassContainer$` ------ #### [ Versions 1 - 3 ] `PublishInterval` 发布给定命名空间的批处理指标之前等待的最长秒数。最大值为 900。要将连接器配置为一收到指标便发布（而不进行批处理），请指定 0。 连接器在同一命名空间中收到 20 个指标后或在指定的时间间隔之后发布到。 CloudWatch 连接器不保证发布事件的顺序。 AWS IoT 控制台中的显示名称：**发布间隔** 必需：`true` 类型：`string` 有效值：`0 - 900` 有效模式：`[0-9]|[1-9]\d|[1-9]\d\d|900` `PublishRegion` AWS 区域 要向其发布 CloudWatch 指标的。该值会覆盖默认 Greengrass 指标区域。该值仅在发布跨区域指标时是必需的。 AWS IoT 控制台中的显示名称：**发布区域** 必需：`false` 类型：`string` 有效模式：`^$|([a-z]{2}-[a-z]+-\d{1})` `MemorySize` 要分配给连接器的内存 (KB)。 AWS IoT 控制台中的显示名称：**内存大小** 必需：`true` 类型：`string` 有效模式：`^[0-9]+$` `MaxMetricsToRetain` 替换为新指标之前所有命名空间内可在内存中保存的指标的最大数量。最小值为 2000。 此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时，最旧的指标将被新的指标所替换。给定命名空间中的指标仅被同一命名空间中的指标所替换。 如果连接器的宿主进程中断，则不会保存指标。例如，在组部署或设备重新启动期间，可能会发生此中断。 AWS IoT 控制台中的显示名称：**要保留的最大指标** 必需：`true` 类型：`string` 有效模式：`^([2-9]\d{3}|[1-9]\d{4,})$` ------ ### 创建连接器示例 (AWS CLI) 以下 CLI 命令`ConnectorDefinition`使用包含 Metr CloudWatch ics 连接器的初始版本创建一个。 ``` aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyCloudWatchMetricsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4", "Parameters": { "PublishInterval" : "600", "PublishRegion" : "us-west-2", "MemorySize" : "16", "MaxMetricsToRetain" : "2500", "IsolationMode" : "GreengrassContainer" } } ] }' ``` 在 AWS IoT Greengrass 控制台中，您可以从群组的 “连接器” 页面添加**连接器**。有关更多信息，请参阅 [Greengrass 连接器入门（控制台）](connectors-console.md)。 ## 输入数据 此连接器接受 MQTT 主题的指标并将这些指标发布到。 CloudWatch输入消息必须采用 JSON 格式。 **订阅中的主题筛选条件** `cloudwatch/metric/put` **消息属性** `request` 有关此消息中的指标的信息。 请求对象包含要发布到 CloudWatch 的指标数据。指标值必须符合 [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) API 的规范。只有 `namespace`、`metricData.metricName` 和 `metricData.value` 属性是必需的。 必需：`true` 类型：包含以下属性的 `object`： `namespace` 此请求中指标数据的用户定义命名空间。 CloudWatch 使用命名空间作为指标数据点的容器。 不能指定以保留字符串 `AWS/` 开头的命名空间。 必需：`true` 类型：`string` 有效模式：`[^:].*` `metricData` 指标的数据。 必需：`true` 类型：包含以下属性的 `object`： `metricName` 指标的名称。 必需：`true` 类型：`string` `dimensions` 与指标关联的维度。维度提供有关指标及其数据的更多信息。指标最多可定义 10 个维度。 此连接器自动包含一个名为 `coreName` 的维度，其中的值是核心的名称。 必需：`false` 类型：维对象的 `array` 包含以下属性： `name` 维度名称。 必需：`false` 类型：`string` `value` 维度值。 必需：`false` 类型：`string` `timestamp` 收到指标数据的时间，表示为自 `Jan 1, 1970 00:00:00 UTC` 以来的秒数。如果省略此值，则连接器将使用它收到消息的时间。 必需：`false` 类型：`timestamp` 如果您使用此连接器的版本 1 到版本 4，我们建议您在从单一来源发送多个指标时分别检索每个指标的时间戳。不要使用变量来存储时间戳。 `value` 指标的值。 CloudWatch 拒绝太小或太大的值。值必须在范围 `8.515920e-109` 到 `1.174271e+108`（以 10 为底的指数）内或范围 `2e-360` 到 `2e360`（以 2 为底的指数）内。不支持特殊值（例如 `NaN`、`+Infinity`、`-Infinity`）。 必需：`true` 类型：`double` `unit` 指标的单位。 必需：`false` 类型：`string` 有效值：`Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent, Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second, Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/Second, Terabits/Second, Count/Second, None` 限制 使用此连接器时， CloudWatch [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)API 施加的所有限制都适用于指标。以下限制尤其重要： + API 负载的 40 KB 限制 + 每个 API 请求的 20 个指标 + `PutMetricData` API 的每秒 150 个事务 (TPS) 有关更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[CloudWatch 限制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_limits.html)。 **示例输入** ``` { "request": { "namespace": "Greengrass", "metricData": { "metricName": "latency", "dimensions": [ { "name": "hostname", "value": "test_hostname" } ], "timestamp": 1539027324, "value": 123.0, "unit": "Seconds" } } } ``` ## 输出数据 此连接器将状态信息发布为 MQTT 主题的输出数据。 **订阅中的主题筛选条件** `cloudwatch/metric/put/status` **示例输出：成功** 响应包括指标数据的命名空间和 CloudWatch 响应中的`RequestId`字段。 ``` { "response": { "cloudwatch_rid":"70573243-d723-11e8-b095-75ff2EXAMPLE", "namespace": "Greengrass", "status":"success" } } ``` **示例输出：失败** ``` { "response" : { "namespace": "Greengrass", "error": "InvalidInputException", "error_message":"cw metric is invalid", "status":"fail" } } ``` 如果连接器检测到可重试的错误（如连接错误），它会在下一批次中重试发布。 ## 用法示例 使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。 **注意** 如果要使用其他 Python 运行时，您可以创建从 Python3.x 到 Python 3.7 的符号链接。 [连接器入门（控制台）](connectors-console.md) 和 [连接器入门 (CLI)](connectors-cli.md) 主题包含详细步骤，说明如何配置和部署示例 Twilio 通知连接器。 1. 确保满足连接器的[要求](#cloudwatch-metrics-connector-req)。 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 1. 创建并发布将输入数据发送到连接器的 Lambda 函数。 将[示例代码](#cloudwatch-metrics-connector-usage-example)保存为 PY 文件。下载并解压[适用于 Python 的AWS IoT Greengrass Core 软件开发工具包](lambda-functions.md#lambda-sdks-core)。然后，创建一个 zip 包，其中在根级别包含 PY 文件和 `greengrasssdk` 文件夹。此 zip 包是您上传到 AWS Lambda的部署包。 创建 Python 3.7 Lambda 函数后，请发布函数版本并创建别名。 1. 配置 Greengrass 组。 1. 通过别名来添加 Lambda 函数（推荐）。将 Lambda 生命周期配置为长时间生存（或在 CLI 中设置为 `"Pinned": true`）。 1. 添加连接器并配置其[参数](#cloudwatch-metrics-connector-param)。 1. 添加允许连接器接收[输入数据](#cloudwatch-metrics-connector-data-input)并针对支持的主题筛选条件发送[输出数据](#cloudwatch-metrics-connector-data-output)的订阅。 + 将 Lambda 函数设置为源，将连接器设置为目标，并使用支持的输入主题筛选条件。 + 将连接器设置为源，将 AWS IoT Core 设置为目标，并使用支持的输出主题筛选条件。您可以使用此订阅在 AWS IoT 控制台中查看状态消息。 1. 部署组。 1. 在 AWS IoT 控制台的 “**测试**” 页面上，订阅输出数据主题以查看来自连接器的状态消息。示例 Lambda 函数是长时间生存的，并且在部署组后立即开始发送消息。 完成测试后，您可以将 Lambda 生命周期设置为按需（或在 CLI 中设置为 `"Pinned": false`）并部署组。这会阻止函数发送消息。 ### 示例 以下示例 Lambda 函数向连接器发送一条输入消息。 ``` import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'cloudwatch/metric/put' def create_request_with_all_fields(): return { "request": { "namespace": "Greengrass_CW_Connector", "metricData": { "metricName": "Count1", "dimensions": [ { "name": "test", "value": "test" } ], "value": 1, "unit": "Seconds", "timestamp": time.time() } } } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return ``` ## 许可证 CloudWatch Metrics 连接器包括以下第三方软件/许可： + [适用于 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache 许可证 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache 许可证 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF 许可证 + [docutils](https://pypi.org/project/docutils/)/BSD 许可证，GNU 通用公共许可证 (GPL)，Python 软件基金会许可证，公共领域 + [jmespath](https://pypi.org/project/jmespath/)/MIT 许可证 + [s3transfer](https://pypi.org/project/s3transfer/)/Apache 许可证 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT 许可证 该连接器在 [Greengrass Core 软件许可协议](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)下发布。 ## 更改日志 下表介绍每个版本连接器的更改。 | 版本 | 更改 | | --- | --- | | 5 | 进行了修复，以添加输入数据中对重复时间戳的支持。 | | 4 | 增加了用于配置连接器容器化模式的 `IsolationMode` 参数。 | | 3 | 已将 Lambda 运行时升级到 Python 3.7，这会更改运行时要求。 | | 2 | 进行了修复，以减少过多的日志记录。 | | 1 | 初始版本。 | Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅[升级连接器版本](connectors.md#upgrade-connector-versions)。 ## 另请参阅 + [使用 Greengrass 连接器与服务和协议集成](connectors.md) + [Greengrass 连接器入门（控制台）](connectors-console.md) + [Greengrass 连接器入门 (CLI)](connectors-cli.md) + [使用亚马逊* CloudWatch 用户指南中的亚马逊 CloudWatch *指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) + [ PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)在 *Amazon CloudWatch API 参考*中