CloudWatch metrics - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

CloudWatch metrics

The Amazon CloudWatch metrics component (aws.greengrass.Cloudwatch) publishes custom metrics from Greengrass core devices to Amazon CloudWatch. The component enables components to publish CloudWatch metrics, which you can use to monitor and analyze the Greengrass core device's environment. For more information, see Using Amazon CloudWatch metrics in the Amazon CloudWatch User Guide.

To publish a CloudWatch metric with this component, publish a message to a topic where this component subscribes. By default, this component subscribes to the cloudwatch/metric/put local publish/subscribe topic. You can specify other topics, including Amazon IoT Core MQTT topics, when you deploy this component.

This component batches metrics that are in the same namespace and publishes them to CloudWatch at regular intervals.

Note

This component provides similar functionality to the CloudWatch metrics connector in Amazon IoT Greengrass V1. For more information, see CloudWatch metrics connector in the Amazon IoT Greengrass V1 Developer Guide.

Versions

This component has the following versions:

  • 3.1.x

  • 3.0.x

  • 2.1.x

  • 2.0.x

For information about changes in each version of the component, see the changelog.

Type

v3.x

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

v2.x

This component is a Lambda component (aws.greengrass.lambda). The Greengrass nucleus runs this component's Lambda function using the Lambda launcher component.

For more information, see Component types.

Operating system

v3.x

This component can be installed on core devices that run the following operating systems:

  • Linux

  • Windows

v2.x

This component can be installed on Linux core devices only.

Requirements

This component has the following requirements:

3.x
  • Python version 3.7 installed on the core device and added to the PATH environment variable.

  • The Greengrass device role must allow the cloudwatch:PutMetricData action, as shown in the following example IAM policy.

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

    For more information, see Amazon CloudWatch permissions reference in the Amazon CloudWatch User Guide.

2.x
  • Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see Lambda function requirements.

  • Python version 3.7 installed on the core device and added to the PATH environment variable.

  • The Greengrass device role must allow the cloudwatch:PutMetricData action, as shown in the following example IAM policy.

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

    For more information, see Amazon CloudWatch permissions reference in the Amazon CloudWatch User Guide.

  • To receive output data from this component, you must merge the following configuration update for the legacy subscription router component (aws.greengrass.LegacySubscriptionRouter) when you deploy this component. This configuration specifies the topic where this component publishes responses.

    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-cn:lambda:region:aws:function:aws-greengrass-cloudwatch:version", "subject": "cloudwatch/metric/put/status", "target": "cloud" } } }
    • Replace region with the Amazon Web Services Region that you use.

    • Replace version with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the Amazon IoT Greengrass console, and look for the Lambda function key-value pair. This key-value pair contains the name and version of the Lambda function.

    Important

    You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

    For more information, see Create deployments.

Endpoints and ports

This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see Allow device traffic through a proxy or firewall.

Endpoint Port Required Description

monitoring.region.amazonaws.com

443 Yes

Upload CloudWatch metrics.

Dependencies

When you deploy a component, Amazon IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the Amazon IoT Greengrass console. On the component details page, look for the Dependencies list.

3.0.0 - 3.1.0

The following table lists the dependencies for versions 3.0.0 to 3.1.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <3.0.0 Soft
Token exchange service >=0.0.0 Hard
2.1.2 and 2.1.3

The following table lists the dependencies for version 2.1.2 and 2.1.3 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.8.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.1.1

The following table lists the dependencies for version 2.1.1 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.7.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.8 - 2.1.0

The following table lists the dependencies for versions 2.0.8 to 2.1.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.6.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.7

The following table lists the dependencies for version 2.0.7 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.5.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.6

The following table lists the dependencies for version 2.0.6 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.4.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.5

The following table lists the dependencies for version 2.0.5 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.3.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.4

The following table lists the dependencies for version 2.0.4 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.2.0 Hard
Lambda launcher ^2.0.0 Hard
Lambda runtimes ^2.0.0 Soft
Token exchange service ^2.0.0 Hard
2.0.3

The following table lists the dependencies for version 2.0.3 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.3 <2.1.0 Hard
Lambda launcher >=1.0.0 Hard
Lambda runtimes >=1.0.0 Soft
Token exchange service >=1.0.0 Hard

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

v3.x
PublishInterval

(Optional) The maximum number of seconds to wait before the component publishes batched metrics for a given namespace. To configure the component to publish metrics as it receives them, which means without batching, specify 0.

The component publishes to CloudWatch after it receives 20 metrics in the same namespace or after the interval that you specify.

Note

The component doesn't specify the order in which events publish.

This value can be a maximum of 900 seconds.

Default: 10 seconds

MaxMetricsToRetain

(Optional) The maximum number of metrics across all namespaces to save in memory before the component replaces them with newer metrics.

This limit applies when the core device doesn't have a connection to the internet, so the component buffers the metrics to publish later. When the buffer is full, the component replaces the oldest metrics with newer ones. Metrics in a given namespace replace only metrics in the same namespace.

Note

If the host process for the component is interrupted, the component doesn't save metrics. This can happen during a deployment or when the core device restarts, for example.

This value must be at least 2,000 metrics.

Default: 5,000 metrics

InputTopic

(Optional) The topic to which the component subscribes to receive messages. If you specify true for PubSubToIoTCore, you can use MQTT wildcards (+ and #) in this topic.

Default: cloudwatch/metric/put

OutputTopic

(Optional) The topic to which the component publishes status responses.

Default: cloudwatch/metric/put/status

PubSubToIoTCore

(Optional) String value that defines whether to publish and subscribe to Amazon IoT Core MQTT topics. Supported values are true and false.

Default: false

UseInstaller

(Optional) Boolean value that defines whether to use the installer script in this component to install this component's SDK dependencies.

Set this value to false if you want to use a custom script to install dependencies, or if you want to include runtime dependencies in a pre-built Linux image. To use this component, you must install the following libraries, including any dependencies, and make them available to the default Greengrass system user.

Default: true

PublishRegion

(Optional) The Amazon Web Services Region to which to publish CloudWatch metrics. This value overrides the default Region for the core device. This parameter is required only for cross-Region metrics.

accessControl

(Optional) The object that contains the authorization policy that allows the component to publish and subscribe to the specified topics. If you specify custom values for InputTopic and OutputTopic, you must update the resource values in this object.

Default:

{ "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" ] } } }
Example: Configuration merge update
{ "PublishInterval": 0, "PubSubToIoTCore": true }
v2.x
Note

This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

lambdaParams

An object that contains the parameters for this component's Lambda function. This object contains the following information:

EnvironmentVariables

An object that contains the Lambda function's parameters. This object contains the following information:

PUBLISH_INTERVAL

(Optional) The maximum number of seconds to wait before the component publishes batched metrics for a given namespace. To configure the component to publish metrics as it receives them, which means without batching, specify 0.

The component publishes to CloudWatch after it receives 20 metrics in the same namespace or after the interval that you specify.

Note

The component doesn't guarantee the order in which events publish.

This value can be at most 900 seconds.

Default: 10 seconds

MAX_METRICS_TO_RETAIN

(Optional) The maximum number of metrics across all namespaces to save in memory before the component replaces them with newer metrics.

This limit applies when the core device doesn't have a connection to the internet, so the component buffers the metrics to publish later. When the buffer is full, the component replaces the oldest metrics with newer ones. Metrics in a given namespace replace only metrics in the same namespace.

Note

If the host process for the component is interrupted, the component doesn't save metrics. This can happen during a deployment or when the core device restarts, for example.

This value must be at least 2,000 metrics.

Default: 5,000 metrics

PUBLISH_REGION

(Optional) The Amazon Web Services Region to which to publish CloudWatch metrics. This value overrides the default Region for the core device. This parameter is required only for cross-Region metrics.

containerMode

(Optional) The containerization mode for this component. Choose from the following options:

  • NoContainer – The component doesn't run in an isolated runtime environment.

  • GreengrassContainer – The component runs in an isolated runtime environment inside the Amazon IoT Greengrass container.

Default: GreengrassContainer

containerParams

(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify GreengrassContainer for containerMode.

This object contains the following information:

memorySize

(Optional) The amount of memory (in kilobytes) to allocate to the component.

Defaults to 64 MB (65,535 KB).

pubsubTopics

(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from Amazon IoT Core or local publish/subscribe topics.

This object contains the following information:

0 – This is an array index as a string.

An object that contains the following information:

type

(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:

  • PUB_SUB – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see Publish/subscribe local messages.

  • IOT_CORE – Subscribe to Amazon IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see Publish/subscribe Amazon IoT Core MQTT messages.

Default: PUB_SUB

topic

(Optional) The topic to which the component subscribes to receive messages. If you specify IotCore for type, you can use MQTT wildcards (+ and #) in this topic.

Example: Configuration merge update (container mode)
{ "containerMode": "GreengrassContainer" }
Example: Configuration merge update (no container mode)
{ "containerMode": "NoContainer" }

Input data

This component accepts metrics on the following topic and publishes the metrics to CloudWatch. By default, this component subscribes to local publish/subscribe messages. For more information about how to publish messages to this component from your custom components, see Publish/subscribe local messages.

Beginning with component version v3.0.0, you can optionally configure this component to subscribe to an MQTT topic by setting the PubSubToIoTCore configuration parameter to true. For more information about publishing messages to an MQTT topic in your custom components, see Publish/subscribe Amazon IoT Core MQTT messages.

Default topic: cloudwatch/metric/put

The message accepts the following properties. Input messages must be in JSON format.

request

The metric in this message.

The request object contains the metric data to publish to CloudWatch. The metric values must meet the specifications of the PutMetricData operation.

Type: object that contains the following information:

namespace

The user-defined namespace for the metric data in this request. CloudWatch uses namespaces as containers for metric data points.

Note

You can't specify a namespace that begins with the reserved string AWS/.

Type: string

Valid pattern: [^:].*

metricData

The data for the metric.

Type: object that contains the following information:

metricName

The name of the metric.

Type: string

value

The value for the metric.

Note

CloudWatch rejects values that are too small or too large. The value must be between 8.515920e-109 and 1.174271e+108 (Base 10) or 2e-360 and 2e360 (Base 2). CloudWatch doesn't support special values such as NaN, +Infinity, and -Infinity.

Type: double

dimensions

(Optional) The dimensions for the metric. Dimensions provide additional information about the metric and its data. A metric can define up to 10 dimensions.

This component automatically includes a dimension named coreName, where the value is the name of the core device.

Type: array of objects that each contain the following information:

name

(Optional) The dimension name.

Type: string

value

(Optional) The dimension value.

Type: string

timestamp

(Optional) The time at which the metric data was received, expressed in seconds in Unix epoch time.

Defaults to the time at which the component receives the message.

Type: double

Note

If you use between versions 2.0.3 and 2.0.7 of this component, we recommend that you retrieve the timestamp separately for each metric when you send multiple metrics from a single source. Don't use a variable to store the timestamp.

unit

(Optional) The unit of the metric.

Type: string

Valid values: 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

Defaults to None.

Note

All quotas that apply to the CloudWatch PutMetricData API apply to metrics that you publish with this component. The following quotas are especially important:

  • 40 KB limit on the API payload

  • 20 metrics per API request

  • 150 transactions per second (TPS) for the PutMetricData API

For more information, see CloudWatch service quotas in the CloudWatch User Guide.

Example input
{ "request": { "namespace": "Greengrass", "metricData": { "metricName": "latency", "dimensions": [ { "name": "hostname", "value": "test_hostname" } ], "timestamp": 1539027324, "value": 123.0, "unit": "Seconds" } } }

Output data

This component publishes responses as output data on the following local publish/subscribe topic by default. For more information about how to subscribe to messages on this topic in your custom components, see Publish/subscribe local messages.

You can optionally configure this component to publish to an MQTT topic by setting the PubSubToIoTCore configuration parameter to true. For more information about subscribing to messages on an MQTT topic in your custom components, see Publish/subscribe Amazon IoT Core MQTT messages.

Note

Component versions 2.0.x publish responses as output data on an MQTT topic by default. You must specify the topic as the subject in the configuration for the legacy subscription router component.

Default topic: cloudwatch/metric/put/status

Example output: Success

The response includes the namespace of the metric data and the RequestId field from the CloudWatch response.

{ "response": { "cloudwatch_rid": "70573243-d723-11e8-b095-75ff2EXAMPLE", "namespace": "Greengrass", "status": "success" } }
Example output: Failure
{ "response" : { "namespace": "Greengrass", "error": "InvalidInputException", "error_message": "cw metric is invalid", "status": "fail" } }
Note

If the component detects an error that can be retried, such as a connection error, it retries the publish in the next batch.

Licenses

This component includes the following third-party software/licensing:

This component is released under the Greengrass Core Software License Agreement.

Local log file

This component uses the following log file.

Linux
/greengrass/v2/logs/aws.greengrass.Cloudwatch.log
Windows
C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log
To view this component's logs
  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the Amazon IoT Greengrass root folder.

    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

Changelog

The following table describes the changes in each version of the component.

v3.x

Version

Changes

3.1.0

Bug fixes and improvements

3.0.0

This version of the CloudWatch metrics component expects different configuration parameters than version 2.x. If you use a non-default configuration for version 2.x, and you want to upgrade from v2.x to v3.x, you must update the component's configuration. For more information, see CloudWatch metrics component configuration.

New features
  • Adds support for core devices that run Windows.

  • Changes the component type from Lambda component to generic component. This component now no longer depends on the legacy subscription router component to create subscriptions.

  • Adds new InputTopic configuration parameter to specify the topic to which the component subscribes to receive messages.

  • Adds new OutputTopic configuration parameter to specify the topic to which the component publishes status responses.

  • Adds new PubSubToIoTCore configuration parameter to specify whether to publish and subscribe to Amazon IoT Core MQTT topics.

  • Adds the new UseInstaller configuration parameter that lets you optionally disable the installation script that installs component dependencies.

Bug fixes and improvements

Adds support for duplicate timestamps in input data.

v2.x

Version

Changes

2.1.3

Version updated for Greengrass nucleus version 2.11.0 release.

2.1.2

Version updated for Greengrass nucleus version 2.7.0 release.

2.1.1

Version updated for Greengrass nucleus version 2.6.0 release.

2.1.0

New features

2.0.8

Bug fixes and improvements
  • Adds support for duplicate timestamps in input data.

  • Version updated for Greengrass nucleus version 2.5.0 release.

2.0.7

Version updated for Greengrass nucleus version 2.4.0 release.

2.0.6

Version updated for Greengrass nucleus version 2.3.0 release.

2.0.5

Version updated for Greengrass nucleus version 2.2.0 release.

2.0.4

Version updated for Greengrass nucleus version 2.1.0 release.

2.0.3

Initial version.

See also