CloudWatch 指标 连接器 - AWS IoT Greengrass
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

CloudWatch 指标 连接器

CloudWatch 指标连接器将 Greengrass 设备中的自定义指标发布到 Amazon CloudWatch。此连接器提供了一个用于发布 CloudWatch 指标的集中式基础设施,您可以使用它来监控和分析 Greengrass 核心环境,以及处理本地事件。有关更多信息,请参阅 Amazon CloudWatch 用户指南 中的使用 Amazon CloudWatch 指标

此连接器以 MQTT 消息形式接收指标数据。连接器对同一命名空间中的指标进行批处理,并定期将这些指标发布到 CloudWatch。

此连接器具有以下版本。

版本

ARN

4

arn:aws:greengrass:区域::/connectors/CloudWatchMetrics/versions/4

3

arn:aws:greengrass:区域::/connectors/CloudWatchMetrics/versions/3

2

arn:aws:greengrass:区域::/connectors/CloudWatchMetrics/versions/2

1

arn:aws:greengrass:区域::/connectors/CloudWatchMetrics/versions/1

有关版本更改的信息,请参阅更改日志

要求

此连接器具有以下要求:

Version 4
  • AWS IoT Greengrass Core 软件 v1.9.3 版或更高版本。

  • Python 版本 3.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • Greengrass 组角色,配置为允许执行 cloudwatch:PutMetricData 操作,如以下示例 IAM 策略中所示。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "cloudwatch:PutMetricData" ], "Effect": "Allow", "Resource": "*" } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

    有关 CloudWatch 权限的更多信息,请参阅 IAM 用户指南 中的 Amazon CloudWatch 权限参考

Version 3
  • AWS IoT Greengrass Core 软件 v1.9.3 版或更高版本。

  • Python 版本 3.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • Greengrass 组角色,配置为允许执行 cloudwatch:PutMetricData 操作,如以下示例 IAM 策略中所示。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "cloudwatch:PutMetricData" ], "Effect": "Allow", "Resource": "*" } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

    有关 CloudWatch 权限的更多信息,请参阅 IAM 用户指南 中的 Amazon CloudWatch 权限参考

Versions 1 - 2
  • AWS IoT Greengrass Core 软件 v1.7 or later。

  • Python 版本 2.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • Greengrass 组角色,配置为允许执行 cloudwatch:PutMetricData 操作,如以下示例 IAM 策略中所示。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "cloudwatch:PutMetricData" ], "Effect": "Allow", "Resource": "*" } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

    有关 CloudWatch 权限的更多信息,请参阅 IAM 用户指南 中的 Amazon CloudWatch 权限参考

连接器参数

该连接器提供以下参数:

Version 4
PublishInterval

发布给定命名空间的批处理指标之前等待的最长秒数。最大值为 900。要将连接器配置为一收到指标便发布(而不进行批处理),请指定 0。

连接器在同一命名空间中或在经过指定间隔收到 20 个指标之后发布到 CloudWatch。

注意

连接器不保证发布事件的顺序。

在 AWS IoT 控制台中显示名称:Publish interval (发布间隔)

必需:true

类型:string

有效值:0 - 900

有效模式:[0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

要将 CloudWatch 指标发布到的 AWS 区域。该值会覆盖默认 Greengrass 指标区域。该值仅在发布跨区域指标时是必需的。

在 AWS IoT 控制台中显示名称:Publish region (发布区域)

必需:false

类型:string

有效模式:^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

要分配给连接器的内存 (KB)。

在 AWS IoT 控制台中显示名称:Memory size (内存大小)

必需:true

类型:string

有效模式:^[0-9]+$

MaxMetricsToRetain

替换为新指标之前所有命名空间内可在内存中保存的指标的最大数量。最小值为 2000。

此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时,最旧的指标将被新的指标所替换。给定命名空间中的指标仅被同一命名空间中的指标所替换。

注意

如果连接器的宿主进程中断,则不会保存指标。例如,在组部署或设备重新启动期间,可能会发生此中断。

在 AWS IoT 控制台中显示名称:Maximum metrics to retain (可保留的最大指标数)

必需:true

类型:string

有效模式: ^([2-9]\d{3}|[1-9]\d{4,})$

IsolationMode

此连接器的容器化模式。默认值为 GreengrassContainer,这意味着连接器在 AWS IoT Greengrass 容器内的隔离运行时环境中运行。

注意

组的默认容器化设置不适用于连接器。

在 AWS IoT 控制台中显示名称:容器隔离模式

必需:false

类型:string

有效值:GreengrassContainerNoContainer

有效模式:^NoContainer$|^GreengrassContainer$

Version 3
PublishInterval

发布给定命名空间的批处理指标之前等待的最长秒数。最大值为 900。要将连接器配置为一收到指标便发布(而不进行批处理),请指定 0。

连接器在同一命名空间中或在经过指定间隔收到 20 个指标之后发布到 CloudWatch。

注意

连接器不保证发布事件的顺序。

在 AWS IoT 控制台中显示名称:Publish interval (发布间隔)

必需:true

类型:string

有效值:0 - 900

有效模式:[0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

要将 CloudWatch 指标发布到的 AWS 区域。该值会覆盖默认 Greengrass 指标区域。该值仅在发布跨区域指标时是必需的。

在 AWS IoT 控制台中显示名称:Publish region (发布区域)

必需:false

类型:string

有效模式:^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

要分配给连接器的内存 (KB)。

在 AWS IoT 控制台中显示名称:Memory size (内存大小)

必需:true

类型:string

有效模式:^[0-9]+$

MaxMetricsToRetain

替换为新指标之前所有命名空间内可在内存中保存的指标的最大数量。最小值为 2000。

此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时,最旧的指标将被新的指标所替换。给定命名空间中的指标仅被同一命名空间中的指标所替换。

注意

如果连接器的宿主进程中断,则不会保存指标。例如,在组部署或设备重新启动期间,可能会发生此中断。

在 AWS IoT 控制台中显示名称:Maximum metrics to retain (可保留的最大指标数)

必需:true

类型:string

有效模式: ^([2-9]\d{3}|[1-9]\d{4,})$

Versions 1 - 2
PublishInterval

发布给定命名空间的批处理指标之前等待的最长秒数。最大值为 900。要将连接器配置为一收到指标便发布(而不进行批处理),请指定 0。

连接器在同一命名空间中或在经过指定间隔收到 20 个指标之后发布到 CloudWatch。

注意

连接器不保证发布事件的顺序。

在 AWS IoT 控制台中显示名称:Publish interval (发布间隔)

必需:true

类型:string

有效值:0 - 900

有效模式:[0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

要将 CloudWatch 指标发布到的 AWS 区域。该值会覆盖默认 Greengrass 指标区域。该值仅在发布跨区域指标时是必需的。

在 AWS IoT 控制台中显示名称:Publish region (发布区域)

必需:false

类型:string

有效模式:^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

要分配给连接器的内存 (KB)。

在 AWS IoT 控制台中显示名称:Memory size (内存大小)

必需:true

类型:string

有效模式:^[0-9]+$

MaxMetricsToRetain

替换为新指标之前所有命名空间内可在内存中保存的指标的最大数量。最小值为 2000。

此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时,最旧的指标将被新的指标所替换。给定命名空间中的指标仅被同一命名空间中的指标所替换。

注意

如果连接器的宿主进程中断,则不会保存指标。例如,在组部署或设备重新启动期间,可能会发生此中断。

在 AWS IoT 控制台中显示名称:Maximum metrics to retain (可保留的最大指标数)

必需:true

类型:string

有效模式: ^([2-9]\d{3}|[1-9]\d{4,})$

创建连接器示例 (AWS CLI)

以下 CLI 命令创建一个 ConnectorDefinition,其初始版本包含 CloudWatch 指标连接器。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyCloudWatchMetricsConnector", "ConnectorArn": "arn:aws:greengrass:区域::/connectors/CloudWatchMetrics/versions/4", "Parameters": { "PublishInterval" : "600", "PublishRegion" : "us-west-2", "MemorySize" : "16", "MaxMetricsToRetain" : "2500", "IsolationMode" : "GreengrassContainer" } } ] }'

在 AWS IoT Greengrass 控制台 中,您可以从该组的 Connectors (连接器)页面添加一个连接器。有关更多信息,请参阅 Greengrass 连接器入门(控制台)

输入数据

此连接器接受有关 MQTT 主题的指标,并将这些指标发布到 CloudWatch。输入消息必须采用 JSON 格式。

订阅中的主题筛选条件

cloudwatch/metric/put

消息属性
request

有关此消息中的指标的信息。

请求对象包含要发布到 CloudWatch 的指标数据。指标值必须符合 PutMetricData API 的规范。只有 namespacemetricData.metricNamemetricData.value 属性是必需的。

必需:true

类型:包含以下属性的 object

namespace

此请求中的指标数据的用户定义命名空间。CloudWatch 使用命名空间作为指标数据点的容器。

注意

不能指定以保留字符串“AWS/”开头的命名空间。

必需:true

类型:string

有效模式:[^:].*

metricData

指标的数据。

必需:true

类型:包含以下属性的 object

metricName

指标的名称。

必需:true

类型:string

dimensions

与指标关联的维度。维度提供有关指标及其数据的更多信息。指标最多可定义 10 个维度。

必需:false

类型:维对象的 array 包含以下属性:

name

维度名称。

必需:false

类型:string

value

维度值。

必需:false

类型:string

timestamp

收到指标数据的时间,表示为自 Jan 1, 1970 00:00:00 UTC 以来的毫秒数。如果省略此值,则连接器将使用它收到消息的时间。

必需:false

类型:timestamp

value

指标的值。

注意

CloudWatch 拒绝过小或过大的值。值必须在范围 8.515920e-1091.174271e+108(以 10 为底的指数)内或范围 2e-3602e360(以 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 PutMetricData API 施加的所有限制均适用于指标。以下限制尤其重要:

  • API 负载的 40 KB 限制

  • 每个 API 请求的 20 个指标

  • PutMetricData API 的每秒 150 个事务 (TPS)

有关更多信息,请参阅 Amazon CloudWatch 用户指南 中的 CloudWatch 限制

示例输入
{ "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 函数。

注意

连接器入门(控制台)连接器入门 (CLI) 主题包含详细步骤,说明如何配置和部署示例 Twilio 通知连接器。

 

  1. 确保满足连接器的要求

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅 管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

  2. 创建并发布将输入数据发送到连接器的 Lambda 函数。

    示例代码保存为 PY 文件。 下载并解压缩 适用于 Python 的 AWS IoT Greengrass Core 开发工具包。然后,创建一个 zip 包,其中在根级别包含 PY 文件和 greengrasssdk 文件夹。此 zip 包是您上传到 AWS Lambda 的部署包。

    创建 Python 3.7 Lambda 函数后,发布函数版本并创建别名。

  3. 配置 Greengrass 组。

    1. 通过 Lambda 函数的别名添加此函数(推荐)。将 Lambda 生命周期配置为长时间生存(或在 CLI 中设置为 "Pinned": true)。

    2. 添加连接器并配置其参数

    3. 添加允许连接器接收输入数据并针对支持的主题筛选条件发送输出数据的订阅。

      • 将 Lambda 函数设置为源,将连接器设置为目标,并使用支持的输入主题筛选条件。

      • 将连接器设置为源,将 AWS IoT Core 设置为目标,并使用支持的输出主题筛选条件。您可以使用此订阅查看 AWS IoT 控制台 中的状态消息。

  4. 部署组。

  5. 在 AWS IoT 控制台 中,在 Test (测试) 页面上,订阅输出数据主题以查看连接器中的状态消息。示例 Lambda 函数是长时间生存的,并且在部署组后立即开始发送消息。

    完成测试后,您可以将 Lambda 生命周期设置为按需(或在 CLI 中设置为 "Pinned": false )并部署组。这会阻止函数发送消息。

Ejemplo

以下是 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 指标 连接器包含以下第三方软件/许可:

此连接器按照 Greengrass 核心软件许可协议发布。

Changelog

下表描述了连接器每个版本中所做的更改。

版本

更改

4

增加了用于配置连接器容器化模式的 IsolationMode 参数。

3

已将 Lambda 运行时升级到 Python 3.7,这会更改运行时要求。

2

进行了修复,以减少过多的日志记录。

1

首次发布。

Greengrass 组一次只能包含一个版本的连接器。有关升级连接器版本的信息,请参阅升级连接器版本

另请参阅