Menu
Amazon CloudWatch
Developer Guide (API Version 2010-08-01)

Using CloudWatch Events

Amazon CloudWatch Events delivers a near real-time stream of system events that describe changes in Amazon Web Services (AWS) resources to AWS Lambda functions, Amazon SNS topics, Amazon SQS queues, streams in Amazon Kinesis Streams, or built-in targets. 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.

CloudWatch Events Components

The three main components of CloudWatch Events are events, rules, and targets:

  • Events—are generated in four ways. First, they are emitted by AWS when resources change state. For example, an event is generated when the state of an Amazon EC2 instance changes from pending to running or when Auto Scaling launches or terminates instances in your Auto Scaling group. Second, events are emitted by AWS CloudTrail when you make a read/write API call, or sign in to the AWS Management Console. Third, your own code can generate application-level events and publish them to CloudWatch Events for processing. Fourth, they can be issued on a scheduled basis, with options for periodic or cron-style scheduling.

  • Rules—match incoming events and route them to one or more targets for processing. Rules are not processed in any particular order. This allows different parts of a single organization to independently look for and process events that are of interest.

  • Targets—are specified in rules and receive matching events. Targets include AWS Lambda functions, Amazon SNS topics, Amazon SQS queues, streams in Amazon Kinesis Streams, or built-in targets (CloudWatch alarm actions). A single rule can specify multiple targets, all of which are processed in parallel. Each event is passed to each target in JSON form. A rule can customize the JSON that flows to the target, by passing only certain part of an event to the target, or overwriting the matched event with a constant. Some target types might not be available in every region. For more information about the endpoints that represent each region, see Regions and Endpoints in the Amazon Web Services General Reference.

Amazon CloudWatch Events Prerequisites

Amazon CloudWatch Events has the following prerequisites:

  • User accounts—Although you can use your root account, we recommend that you use an AWS Identity and Access Management (IAM) account. If you're using an IAM account, you must have "events:*" and "iam:PassRole" permissions:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": [
            "events:*",
            "iam:PassRole"
          ],
          "Effect": "Allow",
          "Resource": "*"
        }
      ]
    }
  • AWS CloudTrail logging—If you want to log AWS API calls in CloudWatch Events, you must turn on AWS CloudTrail. For more information, see Turning on CloudTrail in Additional Accounts in the AWS CloudTrail User Guide.

  • AWS Security Token Service (AWS STS)—Regional endpoints must be enabled (the default) in order to use Amazon CloudWatch Events. For more information, see Activating and Deactivating AWS STS in an AWS Region in the IAM User Guide.