Event Patterns in CloudWatch Events

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. Changes you make
in either CloudWatch or EventBridge will appear in each console. For more information, see Amazon EventBridge.

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": "2017-12-22T18:43:48Z",
  "region": "us-west-1",
  "resources": [
    "arn:aws:ec2:us-west-1:123456789012:instance/ i-1234567890abcdef0"
  ],
  "detail": 
{
    "instance-id": " i-1234567890abcdef0",
    "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 are different
  depending on which service generated the event and what the event is. The
  combination of the source and detail-type
  fields serves to identify the fields and values found in the
  detail field. For examples of events generated by AWS
  services, see Event Types for CloudWatch
  Events.

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 appear in the detail field.

All events that are delivered via CloudTrail have AWS API Call via CloudTrail as
the value for detail-type. For more information, see Events Delivered Via CloudTrail.

source

Identifies the service that sourced the event. All events sourced from within
AWS 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.

To find the correct value for source for an AWS service, see the table
in AWS Service Namespaces.
For example, the source value for Amazon CloudFront is aws.cloudfront.

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 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 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.

When you write patterns to match events, you can use the TestEventPattern
API or the test-event-pattern CLI command to make sure that your pattern
will match the desired events. For more information, see TestEventPattern or test-event-pattern.

The following event patterns would match the event at the top of this page. The
first pattern matches because one of the instance values specified in the pattern
matches the event (and the pattern does not specify any additional fields not
contained in the event). The second one matches because the “terminated” state is
contained in the event.

{
  "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 do not match the event at the top of this page. The first pattern
does not match because the pattern specifies a “pending” value for state, and this value
does not appear in the event. The second pattern does not match because the resource
value specified in the pattern does not appear in the event.

{
  "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" ]
}

Matching Null Values and Empty Strings In Event Patterns

You can create a pattern that matches an event field that has a null value or an empty string. To see how this works,
consider the following example event:

{
  "version": "0",
  "id": "3e3c153a-8339-4e30-8c35-687ebef853fe",
  "detail-type": "EC2 Instance Launch Successful",
  "source": "aws.autoscaling",
  "account": "123456789012",
  "time": "2015-11-11T21:31:47Z",
  "region": "us-east-1",
  "resources": [
   ],
  "detail": 
{
    "eventVersion": "",
    "responseElements": null
   }
}

To match events where the value of eventVersion is an empty string, use the following pattern, which would match the
event example.

{
  "detail": 
{
     "eventVersion": [""]
  }
}

To match events where the value of responseElements is null, use the following pattern, which would match the
event example.

{
  "detail": 
{
     "responseElements": [null]
  }
}

Null values and empty strings are not interchangeable in pattern matching. A pattern that is written to detect empty strings will not
catch values of null.

Arrays In CloudWatch Events Patterns

The value of each field in a 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.

For example, an example event pattern includes the following text:

"resources": [
   "arn:aws:ec2:us-east-1:123456789012:instance/i-b188560f",
   "arn:aws:ec2:us-east-1:111122223333:instance/i-b188560f",
   "arn:aws:ec2:us-east-1:444455556666:instance/i-b188560f",
]

The example pattern would match an event that includes the following text, because the first
item in the pattern array matches the second item in the event array.

"resources": [
   "arn:aws:autoscaling:us-east-1:123456789012:autoScalingGroup:eb56d16b-bbf0-401d-b893-d5978ed4a025:autoScalingGroupName/ASGTerminate",
   "arn:aws:ec2:us-east-1:123456789012:instance/i-b188560f" 
]