Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(iot): add Action to capture CloudWatch metrics #17503

Merged
merged 5 commits into from
Nov 24, 2021
Merged

feat(iot): add Action to capture CloudWatch metrics #17503

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c67d50f
feat(iot): add Action to capture CloudWatch metrics
yamatatsu Nov 15, 2021
b22ebec
Merge branch 'master' into aws-iot-actions-cloudwatch-metric
yamatatsu Nov 15, 2021
98b8769
Merge branch 'master' into aws-iot-actions-cloudwatch-metric
yamatatsu Nov 16, 2021
6ace2c8
address comments
yamatatsu Nov 16, 2021
12773ba
Merge branch 'master' into aws-iot-actions-cloudwatch-metric
mergify[bot] Nov 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions packages/@aws-cdk/aws-iot-actions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Currently supported are:
- Invoke a Lambda function
- Put objects to a S3 bucket
- Put logs to CloudWatch Logs
- Capture CloudWatch metrics
- Put records to Kinesis Data Firehose stream

## Invoke a Lambda function
Expand Down Expand Up @@ -123,6 +124,30 @@ new iot.TopicRule(this, 'TopicRule', {
});
```

## Capture CloudWatch metrics

The code snippet below creates an AWS IoT Rule that capture CloudWatch metrics
when it is triggered.

```ts
import * as iot from '@aws-cdk/aws-iot';
import * as actions from '@aws-cdk/aws-iot-actions';

const topicRule = new iot.TopicRule(this, 'TopicRule', {
sql: iot.IotSql.fromStringAsVer20160323(
"SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'",
),
actions: [
new actions.CloudWatchMetricAction({
metricName: '${topic(2)}',
metricNamespace: '${namespace}',
metricUnit: '${unit}',
metricValue: '${value}',
metricTimestamp: '${timestamp}',
})
],
});
```

## Put records to Kinesis Data Firehose stream

Expand Down
80 changes: 80 additions & 0 deletions packages/@aws-cdk/aws-iot-actions/lib/cloudwatch-metric-action.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import * as iam from '@aws-cdk/aws-iam';
import * as iot from '@aws-cdk/aws-iot';
import { CommonActionProps } from './common-action-props';
import { singletonActionRole } from './private/role';

/**
* Configuration properties of an action for CloudWatch metric.
*/
export interface CloudWatchMetricActionProps extends CommonActionProps {
/**
* The CloudWatch metric name.
*
* Supports substitution templates.
* @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
*/
readonly metricName: string,

/**
* The CloudWatch metric namespace name.
*
* Supports substitution templates.
* @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
*/
readonly metricNamespace: string,

/**
* A string that contains the timestamp, expressed in seconds in Unix epoch time.
*
* Supports substitution templates.
* @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
*
* @default - none -- Defaults to the current Unix epoch time.
*/
readonly metricTimestamp?: string,

/**
* The metric unit supported by CloudWatch.
*
* Supports substitution templates.
* @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
*/
readonly metricUnit: string,

/**
* A string that contains the CloudWatch metric value.
*
* Supports substitution templates.
* @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
*/
readonly metricValue: string,
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't we use the Metric class from the CloudWatch module instead of all these separate props here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@skinny85
I thought it too. But if using Metric class, we will not be able to use substitution templates.
So I think it is better that we provide fromMetric() method.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting... what's the problem that prevents using Metric with substitution templates?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@skinny85
I had envisioned using Metric class as following.

const metric = new cloudwatch.Metric({
  namespace: 'test-namespace',
  metricName: 'test-name',
  unit: cloudwatch.Unit.COUNT,
});
new CloudWatchPutMetricAction(metric, {
  metricValue: '${temperature}',
  metricTimestamp: '${timestamp}',
});

In above case, I predicted that users might think "I cannot use substitution templates in namespace, metricName and unit".

Hmmm🤔. As I was writing this, I realized that there was nothing preventing from using substitution templates in properties besides unit as following.

const metric = new cloudwatch.Metric({
  namespace: '${namespace}',
  metricName: '${topic(2)}',
});

I'm a little uncomfortable with it, in that substitution templates are written in Metric class props. How about?

And unit cannot be used with substitution templates because unit is enum in Metric.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How common it is to use a dynamic Unit, do you think?

We can work around it by having something like:

new CloudWatchPutMetricAction(metric, {
  dynamicUnit: `${sth}`,
});

It is a little bit awkward, I agree.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a pretty rare case that a unit is used dynamically.

For just one thing, How about this?
We keep current props, and we provide metric() method like metric-filter.ts.
Because, in many case, CloudWatchPutMetricAction will generate new custom metric for example temperature, weight and moisture. And alerms will be created with this metrics.
So I think users maybe will want metric after they make the topic rules.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, sounds good.


/**
* The action to capture an Amazon CloudWatch metric.
*/
export class CloudWatchMetricAction implements iot.IAction {
constructor(private readonly props: CloudWatchMetricActionProps) {
}

bind(rule: iot.ITopicRule): iot.ActionConfig {
const role = this.props.role ?? singletonActionRole(rule);
role.addToPrincipalPolicy(new iam.PolicyStatement({
actions: ['cloudwatch:PutMetricData'],
resources: ['*'],
}));
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use the Metric.grantPutMetricData() method instead.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cool!


return {
configuration: {
cloudwatchMetric: {
metricName: this.props.metricName,
metricNamespace: this.props.metricNamespace,
metricTimestamp: this.props.metricTimestamp,
metricUnit: this.props.metricUnit,
metricValue: this.props.metricValue,
roleArn: role.roleArn,
},
},
};
}
}
1 change: 1 addition & 0 deletions packages/@aws-cdk/aws-iot-actions/lib/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
export * from './cloudwatch-logs-action';
export * from './cloudwatch-metric-action';
export * from './common-action-props';
export * from './firehose-stream-action';
export * from './lambda-function-action';
Expand Down
134 changes: 134 additions & 0 deletions packages/@aws-cdk/aws-iot-actions/test/cloudwatch-metric/cloudwatch-metric-action.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
import { Template, Match } from '@aws-cdk/assertions';
import * as iam from '@aws-cdk/aws-iam';
import * as iot from '@aws-cdk/aws-iot';
import * as cdk from '@aws-cdk/core';
import * as actions from '../../lib';

test('Default cloudwatch metric action', () => {
// GIVEN
const stack = new cdk.Stack();
const topicRule = new iot.TopicRule(stack, 'MyTopicRule', {
sql: iot.IotSql.fromStringAsVer20160323("SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'"),
});

// WHEN
topicRule.addAction(
new actions.CloudWatchMetricAction({
metricName: '${topic(2)}',
metricNamespace: '${namespace}',
metricUnit: '${unit}',
metricValue: '${value}',
}),
);

// THEN
Template.fromStack(stack).hasResourceProperties('AWS::IoT::TopicRule', {
TopicRulePayload: {
Actions: [
{
CloudwatchMetric: {
MetricName: '${topic(2)}',
MetricNamespace: '${namespace}',
MetricUnit: '${unit}',
MetricValue: '${value}',
RoleArn: {
'Fn::GetAtt': ['MyTopicRuleTopicRuleActionRoleCE2D05DA', 'Arn'],
},
},
},
],
},
});

Template.fromStack(stack).hasResourceProperties('AWS::IAM::Role', {
AssumeRolePolicyDocument: {
Statement: [
{
Action: 'sts:AssumeRole',
Effect: 'Allow',
Principal: {
Service: 'iot.amazonaws.com',
},
},
],
Version: '2012-10-17',
},
});

Template.fromStack(stack).hasResourceProperties('AWS::IAM::Policy', {
PolicyDocument: {
Statement: [
{
Action: 'cloudwatch:PutMetricData',
Effect: 'Allow',
Resource: '*',
},
],
Version: '2012-10-17',
},
PolicyName: 'MyTopicRuleTopicRuleActionRoleDefaultPolicy54A701F7',
Roles: [{ Ref: 'MyTopicRuleTopicRuleActionRoleCE2D05DA' }],
});
});

test('can set timestamp', () => {
// GIVEN
const stack = new cdk.Stack();
const topicRule = new iot.TopicRule(stack, 'MyTopicRule', {
sql: iot.IotSql.fromStringAsVer20160323("SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'"),
});

// WHEN
topicRule.addAction(
new actions.CloudWatchMetricAction({
metricName: '${topic(2)}',
metricNamespace: '${namespace}',
metricUnit: '${unit}',
metricValue: '${value}',
metricTimestamp: '${timestamp()}',
}),
);

// THEN
Template.fromStack(stack).hasResourceProperties('AWS::IoT::TopicRule', {
TopicRulePayload: {
Actions: [
Match.objectLike({ CloudwatchMetric: { MetricTimestamp: '${timestamp()}' } }),
],
},
});
});

test('can set role', () => {
// GIVEN
const stack = new cdk.Stack();
const topicRule = new iot.TopicRule(stack, 'MyTopicRule', {
sql: iot.IotSql.fromStringAsVer20160323("SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'"),
});
const role = iam.Role.fromRoleArn(stack, 'MyRole', 'arn:aws:iam::123456789012:role/ForTest');

// WHEN
topicRule.addAction(
new actions.CloudWatchMetricAction({
metricName: '${topic(2)}',
metricNamespace: '${namespace}',
metricUnit: '${unit}',
metricValue: '${value}',
role,
}),
);

// THEN
Template.fromStack(stack).hasResourceProperties('AWS::IoT::TopicRule', {
TopicRulePayload: {
Actions: [
Match.objectLike({ CloudwatchMetric: { RoleArn: 'arn:aws:iam::123456789012:role/ForTest' } }),
],
},
});

Template.fromStack(stack).hasResourceProperties('AWS::IAM::Policy', {
PolicyName: 'MyRolePolicy64AB00A5',
Roles: ['ForTest'],
});
});
68 changes: 68 additions & 0 deletions ...s-cdk/aws-iot-actions/test/cloudwatch-metric/integ.cloudwatch-metric-action.expected.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
{
"Resources": {
"TopicRule40A4EA44": {
"Type": "AWS::IoT::TopicRule",
"Properties": {
"TopicRulePayload": {
"Actions": [
{
"CloudwatchMetric": {
"MetricName": "${topic(2)}",
"MetricNamespace": "${namespace}",
"MetricTimestamp": "${timestamp}",
"MetricUnit": "${unit}",
"MetricValue": "${value}",
"RoleArn": {
"Fn::GetAtt": [
"TopicRuleTopicRuleActionRole246C4F77",
"Arn"
]
}
}
}
],
"AwsIotSqlVersion": "2016-03-23",
"Sql": "SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'"
}
}
},
"TopicRuleTopicRuleActionRole246C4F77": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
}
}
],
"Version": "2012-10-17"
}
}
},
"TopicRuleTopicRuleActionRoleDefaultPolicy99ADD687": {
"Type": "AWS::IAM::Policy",
"Properties": {
"PolicyDocument": {
"Statement": [
{
"Action": "cloudwatch:PutMetricData",
"Effect": "Allow",
"Resource": "*"
}
],
"Version": "2012-10-17"
},
"PolicyName": "TopicRuleTopicRuleActionRoleDefaultPolicy99ADD687",
"Roles": [
{
"Ref": "TopicRuleTopicRuleActionRole246C4F77"
}
]
}
}
}
}
27 changes: 27 additions & 0 deletions packages/@aws-cdk/aws-iot-actions/test/cloudwatch-metric/integ.cloudwatch-metric-action.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/// !cdk-integ pragma:ignore-assets
import * as iot from '@aws-cdk/aws-iot';
import * as cdk from '@aws-cdk/core';
import * as actions from '../../lib';

const app = new cdk.App();

class TestStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);

const topicRule = new iot.TopicRule(this, 'TopicRule', {
sql: iot.IotSql.fromStringAsVer20160323("SELECT topic(2) as device_id, namespace, unit, value, timestamp FROM 'device/+/data'"),
});

topicRule.addAction(new actions.CloudWatchMetricAction({
metricName: '${topic(2)}',
metricNamespace: '${namespace}',
metricUnit: '${unit}',
metricValue: '${value}',
metricTimestamp: '${timestamp}',
}));
}
}

new TestStack(app, 'test-stack');
app.synth();