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 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.
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.
Versions
This component has the following versions:
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:
- 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:lambda:region
:aws:function:aws-greengrass-cloudwatch:version
",
"subject": "cloudwatch/metric/put/status",
"target": "cloud"
}
}
}
-
Replace region
with the AWS 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
AWS 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.
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, 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. 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.
- 2.1.4 - 2.1.8
-
The following table lists the dependencies for version 2.1.4 and 2.1.8 of this
component.
- 2.1.2 - 2.1.3
-
The following table lists the dependencies for version 2.1.2 and 2.1.3 of this
component.
- 2.1.1
-
The following table lists the dependencies for version 2.1.1 of this
component.
- 2.0.8 - 2.1.0
-
The following table lists the dependencies for versions 2.0.8 to 2.1.0 of this
component.
- 2.0.7
-
The following table lists the dependencies for version 2.0.7 of this
component.
- 2.0.6
-
The following table lists the dependencies for version 2.0.6 of this
component.
- 2.0.5
-
The following table lists the dependencies for version 2.0.5 of this
component.
- 2.0.4
-
The following table lists the dependencies for version 2.0.4 of this
component.
- 2.0.3
-
The following table lists the dependencies for version 2.0.3 of this
component.
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.
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.
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
AWS 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 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
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
-
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.
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.
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 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.
containerMode
-
(Optional) The containerization mode for this component. Choose from the following
options:
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 AWS 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 AWS 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 AWS 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"
}
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.
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.
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
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
.
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.
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"
}
}
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
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 AWS 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.8
|
Version updated for Greengrass nucleus version 2.13.0 release.
|
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
|
|
2.0.8
|
- Bug fixes and improvements
-
|
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