Menu
Amazon CloudWatch Events
User Guide

Tutorial: Relay Events to a 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.

To create a rule

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

  2. In the navigation pane, choose Events.

  3. Choose Create rule.

  4. For Event source, do the following:

    1. Choose Event Pattern.

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

    3. Choose EC2 and then choose Instance State-change Notification.

    4. Choose Specific state(s) and then choose Running.

    The Event selector pane
  5. For Targets, choose Add target, and then choose Kinesis stream.

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

  7. Choose Configure details.

  8. For Rule definition, type a name and description for the rule.

  9. For AWS permissions, choose the option to create a new role. This opens the IAM console in a new tab. The new role grants CloudWatch Events permission to write records to your streams. Choose Allow. The tab with the IAM window closes.

  10. Choose Create rule.

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

  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.

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

  4. To view metrics for the event, do the following:

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

    2. Choose the name of the rule you created.

    3. Choose Show metrics for the rule.

  5. (Optional) When you are finished, 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 Amazon 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="
    }
  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 specified shard. You can receive zero or more records. Any records returned might not represents all records in your stream. If you don't receive the data you expect, keep calling get-records.

    Records in Amazon 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 will see that it is the event relayed to the stream in JSON form.