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 AWS 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 AWS IoT Greengrass V1. For more information, see CloudWatch metrics connector in the AWS IoT Greengrass V1 Developer Guide.
Topics
Versions
This component has the following versions:
-
3.2.x
-
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
This component is a generic component (aws.greengrass.generic
). The Greengrass nucleus runs the component's lifecycle
scripts.
For more information, see Component types.
Operating system
This component can be installed on core devices that run the following operating systems:
Linux
Windows
Requirements
This component has the following 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.
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 |
---|---|---|---|
|
443 | Yes |
Upload CloudWatch metrics. |
Dependencies
When you deploy a component, AWS 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 AWS IoT Greengrass console
The following table lists the dependencies for versions 3.2.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 |
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.
-
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
forPubSubToIoTCore
, 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 AWS IoT Core MQTT topics. Supported values are
true
andfalse
.Default:
false
LogLevel
-
(Optional) The logging level for the component. Choose from the following log levels, listed here in level order:
-
DEBUG
-
INFO
-
WARNING
-
ERROR
-
CRITICAL
Default:
INFO
-
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 AWS 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
andOutputTopic
, 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
}
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 AWS 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
and1.174271e+108
(Base 10) or2e-360
and2e360
(Base 2). CloudWatch doesn't support special values such asNaN
,+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 AWS 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:
-
AWS SDK for Python (Boto3)
/Apache License 2.0 -
botocore
/Apache License 2.0 -
dateutil
/PSF License -
docutils
/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public Domain -
jmespath
/MIT License -
s3transfer
/Apache License 2.0 -
urllib3
/MIT License
This component is released under the Greengrass Core Software License Agreement
Local log file
This component uses the following log file.
/logs/aws.greengrass.Cloudwatch.log
/greengrass/v2
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
or/greengrass/v2
C:\greengrass\v2
with the path to the AWS IoT Greengrass root folder.sudo tail -f
/logs/aws.greengrass.Cloudwatch.log/greengrass/v2
Changelog
The following table describes the changes in each version of the component.
Version |
Changes |
---|---|
3.2.0 |
|
3.1.0 |
|
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.
|
See also
-
Using Amazon CloudWatch metrics in the Amazon CloudWatch User Guide
-
PutMetricData in the Amazon CloudWatch API Reference