Amazon CloudWatch Events

(1)

Amazon CloudWatch Events

User Guide

(2)

Amazon CloudWatch Events: User Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What Is Amazon CloudWatch Events?

NoteAmazon EventBridge is the preferred way to manage your events. CloudWatch Events and EventBridge are the same underlying service and API, but EventBridge provides more features.

Changes you make in either CloudWatch or EventBridge will appear in each console. For more information, see Amazon EventBridge.

Amazon CloudWatch Events delivers a near real-time stream of system events that describe changes in Amazon Web Services (AWS) resources. Using simple rules that you can quickly set up, you can match events and route them to one or more target functions or streams. CloudWatch Events becomes aware of operational changes as they occur. CloudWatch Events responds to these operational changes and takes corrective action as necessary, by sending messages to respond to the environment, activating functions, making changes, and capturing state information.

You can also use CloudWatch Events to schedule automated actions that self-trigger at certain times using cron or rate expressions. For more information, see Schedule Expressions for Rules (p. 30).

You can conﬁgure the following AWS services as targets for CloudWatch Events:

• Amazon EC2 instances

• AWS Lambda functions

• Streams in Amazon Kinesis Data Streams

• Delivery streams in Amazon Kinesis Data Firehose

• Log groups in Amazon CloudWatch Logs

• Amazon ECS tasks

• Systems Manager Run Command

• Systems Manager Automation

• AWS Batch jobs

• Step Functions state machines

• Pipelines in CodePipeline

• CodeBuild projects

• Amazon Inspector assessment templates

• Amazon SNS topics

• Amazon SQS queues

• Built-in targets: EC2 CreateSnapshot API call, EC2 RebootInstances API call, EC2 StopInstances API call, and EC2 TerminateInstances API call.

• The default event bus of another AWS account

Concepts

Before you begin using CloudWatch Events, you should understand the following concepts:

• Events – An event indicates a change in your AWS environment. AWS resources can generate events when their state changes. For example, Amazon EC2 generates an event when the state of an EC2 instance changes from pending to running, and Amazon EC2 Auto Scaling generates events when

(7)

Related AWS Services

it launches or terminates instances. AWS CloudTrail publishes events when you make API calls. You can generate custom application-level events and publish them to CloudWatch Events. You can also set up scheduled events that are generated on a periodic basis. For a list of services that generate events, and sample events from each service, see CloudWatch Events Event Examples From Supported Services (p. 39).

• Rules – A rule matches incoming events and routes them to targets for processing. A single rule can route to multiple targets, all of which are processed in parallel. Rules are not processed in a particular order. This enables diﬀerent parts of an organization to look for and process the events that are of interest to them. A rule can customize the JSON sent to the target, by passing only certain parts or by overwriting it with a constant.

• Targets – A target processes events. Targets can include Amazon EC2 instances, AWS Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, Amazon SNS topics, Amazon SQS queues, and built-in targets. A target receives events in JSON format.

A rule's targets must be in the same Region as the rule.

Related AWS Services

The following services are used in conjunction with CloudWatch Events:

• AWS CloudTrail enables you to monitor the calls made to the CloudWatch Events API for your account, including calls made by the AWS Management Console, the AWS CLI and other services.

When CloudTrail logging is turned on, CloudWatch Events writes log ﬁles to an S3 bucket. Each log ﬁle contains one or more records, depending on how many actions are performed to satisfy a request. For more information, see Logging Amazon CloudWatch Events API Calls with AWS CloudTrail (p. 107).

• AWS CloudFormation enables you to model and set up your AWS resources. You create a template that describes the AWS resources you want, and AWS CloudFormation takes care of provisioning and conﬁguring those resources for you. You can use CloudWatch Events rules in your AWS

CloudFormation templates. For more information, see AWS::Events::Rule in the AWS CloudFormation User Guide.

• AWS Config enables you to record configuration changes to your AWS resources. This includes how resources relate to one another and how they were configured in the past, so that you can see how the configurations and relationships change over time. You can also create AWS Config rules to check whether your resources are compliant or noncompliant with your organization's policies. For more information, see the AWS Config Developer Guide.

• AWS Identity and Access Management (IAM) helps you securely control access to AWS resources for your users. Use IAM to control who can use your AWS resources (authentication), what resources they can use, and how they can use them (authorization). For more information, see IAM User Guide.

• Amazon Kinesis Data Streams enables rapid and nearly continuous data intake and aggregation. The type of data used includes IT infrastructure log data, application logs, social media, market data feeds, and web clickstream data. Because the response time for the data intake and processing is in real time, processing is typically lightweight. For more information, see the Amazon Kinesis Data Streams Developer Guide.

• AWS Lambda enables you to build applications that respond quickly to new information. Upload your application code as Lambda functions and Lambda runs your code on high-availability compute infrastructure. Lambda performs all the administration of the compute resources, including server and operating system maintenance, capacity provisioning, automatic scaling, code and security patch deployment, and code monitoring and logging. For more information, see the AWS Lambda Developer Guide.

(8)

Sign Up for Amazon Web Services (AWS)

Setting Up Amazon CloudWatch Events

To use Amazon CloudWatch Events you need an AWS account. Your AWS account allows you to use services (for example, Amazon EC2) to generate events that you can view in the CloudWatch console, a web-based interface. In addition, you can install and conﬁgure the AWS Command Line Interface (AWS CLI) to use a command-line interface.

Sign Up for Amazon Web Services (AWS)

When you create an AWS account, we automatically sign up your account for all AWS services. You pay only for the services that you use.

If you have an AWS account already, skip to the next step. If you don't have an AWS account, use the following procedure to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Sign in to the Amazon CloudWatch Console

To sign in to the Amazon CloudWatch console

1. Sign in to the AWS Management Console and open the CloudWatch console at https://

console.aws.amazon.com/cloudwatch/.

2. If necessary, change the region. From the navigation bar, choose the region where you have your AWS resources.

3. In the navigation pane, choose Events.

Account Credentials

Although you can use your root user credentials to access CloudWatch Events, we recommend that you use an AWS Identity and Access Management (IAM) account. If you're using an IAM account to access CloudWatch, you must have the following permissions:

(9)

Set Up the Command Line Interface

{ "Version": "2012-10-17", "Statement": [

{

"Action": [ "events:*", "iam:PassRole"

],

"Effect": "Allow", "Resource": "*"

} ] }

Set Up the Command Line Interface

You can use the AWS CLI to perform CloudWatch Events operations.

For information about how to install and conﬁgure the AWS CLI, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.

Regional Endpoints

You must enable regional endpoints (the default) in order to use CloudWatch Events. For more information, see Activating and Deactivating AWS STS in an AWS Region in the IAM User Guide.

(10)

Getting Started with Amazon CloudWatch Events

Use the procedures in this section to create and delete CloudWatch Events rules. These are general procedures usable for any event source or target. For tutorials written for speciﬁc scenarios and speciﬁc targets, see Tutorials.

Each rule Contents

• Creating a CloudWatch Events Rule That Triggers on an Event (p. 6)

• Creating a CloudWatch Events Rule That Triggers on an AWS API Call Using AWS CloudTrail (p. 7)

• Creating a CloudWatch Events Rule That Triggers on a Schedule (p. 8)

• Deleting or Disabling a CloudWatch Events Rule (p. 8)

Restrictions

• The targets you associate with a rule must be in the same Region as the rule.

• Some target types might not be available in every region. For more information, see Regions and Endpoints in the Amazon Web Services General Reference.

• Creating rules with built-in targets is supported only in the AWS Management Console.

• If you create a rule with an encrypted Amazon SQS queue as a target, you must have the following section included in your KMS key policy. It allows the event to be successfully delivered to the encrypted queue.

{ "Sid": "Allow CWE to use the key", "Effect": "Allow",

"Principal": {

"Service": "events.amazonaws.com"

},

"Action": [

"kms:Decrypt", "kms:GenerateDataKey"

],

"Resource": "*"

}

(11)

Creating a Rule That Triggers on an Event

Creating a CloudWatch Events Rule That Triggers on an Event

Use the following steps to create a CloudWatch Events rule that triggers on an event emitted by an AWS service.

To create a rule that triggers on an event:

1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

2. In the navigation pane, choose Events, Create rule.

3. For Event source, do the following:

a. Choose Event Pattern, Build event pattern to match events by service.

b. For Service Name, choose the service that emits the event to trigger the rule.

c. For Event Type, choose the speciﬁc event that is to trigger the rule. If the only option is AWS API Call via CloudTrail, the selected service does not emit events and you can only base rules on API calls made to this service. For more information about creating this type of rule, see Creating a CloudWatch Events Rule That Triggers on an AWS API Call Using AWS CloudTrail (p. 7).

d. Depending on the service emitting the event, you may see options for Any... and Speciﬁc....

Choose Any... to have the event trigger on any type of the selected event, or choose Speciﬁc...

to choose one or more speciﬁc event types.

4. For Targets, choose Add Target and choose the AWS service that is to act when an event of the selected type is detected.

5. In the other ﬁelds in this section, enter information speciﬁc to this target type, if any is needed.

6. For many target types, CloudWatch Events needs permissions to send events to the target. In these cases, CloudWatch Events can create the IAM role needed for your event to run:

• To create an IAM role automatically, choose Create a new role for this speciﬁc resource.

• To use an IAM role that you created before, choose Use existing role.

7. Optionally, repeat steps 4-6 to add another target for this rule.

8. Choose Conﬁgure details. For Rule deﬁnition, type a name and description for the rule.

The rule name must be unique within this Region.

9. Choose Create rule.

(12)

Creating a Rule That Triggers on an AWS API Call via CloudTrail

Creating a CloudWatch Events Rule That Triggers on an AWS API Call Using AWS CloudTrail

To create a rule that triggers on an action by an AWS service that does not emit events, you can base the rule on API calls made by that service. The API calls are recorded by AWS CloudTrail. For more information about the API calls that you can use as triggers for rules, see Services Supported by CloudTrail Event History.

Rules in CloudWatch Events work only in the Region in which they are created. If you conﬁgure CloudTrail to track API calls in multiple Regions, and you want a rule based on CloudTrail to trigger in each of those Regions, you must create a separate rule in each Region that you want to track.

All events that are delivered via CloudTrail have AWS API Call via CloudTrail as the value for detail-type.

NoteIn CloudWatch Events, it is possible to create rules that lead to infinite loops, where a rule is fired repeatedly. For example, a rule might detect that ACLs have changed on an S3 bucket, and trigger software to change them to the desired state. If the rule is not written carefully, the subsequent change to the ACLs fires the rule again, creating an infinite loop.

To prevent this, write the rules so that the triggered actions do not re-ﬁre the same rule. For example, your rule could ﬁre only if ACLs are found to be in a bad state, instead of after any change.

An inﬁnite loop can quickly cause higher than expected charges. We recommend that you use budgeting, which alerts you when charges exceed your speciﬁed limit. For more information, see Managing Your Costs with Budgets.

To create a rule that triggers on an API call via CloudTrail:

b. For Service Name, choose the service that uses the API operations to use as the trigger.

c. For Event Type, choose AWS API Call via CloudTrail.

d. To trigger your rule when any API operation for this service is called, choose Any operation.

To trigger your rule only when certain API operations are called, choose Speciﬁc operation(s), type the name of an operation in the next box, and then press ENTER. To add more operations, choose +.

(13)

Creating a Rule That Triggers on a Schedule

Creating a CloudWatch Events Rule That Triggers on a Schedule

Use the following steps to create a CloudWatch Events rule that triggers on a regular schedule.

To create a rule that triggers on a regular schedule

3. For Event source, choose Schedule.

4. Choose Fixed rate of and specify how often the task is to run, or choose Cron expression and specify a cron expression that deﬁnes when the task is to be triggered. For more information about cron expression syntax, see Schedule Expressions for Rules (p. 30).

Deleting or Disabling a CloudWatch Events Rule

(14)

Deleting or Disabling a Rule

Use the following steps to delete or disable a CloudWatch Events rule.

To delete or disable a rule

2. In the navigation pane, choose Rules.

Managed rules have a box icon next to their names. For more information, see Amazon CloudWatch Events Managed Rules (p. 95).

3. Do one of the following:

a. To delete a rule, select the button next to the rule and choose Actions, Delete, Delete.

If the rule is a managed rule, you must type the name of the rule to acknowledge that it is a managed rule, and that deleting it may stop functionality in the service that created the rule. To continue, type the rule name and choose Force delete.

b. To temporarily disable a rule, select the button next to the rule and choose Actions, Disable, Disable.

You cannot disable a managed rule.

(15)

Tutorial: Relay Events to Systems Manager Run Command

CloudWatch Events Tutorials

Note

Amazon EventBridge is the preferred way to manage your events. CloudWatch Events and EventBridge are the same underlying service and API, but EventBridge provides more features.

The following tutorials show you how to create CloudWatch Events rules for certain tasks and targets.

Tutorials:

• Tutorial: Use CloudWatch Events to Relay Events to AWS Systems Manager Run Command (p. 10)

• Tutorial: Log the State of an Amazon EC2 Instance Using CloudWatch Events (p. 11)

• Tutorial: Log the State of an Auto Scaling Group Using CloudWatch Events (p. 13)

• Tutorial: Log Amazon S3 Object-Level Operations Using CloudWatch Events (p. 15)

• Tutorial: Use Input Transformer to Customize What is Passed to the Event Target (p. 17)

• Tutorial: Log AWS API Calls Using CloudWatch Events (p. 18)

• Tutorial: Schedule Automated Amazon EBS Snapshots Using CloudWatch Events (p. 20)

• Tutorial: Schedule AWS Lambda Functions Using CloudWatch Events (p. 21)

• Tutorial: Set AWS Systems Manager Automation as a CloudWatch Events Target (p. 24)

• Tutorial: Relay Events to an Amazon Kinesis Stream Using CloudWatch Events (p. 25)

• Tutorial: Run an Amazon ECS Task When a File is Uploaded to an Amazon S3 Bucket (p. 27)

• Tutorial: Schedule Automated Builds Using CodeBuild (p. 28)

• Tutorial: Log State Changes of Amazon EC2 Instances (p. 29)

Tutorial: Use CloudWatch Events to Relay Events to AWS Systems Manager Run Command

You can use Amazon CloudWatch Events to invoke AWS Systems Manager Run Command and perform actions on Amazon EC2 instances when certain events happen. In this tutorial, set up Run Command to run shell commands and conﬁgure each new instance that is launched in an Amazon EC2 Auto Scaling group. This tutorial assumes that you have already assigned a tag to the Amazon EC2 Auto Scaling group, with environment as the key and production as the value.

To create the CloudWatch Events rule

(16)

Tutorial: Log EC2 Instance States

b. For Service Name, choose Auto Scaling. For Event Type, choose Instance Launch and Terminate.

c. Choose Speciﬁc instance event(s), EC2 Instance-launch Lifecycle Action.

d. By default, the rule matches any Amazon EC2 Auto Scaling group in the region. To make the rule match a speciﬁc group, choose Speciﬁc group name(s) and then select one or more groups.

4. For Targets, choose Add Target, SSM Run Command.

5. For Document, choose AWS-RunShellScript (Linux). There are many other Document options that cover both Linux and Windows instances. For Target key, type tag:environment. For Target value(s), type production and choose Add.

6. Under Conﬁgure parameter(s), choose Constant.

7. For Commands, type a shell command and choose Add. Repeat this step for all commands to run when an instance launches.

8. If necessary, type the appropriate information in WorkingDirectory and ExecutionTimeout.

9. CloudWatch Events can create the IAM role needed for your event to run:

Tutorial: Log the State of an Amazon EC2 Instance Using CloudWatch Events

You can create an AWS Lambda function that logs the changes in state for an Amazon EC2 instance. You can choose to create a rule that runs the function whenever there is a state transition or a transition to one or more states that are of interest. In this tutorial, you log the launch of any new instance.

Step 1: Create an AWS Lambda Function

Create a Lambda function to log the state change events. You specify this function when you create your rule.

To create a Lambda function

1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

2. If you are new to Lambda, you see a welcome page. Choose Get Started Now. Otherwise, choose Create a Lambda function.

3. On the Select blueprint page, type hello for the ﬁlter and choose the hello-world blueprint.

(17)

Step 2: Create a Rule

4. On the Conﬁgure triggers page, choose Next.

5. On the Conﬁgure function page, do the following:

a. Type a name and description for the Lambda function. For example, name the function

"LogEC2InstanceStateChange".

b. Edit the sample code for the Lambda function. For example:

'use strict';

exports.handler = (event, context, callback) => { console.log('LogEC2InstanceStateChange');

console.log('Received event:', JSON.stringify(event, null, 2));

callback(null, 'Finished');

};

c. For Role, choose Choose an existing role. For Existing role, select your basic execution role.

Otherwise, create a new basic execution role.

d. Choose Next.

6. On the Review page, choose Create function.

Step 2: Create a Rule

Create a rule to run your Lambda function whenever you launch an Amazon EC2 instance.

To create a CloudWatch Events rule

a. Choose Event Pattern.

b. Choose Build event pattern to match events by service.

c. Choose EC2, EC2 Instance State-change Notiﬁcation.

d. Choose Speciﬁc state(s), Running.

e. By default, the rule matches any instance in the region. To make the rule match a speciﬁc instance, choose Speciﬁc instance(s) and then select one or more instances.

4. For Targets, choose Add target, Lambda function.

5. For Function, select the Lambda function that you created.

6. Choose Conﬁgure details.

7. For Rule deﬁnition, type a name and description for the rule.

Step 3: Test the Rule

To test your rule, launch an Amazon EC2 instance. After waiting a few minutes for the instance to launch and initialize, you can verify that your Lambda function was invoked.

To test your rule by launching an instance

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. Launch an instance. For more information, see Launch Your Instance in the Amazon EC2 User Guide for Linux Instances.

(18)

Tutorial: Log Auto Scaling Group States

4. In the navigation pane, choose Events, Rules, select the name of the rule that you created, and chooseShow metrics for the rule.

5. To view the output from your Lambda function, do the following:

a. In the navigation pane, choose Logs.

b. Choose the name of the log group for your Lambda function (/aws/lambda/function-name).

c. Choose the name of log stream to view the data provided by the function for the instance that you launched.

6. (Optional) When you are ﬁnished, you can open the Amazon EC2 console and stop or terminate the instance that you launched. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances.

Tutorial: Log the State of an Auto Scaling Group Using CloudWatch Events

You can run an AWS Lambda function that logs an event whenever an Auto Scaling group launches or terminates an Amazon EC2 instance and whether the launch or terminate event was successful.

For information about additional CloudWatch Events scenarios using Amazon EC2 Auto Scaling events, see Getting CloudWatch Events When Your Auto Scaling Group Scales in the Amazon EC2 Auto Scaling User Guide.

Step 1: Create an AWS Lambda Function

Create a Lambda function to log the scale-out and scale-in events for your Auto Scaling group. Specify this function when you create your rule.

"LogAutoScalingEvent".

'use strict';

(19)

exports.handler = (event, context, callback) => { console.log('LogAutoScalingEvent');

};

d. Choose Next.

6. Choose Create function.

Step 2: Create a Rule

Create a rule to run your Lambda function whenever your Auto Scaling group launches or terminates an instance.

To create a rule

c. Choose Auto Scaling, Instance Launch and Terminate.

d. To capture all successful and unsuccessful instance launch and terminate events, choose Any instance event.

4. By default, the rule matches any Auto Scaling group in the Region. To make the rule match a speciﬁc Auto Scaling group, choose Speciﬁc group name(s) and then select one or more Auto Scaling groups.

8. For Rule deﬁnition, type a name and description for the rule. For example, describe the rule as "Log whenever an Auto Scaling group scales out or in".

Step 3: Test the Rule

You can test your rule by manually scaling an Auto Scaling group so that it launches an instance. After waiting a few minutes for the scale-out event to occur, verify that your Lambda function was invoked.

To test your rule using an Auto Scaling group

1. To increase the size of your Auto Scaling group, do the following:

a. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

b. On the navigation pane, choose Auto Scaling, Auto Scaling Groups.

c. Select the check box for your Auto Scaling group.

d. On the Details tab, choose Edit. For Desired, increase the desired capacity by one. For example, if the current value is 2, type 3. The desired capacity must be less than or equal to the maximum

(20)

Tutorial: Log S3 Object Level Operations

size of the group. If your new value for Desired is greater than Max, you must update Max.

When you are ﬁnished, choose Save.

3. In the navigation pane, choose Events, Rules, select the name of the rule that you created, and then choose Show metrics for the rule.

b. Select the name of the log group for your Lambda function (/aws/lambda/function-name).

c. Select the name of log stream to view the data provided by the function for the instance that you launched.

5. (Optional) When you are ﬁnished, you can decrease the desired capacity by one so that the Auto Scaling group returns to its previous size.

Tutorial: Log Amazon S3 Object-Level Operations Using CloudWatch Events

You can log the object-level API operations on your S3 buckets. Before Amazon CloudWatch Events can match these events, you must use AWS CloudTrail to set up a trail conﬁgured to receive these events.

Step 1: Conﬁgure Your AWS CloudTrail Trail

To log data events for an S3 bucket to AWS CloudTrail and CloudWatch Events, create a trail. A trail captures API calls and related events in your account and delivers the log ﬁles to an S3 bucket that you specify. You can update an existing trail or create a new one.

To create a trail

1. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.

2. In the navigation pane, choose Trails, Create trail.

3. For Trail name, type a name for the trail.

4. For Data events, type the bucket name and preﬁx (optional). For each trail, you can add up to 250 Amazon S3 objects.

• To log data events for all Amazon S3 objects in a bucket, specify an S3 bucket and an empty preﬁx. When an event occurs on an object in that bucket, the trail processes and logs the event.

• To log data events for specific Amazon S3 objects, choose Add S3 bucket, then specify an S3 bucket and optionally the object prefix. When an event occurs on an object in that bucket and the object starts with the specified prefix, the trail processes and logs the event.

5. For each resource, specify whether to log Read events, Write events, or both.

6. For Storage location, create or choose an existing S3 bucket to designate for log ﬁle storage.

7. Choose Create.

(21)

Step 2: Create an AWS Lambda Function

For more information, see Data Events in the AWS CloudTrail User Guide.

Step 2: Create an AWS Lambda Function

Create a Lambda function to log data events for your S3 buckets. You specify this function when you create your rule.

2. If you are new to Lambda, you see a welcome page. Choose Create a function. Otherwise, choose Create function.

3. Choose Author from scratch.

4. Under Author from scratch, do the following:

a. Type a name for the Lambda function. For example, name the function "LogS3DataEvents".

b. For Role, choose Create a custom role.

A new window opens. Change the Role name if necessary, and choose Allow.

c. Back in the Lambda console, choose Create function.

5. Edit the code for the Lambda function to the following, and choose Save.

'use strict';

exports.handler = (event, context, callback) => { console.log('LogS3DataEvents');

};

Step 3: Create a Rule

Create a rule to run your Lambda function in response to an Amazon S3 data event.

2. In the navigation pane, choose Rules, Create rule.

c. Choose Simple Storage Service (S3), Object Level Operations.

d. Choose Speciﬁc operation(s), PutObject.

e. By default, the rule matches data events for all buckets in the region. To match data events for speciﬁc buckets, choose Specify bucket(s) by name and then specify one or more buckets.

(22)

Step 4: Test the Rule

To test the rule, put an object in your S3 bucket. You can verify that your Lambda function was invoked.

To view the logs for your Lambda function

2. In the navigation pane, choose Logs.

3. Select the name of the log group for your Lambda function (/aws/lambda/function-name).

4. Select the name of log stream to view the data provided by the function for the instance that you launched.

You can also check the contents of your CloudTrail logs in the S3 bucket that you speciﬁed for your trail.

For more information, see Getting and Viewing Your CloudTrail Log Files in the AWS CloudTrail User Guide.

Tutorial: Use Input Transformer to Customize What is Passed to the Event Target

Note

You can use the input transformer feature of CloudWatch Events to customize the text that is taken from an event before it is input to the target of a rule.

You can deﬁne multiple JSON paths from the event and assign their outputs to diﬀerent variables. Then you can use those variables in the input template as <variable-name>. The characters < and > cannot be escaped.

If you specify a variable to match a JSON path that does not exist in the event, then that variable is not created and does not appear in the output.

In this tutorial, we extract the instance-id and state of an Amazon EC2 instance from the instance state change event. We use the input transformer to put that data into an easy-to-read message that is sent to an Amazon SNS topic. The rule is triggered when any instance changes to any state. For example, with this rule, the following Amazon EC2 instance state-change notiﬁcation event produces the Amazon SNS message The EC2 instance i-1234567890abcdef0 has changed state to stopped.

{ "id":"7bf73129-1428-4cd3-a780-95db273d1602",

"detail-type":"EC2 Instance State-change Notification", "source":"aws.ec2",

"account":"123456789012", "time":"2015-11-11T21:29:54Z", "region":"us-east-1",

"resources":[

"arn:aws:ec2:us-east-1:123456789012:instance/ i-1234567890abcdef0"

],

(23)

Create a Rule

"detail":{

"instance-id":" i-1234567890abcdef0", "state":"stopped"

} }

We achieve this by mapping the instance variable to the $.detail.instance-id JSON path from the event, and the state variable to the $.detail.state JSON path. We then set the input template as "The EC2 instance <instance> has changed state to <state>."

Create a Rule

To customize instance state change information sent to a target using the input transformer 1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

c. Choose EC2, EC2 Instance State-change Notiﬁcation.

d. Choose Any state, Any instance.

4. For Targets, choose Add target, SNS topic.

5. For Topic, select the Amazon SNS topic for which to be notiﬁed when Amazon EC2 instances change state.

6. Choose Conﬁgure input, Input Transformer.

7. In the next box, type {"state" : "$.detail.state", "instance" : "$.detail.instance-id"}

8. In the following box, type "The EC2 instance <instance> has changed state to <state>."

10. Type a name and description for the rule, and choose Create rule.

Tutorial: Log AWS API Calls Using CloudWatch Events

Note

You can use an AWS Lambda function that logs each AWS API call. For example, you can create a rule to log any operation within Amazon EC2, or you can limit this rule to log only a speciﬁc API call. In this tutorial, you log every time an Amazon EC2 instance is stopped.

Prerequisite

Before you can match these events, you must use AWS CloudTrail to set up a trail. If you do not have a trail, complete the following procedure.

(24)

To create a trail

1. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.

2. Choose Trails, Create trail.

3. For Trail name, type a name for the trail.

4. For Storage location, in Create a new S3 bucket type the name for the new bucket that CloudTrail should deliver logs to.

5. Choose Create.

Step 1: Create an AWS Lambda Function

Create a Lambda function to log the API call events. Specify this function when you create your rule.

"LogEC2StopInstance".

'use strict';

exports.handler = (event, context, callback) => { console.log('LogEC2StopInstance');

};

d. Choose Next.

Step 2: Create a Rule

Create a rule to run your Lambda function whenever you stop an Amazon EC2 instance.

c. Choose EC2, AWS API Call via CloudTrail.

(25)

d. Choose Speciﬁc operation(s) and then type StopInstances in the box below.

Step 3: Test the Rule

You can test your rule by stopping an Amazon EC2 instance using the Amazon EC2 console. After waiting a few minutes for the instance to stop, check your AWS Lambda metrics in the CloudWatch console to verify that your function was invoked.

To test your rule by stopping an instance

3. Stop the instance. For more information, see Stop and Start Your Instance in the Amazon EC2 User Guide for Linux Instances.

5. In the navigation pane, choose Events, select the name of the rule that you created, and choose Show metrics for the rule.

c. Select the name of log stream to view the data provided by the function for the instance that you stopped.

7. (Optional) When you are ﬁnished, you can terminate the stopped instance. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances.

Tutorial: Schedule Automated Amazon EBS Snapshots Using CloudWatch Events

You can run CloudWatch Events rules according to a schedule. In this tutorial, you create an automated snapshot of an existing Amazon Elastic Block Store (Amazon EBS) volume on a schedule. You can choose a ﬁxed rate to create a snapshot every few minutes or use a cron expression to specify that the snapshot is made at a speciﬁc time of day.

Important

Creating rules with built-in targets is supported only in the AWS Management Console.

(26)

Step 1: Create a Rule

Create a rule that takes snapshots on a schedule. You can use a rate expression or a cron expression to specify the schedule. For more information, see Schedule Expressions for Rules (p. 30).

3. For Event Source, do the following:

a. Choose Schedule.

b. Choose Fixed rate of and specify the schedule interval (for example, 5 minutes). Alternatively, choose Cron expression and specify a cron expression (for example, every 15 minutes Monday through Friday, starting at the current time).

4. For Targets, choose Add target and then select EC2 CreateSnapshot API call. You may have to scroll up in the list of possible targets to ﬁnd EC2 CreateSnapshot API call.

5. For Volume ID, type the volume ID of the targeted Amazon EBS volume.

6. Choose Create a new role for this speciﬁc resource. The new role grants the target permissions to access resources on your behalf.

Step 2: Test the Rule

You can verify your rule by viewing your ﬁrst snapshot after it is taken.

To test your rule

2. In the navigation pane, choose Elastic Block Store, Snapshots.

3. Verify that the ﬁrst snapshot appears in the list.

4. (Optional) When you are ﬁnished, you can disable the rule to prevent additional snapshots from being taken.

a. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

b. In the navigation pane, choose Events, Rules.

c. Select the rule and choose Actions, Disable.

d. When prompted for conﬁrmation, choose Disable.

Tutorial: Schedule AWS Lambda Functions Using CloudWatch Events

(27)

You can set up a rule to run an AWS Lambda function on a schedule. This tutorial shows how to use the AWS Management Console or the AWS CLI to create the rule. If you would like to use the AWS CLI but have not installed it, see the AWS Command Line Interface User Guide.

CloudWatch Events does not provide second-level precision in schedule expressions. The ﬁnest resolution using a cron expression is a minute. Due to the distributed nature of the CloudWatch Events and the target services, the delay between the time the scheduled rule is triggered and the time the target service honors the execution of the target resource might be several seconds. Your scheduled rule is triggered within that minute but not on the precise 0th second.

Step 1: Create an AWS Lambda Function

Create a Lambda function to log the scheduled events. Specify this function when you create your rule.

"LogScheduledEvent".

'use strict';

exports.handler = (event, context, callback) => { console.log('LogScheduledEvent');

};

d. Choose Next.

Step 2: Create a Rule

Create a rule to run your Lambda function on a schedule.

To create a rule using the console

3. For Event Source, do the following:

(28)

a. Choose Schedule.

b. Choose Fixed rate of and specify the schedule interval (for example, 5 minutes).

If you prefer, you can create the rule using the AWS CLI. First, you must grant the rule permission to invoke your Lambda function. Then you can create the rule and add the Lambda function as a target.

To create a rule using the AWS CLI

1. Use the following put-rule command to create a rule that triggers itself on a schedule:

aws events put-rule \ --name my-scheduled-rule \

--schedule-expression 'rate(5 minutes)'

When this rule triggers, it generates an event that serves as input to the targets of this rule. The following is an example event:

{ "version": "0",

"id": "53dc4d37-cffa-4f76-80c9-8b7d4a4d2eaa", "detail-type": "Scheduled Event",

"source": "aws.events", "account": "123456789012", "time": "2015-10-08T16:53:06Z", "region": "us-east-1",

"resources": [

"arn:aws:events:us-east-1:123456789012:rule/my-scheduled-rule"

],

"detail": {}

}

2. Use the following add-permission command to trust the CloudWatch Events service principal (events.amazonaws.com) and scope permissions to the rule with the speciﬁed Amazon Resource Name (ARN):

aws lambda add-permission \

--function-name LogScheduledEvent \ --statement-id my-scheduled-event \ --action 'lambda:InvokeFunction' \ --principal events.amazonaws.com \

--source-arn arn:aws:events:us-east-1:123456789012:rule/my-scheduled-rule

3. Use the following put-targets command to add the Lambda function that you created to this rule so that it runs every ﬁve minutes:

aws events put-targets --rule my-scheduled-rule --targets file://targets.json

Create the ﬁle targets.json with the following contents:

[

(29)

Step 3: Verify the Rule

{

"Id": "1",

"Arn": "arn:aws:lambda:us-east-1:123456789012:function:LogScheduledEvent"

} ]

Step 3: Verify the Rule

At least ﬁve minutes after completing Step 2, you can verify that your Lambda function was invoked.

To test your rule

2. In the navigation pane, choose Events, Rules, select the name of the rule that you created, and choose Show metrics for the rule.

c. Select the name of log stream to view the data provided by the function for the instance that you launched.

4. (Optional) When you are ﬁnished, you can disable the rule.

a. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

b. In the navigation pane, choose Events, Rules.

c. Select the rule and choose Actions, Disable.

d. When prompted for conﬁrmation, choose Disable.

Tutorial: Set AWS Systems Manager Automation as a CloudWatch Events Target

You can use CloudWatch Events to invoke AWS Systems Manager Automation on a regular timed schedule, or when speciﬁed events are detected. This tutorial assumes that you are invoking Systems Manager Automation based on certain events.

To create the CloudWatch Events rule

a. Choose Event Pattern and choose Build event pattern to match events by service.

(30)

Tutorial: Relay Events to a Kinesis Stream

b. For Service Name and Event Type, choose the service and event type to use as the trigger.

Depending on the service and event type you choose, you may need to specify additional options under Event Source.

4. For Targets, choose Add Target, SSM Automation.

5. For Document, choose the Systems Manager document to run when the target is triggered.

6. (Optional), To specify a certain version of the document, choose Conﬁgure document version.

7. Under Conﬁgure parameter(s), choose No Parameter(s) or Constant.

If you choose Constant, specify the constants to pass to the document execution.

8. CloudWatch Events can create the IAM role needed for your event to run:

Tutorial: Relay Events to an Amazon Kinesis Stream Using CloudWatch Events

You can relay AWS API call events in CloudWatch Events to a stream in Amazon Kinesis.

Prerequisite

Install the AWS CLI. For more information, see the AWS Command Line Interface User Guide.

Step 1: Create an Amazon Kinesis Stream

Use the following create-stream command to create a stream.

aws kinesis create-stream --stream-name test --shard-count 1

When the stream status is ACTIVE, the stream is ready. Use the following describe-stream command to check the stream status:

aws kinesis describe-stream --stream-name test

Step 2: Create a Rule

As an example, create a rule to send events to your stream when you stop an Amazon EC2 instance.

(31)

c. Choose EC2, Instance State-change Notiﬁcation.

d. Choose Speciﬁc state(s), Running.

4. For Targets, choose Add target, Kinesis stream.

5. For Stream, select the stream that you created.

6. Choose Create a new role for this speciﬁc resource.

Step 3: Test the Rule

To test your rule, stop an Amazon EC2 instance. After waiting a few minutes for the instance to stop, check your CloudWatch metrics to verify that your function was invoked.

To test your rule by stopping an instance

4. In the navigation pane, choose Events, Rules, select the name of the rule that you created, and choose Show metrics for the rule.

5. (Optional) When you are ﬁnished, you can terminate the instance. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances.

Step 4: Verify That the Event is Relayed

You can get the record from the stream to verify that the event was relayed.

To get the record

1. Use the following get-shard-iterator command to start reading from your Kinesis stream:

aws kinesis get-shard-iterator --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON --stream-name test

The following is example output:

{

"ShardIterator": "AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp +KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/mBYWRO6OTZRKnW9gd

+efGN2aHFdkH1rJl4BL9Wyrk+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg="

(32)

Tutorial: Run an Amazon ECS Task When a File is Uploaded to an Amazon S3 Bucket }

2. Use the following get-records command to get the record. The shard iterator is the one you got in the previous step:

aws kinesis get-records --shard-

iterator AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp+KEd9I6AJ9ZG4lNR1EMi +9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk

+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg=

If the command is successful, it requests records from your stream for the speciﬁed shard. You can receive zero or more records. Any records returned might not represent all records in your stream. If you don't receive the data you expect, keep calling get-records.

Records in Kinesis are Base64-encoded. However, the streams support in the AWS CLI does not provide base64 decoding. If you use a base64 decoder to manually decode the data, you see that it is the event relayed to the stream in JSON form.

Tutorial: Run an Amazon ECS Task When a File is Uploaded to an Amazon S3 Bucket

You can use CloudWatch Events to run Amazon ECS tasks when certain AWS events occur. In this tutorial, you set up a CloudWatch Events rule that runs an Amazon ECS task whenever a ﬁle is uploaded to a certain Amazon S3 bucket using the Amazon S3 PUT operation.

This tutorial assumes that you have already created the task deﬁnition in Amazon ECS.

To run an Amazon ECS task whenever a ﬁle is uploaded to an S3 bucket using the PUT operation

c. For Service Name, choose Simple Storage Service (S3).

d. For Event Type, choose Object Level Operations.

e. Choose Speciﬁc operation(s), Put Object.

f. Choose Speciﬁc bucket(s) by name, and enter type the name of the bucket.

4. For Targets, do the following:

a. Choose Add target, ECS task.

b. For Cluster and Task Deﬁnition, select the resources that you created.

Amazon CloudWatch Events

Amazon CloudWatch Events

User Guide

Amazon CloudWatch Events: User Guide

Table of Contents

What Is Amazon CloudWatch Events?

Concepts

Related AWS Services

Setting Up Amazon CloudWatch Events

Sign Up for Amazon Web Services (AWS)

Sign in to the Amazon CloudWatch Console

Account Credentials

Set Up the Command Line Interface

Regional Endpoints

Getting Started with Amazon CloudWatch Events

Creating a CloudWatch Events Rule That Triggers on an Event

Creating a CloudWatch Events Rule That Triggers on an AWS API Call Using AWS CloudTrail

Creating a CloudWatch Events Rule That Triggers on a Schedule

Deleting or Disabling a CloudWatch Events Rule

CloudWatch Events Tutorials

Tutorial: Use CloudWatch Events to Relay Events to AWS Systems Manager Run Command

Tutorial: Log the State of an Amazon EC2 Instance Using CloudWatch Events

Step 1: Create an AWS Lambda Function

Step 2: Create a Rule

Step 3: Test the Rule

Tutorial: Log the State of an Auto Scaling Group Using CloudWatch Events

Step 1: Create an AWS Lambda Function

Step 2: Create a Rule

Step 3: Test the Rule

Tutorial: Log Amazon S3 Object-Level Operations Using CloudWatch Events

Step 1: Conﬁgure Your AWS CloudTrail Trail

Step 2: Create an AWS Lambda Function

Step 3: Create a Rule

Step 4: Test the Rule

Tutorial: Use Input Transformer to Customize What is Passed to the Event Target

Create a Rule

Tutorial: Log AWS API Calls Using CloudWatch Events

Prerequisite

Step 1: Create an AWS Lambda Function

Step 2: Create a Rule

Step 3: Test the Rule

Tutorial: Schedule Automated Amazon EBS Snapshots Using CloudWatch Events

Step 1: Create a Rule

Step 2: Test the Rule

Tutorial: Schedule AWS Lambda Functions Using CloudWatch Events

Step 1: Create an AWS Lambda Function

Step 2: Create a Rule

Step 3: Verify the Rule

Tutorial: Set AWS Systems Manager Automation as a CloudWatch Events Target

Tutorial: Relay Events to an Amazon Kinesis Stream Using CloudWatch Events

Prerequisite

Step 1: Create an Amazon Kinesis Stream

Step 2: Create a Rule

Step 3: Test the Rule

Step 4: Verify That the Event is Relayed

Tutorial: Run an Amazon ECS Task When a File is Uploaded to an Amazon S3 Bucket