CloudWatch 指标 - AWS IoT Greengrass
版本类型操作系统要求依赖项配置输入数据输出数据许可证本地日志文件更改日志另请参阅

CloudWatch 指标

Amazon CloudWatch 指标组件（aws.greengrass.Cloudwatch）将 Greengrass 核心设备中的自定义指标发布到 Amazon CloudWatch。该组件使组件能够发布 CloudWatch 指标，您可以用其来监控和分析 Greengrass 核心设备的环境。有关更多信息，请参阅《Amazon CloudWatch 用户指南》中的使用 Amazon CloudWatch 指标。

要通过此组件发布 CloudWatch 指标，请向此组件订阅的主题发布一条消息。默认情况下，此组件订阅 cloudwatch/metric/putlocal publish/subscribe 主题。部署此组件时，可以指定其他主题，包括 AWS IoT Core MQTT 主题。

此组件对同一命名空间中的指标进行批处理，并定期将这些指标发布到 CloudWatch。

注意

此组件提供的功能与 AWS IoT Greengrass V1 中的 CloudWatch 指标连接器类似。有关更多信息，请参阅《AWS IoT Greengrass V1 开发人员指南》中的 CloudWatch metrics connector。

版本

此组件具有以下版本：

  • 3.1.x

  • 3.0.x

  • 2.1.x

  • 2.0.x

有关每个组件版本中的更改的信息，请参阅更改日志。

类型

v3.x

此组件是一个通用组件 (aws.greengrass.generic)。Greengrass Nucleus 运行组件的生命周期脚本。

v2.x

此组件是一个 Lambda 组件 (aws.greengrass.lambda)。Greengrass Nucleus 使用 Lambda 启动程序组件运行此组件的 Lambda 函数。

有关更多信息，请参阅 组件类型。

操作系统

v3.x

此组件可以安装在运行以下操作系统的核心设备上：

  • Linux

  • Windows

v2.x

此组件只能安装在 Linux 核心设备上。

要求

此组件具有以下要求：

3.x

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

  • Greengrass 设备角色必须允许执行 cloudwatch:PutMetricData 操作，如以下示例 IAM 策略中所示。

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

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

2.x

  • 您的核心设备必须满足运行 Lambda 函数的要求。如果您希望核心设备运行容器化 Lambda 函数，则设备必须满足相关要求。有关更多信息，请参阅 Lambda 函数要求。

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

  • Greengrass 设备角色必须允许执行 cloudwatch:PutMetricData 操作，如以下示例 IAM 策略中所示。

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

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

  • 要接收此组件的输出数据，在部署此组件时，必须合并旧版订阅路由器组件 (aws.greengrass.LegacySubscriptionRouter) 的以下配置更新。此配置指定此组件发布响应的主题。

    Legacy subscription router v2.1.xLegacy subscription router v2.0.x
    Legacy subscription router v2.1.x
    {
  "subscriptions": {
    "aws-greengrass-cloudwatch": {
      "id": "aws-greengrass-cloudwatch",
      "source": "component:aws.greengrass.Cloudwatch",
      "subject": "cloudwatch/metric/put/status",
      "target": "cloud"
    }
  }
}
    Legacy subscription router v2.0.x
    {
  "subscriptions": {
    "aws-greengrass-cloudwatch": {
      "id": "aws-greengrass-cloudwatch",
      "source": "arn:aws:lambda:region:aws:function:aws-greengrass-cloudwatch:version",
      "subject": "cloudwatch/metric/put/status",
      "target": "cloud"
    }
  }
}

    • 将 region 替换为您使用的 AWS 区域。

    • 将 version 替换为此组件运行的 Lambda 函数的版本。要查找 Lambda 函数版本，您必须查看要部署的此组件版本配方。在 AWS IoT Greengrass 控制台中打开此组件的详细信息页面，然后查找 Lambda 函数键值对。此键值对包含 Lambda 函数的名称和版本。

    重要

    每次部署此组件时，都必须更新旧版订阅路由器上的 Lambda 函数版本。这样能够确保为部署的组件版本使用正确的 Lambda 函数版本。

    有关更多信息，请参阅 创建部署。

端点和端口

除基本操作所需的端点和端口外，此组件还必须能够对以下端点和端口执行出站请求。有关更多信息，请参阅 允许设备流量通过代理或防火墙。

Endpoint 端口 必需 描述

monitoring.region.amazonaws.com

 443 是

上传 CloudWatch 指标。

依赖项

在您部署组件时，AWS IoT Greengrass 也会部署其依赖关系的兼容版本。这意味着您必须满足组件及其所有依赖关系的要求，才能成功部署组件。本部分列出了此组件的已发布版本的依赖关系，以及定义每个依赖关系的组件版本的语义版本约束。您还可以在 AWS IoT Greengrass 控制台中查看每个组件版本的依赖关系。在组件详细信息页面上，查找依赖关系列表。

3.0.0 - 3.1.0

下表列出了此组件的版本 3.0.0 至 3.1.0 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <3.0.0 软性
令牌交换服务 >=0.0.0 硬性
2.1.4 - 2.1.8

下表列出了此组件的版本 2.1.4 至 2.1.8 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <3.0.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.1.2 - 2.1.3

下表列出了此组件的版本 2.1.2 和 2.1.3 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.8.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.1.1

下表列出了此组件的版本 2.1.1 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.7.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.8 - 2.1.0

下表列出了此组件的版本 2.0.8 至 2.1.0 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.6.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.7

下表列出了此组件的版本 2.0.7 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.5.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.6

下表列出了此组件的版本 2.0.6 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.4.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.5

下表列出了此组件的版本 2.0.5 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.3.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.4

下表列出了此组件的版本 2.0.4 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.0 <2.2.0 硬性
Lambda 启动程序 ^2.0.0 硬性
Lambda 运行时 ^2.0.0 软性
令牌交换服务 ^2.0.0 硬性
2.0.3

下表列出了此组件的版本 2.0.3 的依赖关系。

依赖关系 兼容版本 依赖关系类型
Greengrass Nucleus >=2.0.3 <2.1.0 硬性
Lambda 启动程序 >=1.0.0 硬性
Lambda 运行时 >=1.0.0 软性
令牌交换服务 >=1.0.0 硬性

有关组件依赖关系的更多信息，请参阅组件配方参考。

配置

此组件提供您可以在部署组件时自定义的以下配置参数。

v3.x
PublishInterval

（可选）组件发布给定命名空间的批处理指标之前等待的最长秒数。要将组件配置为在收到指标时发布它们，即不进行批处理，请指定 0。

组件在同一命名空间中收到 20 个指标或在经过您指定的间隔之后发布到 CloudWatch。

注意

组件不指定事件的发布顺序。

此值最多可以是 900 秒。

默认值：10 秒

MaxMetricsToRetain

（可选）组件将指标替换为新指标之前，所有命名空间内可在内存中保存的指标的最大数量。

此限制适用于核心设备无法连接互联网的情况，以便组件缓冲指标供稍后发布。缓冲区已满时，组件会将最旧的指标替换为较新的指标。给定命名空间中的指标仅替换同一命名空间中的指标。

注意

如果组件的主机进程中断，则组件不会保存指标。例如，在部署或核心设备重新启动期间，可能会发生此情况。

此值必须至少为 2,000 个指标。

默认值：5,000 个指标

InputTopic

（可选）组件订阅以接收消息的主题。如果您为 PubSubToIoTCore 指定 true，则可以在本主题中使用 MQTT 通配符（+ 和 #）。

默认：cloudwatch/metric/put

OutputTopic

（可选）组件向其发布状态响应的主题。

默认：cloudwatch/metric/put/status

PubSubToIoTCore

（可选）字符串值，用于定义是否发布和订阅 AWS IoT Core MQTT 主题。支持的值为 true 和 false。

默认：false

UseInstaller

（可选）布尔值，用于定义是否使用此组件中的安装程序脚本来安装此组件的 SDK 依赖关系。

如果您想使用自定义脚本来安装依赖关系，或者想要在预构建的 Linux 映像中包含运行时依赖关系，请将此值设置为 false。要使用此组件，必须安装以下库（包括所有依赖关系），并使其可供默认 Greengrass 系统用户使用。

默认：true

PublishRegion

（可选）要向其发布 CloudWatch 指标的 AWS 区域。此值覆盖核心设备的默认区域。此参数仅是跨区域指标的必需参数。

accessControl

（可选）包含允许组件发布和订阅指定主题的授权策略的对象。如果您为 InputTopic 和 OutputTopic 指定了自定义值，则必须更新此对象中的资源值。

默认值：

{
  "aws.greengrass.ipc.pubsub": {
    "aws.greengrass.Cloudwatch:pubsub:1": {
      "policyDescription": "Allows access to subscribe to input topics.",
      "operations": [
        "aws.greengrass#SubscribeToTopic"
      ],
      "resources": [
        "cloudwatch/metric/put"
      ]
    },
    "aws.greengrass.Cloudwatch:pubsub:2": {
      "policyDescription": "Allows access to publish to output topics.",
      "operations": [
        "aws.greengrass#PublishToTopic"
      ],
      "resources": [
        "cloudwatch/metric/put/status"
      ]
    }
  },
  "aws.greengrass.ipc.mqttproxy": {
    "aws.greengrass.Cloudwatch:mqttproxy:1": {
      "policyDescription": "Allows access to subscribe to input topics.",
      "operations": [
        "aws.greengrass#SubscribeToIoTCore"
      ],
      "resources": [
        "cloudwatch/metric/put"
      ]
    },
    "aws.greengrass.Cloudwatch:mqttproxy:2": {
      "policyDescription": "Allows access to publish to output topics.",
      "operations": [
        "aws.greengrass#PublishToIoTCore"
      ],
      "resources": [
        "cloudwatch/metric/put/status"
      ]
    }
  }
}
例 示例：配置合并更新
{
  "PublishInterval": 0,
  "PubSubToIoTCore": true
}
v2.x
注意

此组件的默认配置包括 Lambda 函数参数。我们建议您只编辑以下参数，以便在您的设备上配置此组件。

lambdaParams

包含此组件的 Lambda 函数参数的对象。该对象包含以下信息：

EnvironmentVariables

包含 Lambda 函数的参数的对象。该对象包含以下信息：

PUBLISH_INTERVAL

（可选）组件发布给定命名空间的批处理指标之前等待的最长秒数。要将组件配置为在收到指标时发布它们，即不进行批处理，请指定 0。

组件在同一命名空间中收到 20 个指标或在经过您指定的间隔之后发布到 CloudWatch。

注意

组件不保证事件的发布顺序。

此值最多可以是 900 秒。

默认值：10 秒

MAX_METRICS_TO_RETAIN

（可选）组件将指标替换为新指标之前，所有命名空间内可在内存中保存的指标的最大数量。

此限制适用于核心设备无法连接互联网的情况，以便组件缓冲指标供稍后发布。缓冲区已满时，组件会将最旧的指标替换为较新的指标。给定命名空间中的指标仅替换同一命名空间中的指标。

注意

如果组件的主机进程中断，则组件不会保存指标。例如，在部署或核心设备重新启动期间，可能会发生此情况。

此值必须至少为 2,000 个指标。

默认值：5,000 个指标

PUBLISH_REGION

（可选）要向其发布 CloudWatch 指标的 AWS 区域。此值覆盖核心设备的默认区域。此参数仅是跨区域指标的必需参数。

containerMode

（可选）此组件的容器化模式。从以下选项中进行选择：

  • NoContainer – 该组件不在隔离的运行时环境中运行。

  • GreengrassContainer – 该组件在 AWS IoT Greengrass 容器内的隔离运行时环境中运行。

默认：GreengrassContainer

containerParams

（可选）包含此组件的容器参数的对象。如果您为 containerMode 指定 GreengrassContainer，则该组件使用这些参数。

该对象包含以下信息：

memorySize

（可选）要分配给组件的内存量（以千字节为单位）。

默认为 64 MB（65,535 KB）。

pubsubTopics

（可选）包含组件订阅以接收消息的主题的对象。您可以指定每个主题，以及该组件是订阅来自 AWS IoT Core 的 MQTT 主题还是本地发布/订阅主题。

该对象包含以下信息：

0 – 这是字符串形式的数组索引。

包含以下信息的对象：

type

（可选）此组件用来订阅消息的发布/订阅消息收发的类型。从以下选项中进行选择：

  • PUB_SUB – 订阅本地发布/订阅消息。如果选择此选项，主题不能包含 MQTT 通配符。有关在指定此选项时如何从自定义组件发送消息的更多信息，请参阅 发布/订阅本地消息。

  • IOT_CORE – 订阅 AWS IoT Core MQTT 消息。如果选择此选项，主题可以包含 MQTT 通配符。有关在指定此选项时如何从自定义组件发送消息的更多信息，请参阅 发布/订阅 AWS IoT Core MQTT 消息。

默认：PUB_SUB

topic

（可选）组件订阅以接收消息的主题。如果您为 type 指定 IotCore，则可以在本主题中使用 MQTT 通配符（+ 和 #）。

例 示例：配置合并更新（容器模式）
{
  "containerMode": "GreengrassContainer"
}
例 示例：配置合并更新（无容器模式）
{
  "containerMode": "NoContainer"
}

输入数据

此组件接受有关以下主题的指标，并将这些指标发布到 CloudWatch。默认情况下，此组件订阅本地发布/订阅消息。有关如何从您的自定义组件向此组件发布消息的更多信息，请参阅 发布/订阅本地消息。

从组件版本 v3.0.0 开始，您可以选择通过将 PubSubToIoTCore 配置参数设置为 true 来将此组件配置为订阅 MQTT 主题。有关在自定义组件中向 MQTT 主题发布消息的更多信息，请参阅 发布/订阅 AWS IoT Core MQTT 消息。

默认主题：cloudwatch/metric/put

消息接受以下属性。输入消息必须采用 JSON 格式。

request

此消息中的指标。

请求对象包含要发布到 CloudWatch 的指标数据。指标值必须符合 PutMetricData 操作的规范。

类型：包含以下信息的 object：

namespace

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

注意

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

类型：string

有效模式：[^:].*

metricData

指标的数据。

类型：包含以下信息的 object：

metricName

指标的名称。

类型：string

value

指标的值。

注意

CloudWatch 拒绝过小或过大的值。该值必须介于 8.515920e-109 和 1.174271e+108（基数 10）或 2e-360 和 2e360（基数 2）之间。CloudWatch 不支持特殊值，例如 NaN、+Infinity 和 -Infinity。

类型：double

dimensions

（可选）指标的维度。维度提供有关指标及其数据的附加信息。指标最多可定义 10 个维度。

此组件自动包含一个名为 coreName 的维度，其中的值是核心设备的名称。

类型：对象的 array，每个对象都包含以下信息：

name

（可选）维度名称。

类型：string

value

（可选）维度值。

类型：string

timestamp

（可选）接收指标数据的时间，以 Unix 纪元时间（以秒为单位）表示。

默认为组件收到消息的时间。

类型：double

注意

如果您使用此组件的版本 2.0.3 到版本 2.0.7，我们建议您在从单一来源发送多个指标时分别检索每个指标的时间戳。不要使用变量来存储时间戳。

unit

（可选）指标的单位。

类型：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

默认值为 None。

注意

适用于 CloudWatch PutMetricData API 的所有配额都适用于您通过此组件发布的指标。以下配额尤其重要：

  • API 有效载荷的 40 KB 限制

  • 每个 API 请求的 20 个指标

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

有关更多信息，请参阅《CloudWatch 用户指南》https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_limits.html中的 CloudWatch 服务配额。

例 示例输入
{
  "request": {
    "namespace": "Greengrass",
    "metricData": {
      "metricName": "latency",
      "dimensions": [
        {
          "name": "hostname",
          "value": "test_hostname"
        }
      ],
      "timestamp": 1539027324,
      "value": 123.0,
      "unit": "Seconds"
    }
  }
}

输出数据

默认情况下，此组件会将响应作为输出数据发布到以下本地发布/订阅主题中。有关如何在自定义组件中订阅此主题消息的更多信息，请参阅 发布/订阅本地消息。

您可以选择通过将 PubSubToIoTCore 配置参数设置为 true 来将此组件配置为发布到 MQTT 主题。有关在自定义组件中订阅 MQTT 主题消息的更多信息，请参阅 发布/订阅 AWS IoT Core MQTT 消息。

注意

默认情况下，组件版本 2.0.x 会将响应作为输出数据发布到 MQTT 主题。您必须在旧版订阅路由器组件的配置中将主题指定为 subject。

默认主题：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"
  }
}
注意

如果组件检测到可以重试的错误（例如连接错误），它会在下一次批处理中重试发布。

许可证

此组件包含以下第三方软件/许可：

此组件在 Greengrass Core 软件许可协议下发行。

本地日志文件

此组件使用以下日志文件。

Linux
/greengrass/v2/logs/aws.greengrass.Cloudwatch.log
Windows
C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log
查看此组件的日志

  • 在核心设备上运行以下命令以实时查看此组件的日志文件。将 /greengrass/v2 或 C:\greengrass\v2 替换为 AWS IoT Greengrass 根文件夹的路径。

    Linux
    sudo tail -f /greengrass/v2/logs/aws.greengrass.Cloudwatch.log
    Windows (PowerShell)
    Get-Content C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log -Tail 10 -Wait

更改日志

下表介绍每个组件版本的更改。

v3.x

版本

更改

3.1.0
错误修复和改进

3.0.0

此版本的 CloudWatch 指标组件需要的配置参数与版本 2.x 不同。如果您为版本 2.x 使用非默认配置，并且想要从 v2.x 升级到 v3.x，则必须更新该组件的配置。有关更多信息，请参阅 CloudWatch 指标组件配置。

新功能

  • 添加了对运行 Windows 的核心设备的支持。

  • 将组件类型从 Lambda 组件更改为通用组件。此组件现在不再依赖旧版订阅路由器组件来创建订阅。

  • 添加了新的 InputTopic 配置参数，以指定组件订阅的主题以接收消息。

  • 添加了新的 OutputTopic 配置参数，以指定组件向其发布状态响应的主题。

  • 添加了新的 PubSubToIoTCore 配置参数，以指定是否发布和订阅 AWS IoT Core MQTT 主题。

  • 添加了新的 UseInstaller 配置参数，使您可以选择禁用安装组件依赖关系的安装脚本。

错误修复和改进

添加了输入数据中对重复时间戳的支持。
v2.x

版本

更改

2.1.8

对 Greengrass Nucleus 版本 2.13.0 发行版进行了版本更新。

2.1.3

版本更新为 Greengrass Nucleus 版本 2.11.0 发布版。

2.1.2

版本更新为 Greengrass Nucleus 版本 2.7.0 发布版。

2.1.1

版本更新为 Greengrass Nucleus 版本 2.6.0 发布版。

2.1.0
新功能

2.0.8
错误修复和改进

  • 添加了输入数据中对重复时间戳的支持。

  • 版本更新为 Greengrass Nucleus 版本 2.5.0 发布版。

2.0.7

版本更新为 Greengrass Nucleus 版本 2.4.0 发布版。

2.0.6

版本更新为 Greengrass Nucleus 版本 2.3.0 发布版。

2.0.5

对 Greengrass Nucleus 版本 2.2.0 发行版进行了版本更新。

2.0.4

对 Greengrass Nucleus 版本 2.1.0 发行版进行了版本更新。

2.0.3

初始版本。

另请参阅