Menu
Amazon CloudWatch Events
User Guide

Events and Event Patterns

Events in Amazon CloudWatch Events are represented as JSON objects. For more information about JSON objects, see RFC 7159. The following is an example event:

{
  "version": "0",
  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "111122223333",
  "time": "2015-12-22T18:43:48Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-12345678"
  ],
  "detail": {
    "instance-id": "i-12345678",
    "state": "terminated"
  }
}

It is important to remember the following details about an event:

  • They all have the same top-level fields – the ones appearing in the example above – which are never absent.

  • The contents of the detail top-level field will be different depending on which service generated the event and what the event is.

  • The combination of the top-level source field and detail-type fields serve to identify the fields and values found in the detail field.

Each event field is described below.

version

By default, this is set to 0 (zero) in all events.

id

A unique value is generated for every event. This can be helpful in tracing events as they move through rules to targets, and are processed.

detail-type

Identifies, in combination with the source field, the fields and values that will appear in the detail field.

source

Identifies the service that sourced the event. All events sourced from within AWS will begin with "aws." Customer-generated events can have any value here as long as it doesn't begin with "aws." We recommend the use of java package-name style reverse domain-name strings.

account

The 12-digit number identifying an AWS account.

time

The event timestamp, which can be specified by the service originating the event. If the event spans a time interval, the service might choose to report the start time, so this value can be noticeably before the time the event is actually received.

region

Identifies the AWS region where the event originated.

resources

This JSON array contains ARNs that identify resources that are involved in the event. Inclusion of these ARNs is at the discretion of the service. For example, Amazon EC2 instance state-changes include Amazon EC2 instance ARNs, Auto Scaling events include ARNs for both instances and Auto Scaling groups, but API calls with AWS CloudTrail do not include resource ARNs.

detail

A JSON object, whose content is at the discretion of the service originating the event. The detail content in the example above is very simple, just two fields. AWS API call events have detail objects with around 50 fields nested several levels deep.

Event Patterns

Rules use event patterns to select events and route them to targets. A pattern either matches an event or it doesn't. Event patterns are represented as JSON objects with a structure that is similar to that of events, for example:

{
  "source": [ "aws.ec2" ],
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "detail": {
    "state": [ "running" ]
  }
}

It is important to remember the following things about event pattern matching:

  • For a pattern to match an event, the event must contain all the field names listed in the pattern. The field names must appear in the event with the same nesting structure.

  • Other fields of the event not mentioned in the pattern are ignored; effectively, there is a "*": "*" wildcard for fields not mentioned.

  • The value of each field in the pattern is an array containing one or more values, and the pattern matches if any of the values in the array match the value in the event.

  • If the value in the event is an array, then the pattern matches if the intersection of the pattern array and the event array is non-empty.

  • The matching is exact (character-by-character), without case-folding or any other string normalization.

  • The values being matched follow JSON rules: Strings enclosed in quotes, numbers, and the unquoted keywords true, false, and null.

  • Number matching is at the string representation level. For example, 300, 300.0, and 3.0e2 are not considered equal.

The following event patterns would match the event above.

{
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-12345678",
    "arn:aws:ec2:us-east-1:123456789012:instance/i-abcdefgh"
  ]
}
{
  "detail": {
    "state": [ "terminated" ]
  }
}

These event patterns would not match the event above:

{
  "source": [ "aws.ec2" ],
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "detail": {
    "state": [ "pending" ]
  }
}
{
  "source": [ "aws.ec2" ],
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1::image/ami-12345678" ]
}