2.3 Amazon EventBridge Rules, Event Buses & Troubleshooting
Key Takeaways
- Amazon EventBridge routes real-time events across three bus types: Default (AWS services), Custom (internal microservices), and Partner (third-party SaaS platforms like Datadog and PagerDuty).
- Event patterns match incoming JSON event envelopes using content-filtering operators including exact match, prefix match, numeric range, exists, and anything-but negation.
- Input Transformers format payloads at the target using inputPathsMap to extract JSON attributes and inputTemplate to assemble human-readable alerts or API payloads without intermediate Lambda functions.
- Target reliability is guaranteed through configurable retry policies (maximum event age up to 24 hours and retry attempts up to 185) paired with target-level Amazon SQS dead-letter queues (DLQs).
- EventBridge rule troubleshooting relies on CloudWatch metrics (MatchedEvents, TriggeredRules, FailedInvocations), target IAM permissions, and event bus archiving and replaying for post-incident recovery.
2.3 Amazon EventBridge Rules, Event Buses & Troubleshooting
Amazon EventBridge is the central serverless event bus service for modern cloud architectures. While CloudWatch alarms evaluate time-series metric thresholds, EventBridge reacts in real time to asynchronous state changes across AWS resources, custom applications, and SaaS partner platforms. For CloudOps engineers taking the SOA-C03 exam, mastering EventBridge requires a comprehensive understanding of event bus topologies, JSON event envelopes, complex event pattern filtering, payload transformations via Input Transformers, target retry policies, dead-letter queues (DLQs), and systematic event bus troubleshooting techniques.
Event Buses & The JSON Event Envelope
An EventBridge event bus is a pipeline that receives events, evaluates them against configured rules, and routes matching events to targets. EventBridge supports three types of event buses:
| Event Bus Type | Source of Ingress Events | Typical Operational Purpose |
|---|---|---|
| Default Event Bus | AWS services emitting state changes, AWS API call events via CloudTrail | Standard system monitoring (e.g., EC2 state changes, Auto Scaling lifecycle hooks, GuardDuty findings). |
| Custom Event Bus | Custom internal applications, microservices, container workloads | Isolating line-of-business domain events (e.g., order processing, payment events, CI/CD telemetry). |
| Partner Event Bus | Third-party SaaS providers (e.g., Datadog, PagerDuty, MongoDB Atlas, Auth0) | Ingesting external SaaS operational alerts directly into AWS architectures without custom webhooks. |
All events flowing through EventBridge follow a standardized JSON envelope structure:
{
"version": "0",
"id": "fe8d8442-1234-5678-abcd-1234567890ab",
"detail-type": "EC2 Instance State-change Notification",
"source": "aws.ec2",
"account": "123456789012",
"time": "2026-09-04T18:00:00Z",
"region": "us-east-1",
"resources": ["arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0"],
"detail": {
"instance-id": "i-0123456789abcdef0",
"state": "shutting-down"
}
}
The top-level fields (source, detail-type, time, account, region, resources) provide standard routing metadata, while the detail object contains the payload generated by the emitting service.
Rule Pattern Matching & Content Filtering
EventBridge rules use JSON event patterns to evaluate whether an incoming event should trigger configured targets. An event pattern has the same structure as the event it matches; an event matches a pattern if all fields present in the pattern exist in the event with matching values.
EventBridge provides sophisticated content-filtering syntax:
- Exact String Matching: Matches exact string values in an array:
{"detail": {"state": ["running", "stopped"]}} - Prefix Matching: Matches values starting with a specified prefix:
{"detail": {"bucket": {"name": [{"prefix": "prod-data-"}]}}} - Numeric Matching: Evaluates numbers using relational operators (
=,>,>=,<,<=, or range intervals):{"detail": {"memoryUsage": [{"numeric": [">=", 85]}]}} - Exists Matching: Checks whether a JSON key is present regardless of its value:
{"detail": {"compromisedCredentials": [{"exists": true}]}} - Anything-But Matching: Negates values, matching anything except the specified list, prefix, or suffix:
{"detail": {"state": [{"anything-but": ["running", "pending"]}]}} - Suffix Matching: Matches the trailing characters of a string (e.g., matching file extensions like
.tar.gz). - IP Address Matching: Matches IPv4 or IPv6 CIDR blocks (e.g.,
{"cidr": "10.0.0.0/24"}).
When designing patterns, engineers must remember that arrays inside an event pattern indicate an OR relationship (matching any element), whereas distinct top-level keys enforce an AND relationship.
Event Payload Transformation: Input Transformers
By default, EventBridge delivers the entire raw JSON event envelope to targets. When sending alerts to human-facing channels (such as Amazon SNS topics subscribed to email or Slack webhooks), raw JSON is difficult to read. Furthermore, API targets (like AWS Systems Manager Automation or Step Functions) often require payloads formatted in a specific schema.
The Input Transformer solves this problem without requiring an intermediate AWS Lambda function. It operates in two declarative steps:
- Input Paths Map (
inputPathsMap): Extracts values from the incoming event JSON using JSONPath expressions and assigns them to local variables. - Input Template (
inputTemplate): Constructs a customized string or JSON output, referencing the variables enclosed in<variable>tags.
For example, to transform an EC2 state-change event into a readable alert:
{
"InputTransformer": {
"InputPathsMap": {
"instance": "$.detail.instance-id",
"state": "$.detail.state",
"time": "$.time",
"account": "$.account"
},
"InputTemplate": "\"ALERT: EC2 Instance <instance> in account <account> changed state to <state> at <time>.\""
}
}
The resulting string is delivered cleanly to the SNS topic or webhook, improving readability and eliminating extra compute costs.
Target Retry Policies & Dead-Letter Queues (DLQs)
When EventBridge triggers a target (such as an AWS Lambda function, SQS queue, Kinesis stream, or SSM Automation runbook), invocation can fail due to target throttling, network failures, or misconfigured permissions.
Engineers configure two critical resilience parameters on each target:
- Maximum Age of Event: Defines how long EventBridge will retain and retry an unhandled event (from 1 minute up to 24 hours; default is 24 hours).
- Maximum Retry Attempts: Sets the number of retry attempts before discarding the event (from 0 to 185 attempts; default is 185).
To guarantee zero data loss, engineers attach an Amazon SQS Dead-Letter Queue (DLQ) to the target. If an event cannot be delivered within the configured retry attempts or age limit, EventBridge sends the event to the target's DLQ along with error attributes (ErrorCode, ErrorMessage). Note that in EventBridge, DLQs are configured per target, allowing different targets on the same rule to have independent error handling.
Troubleshooting EventBridge Rules
When an expected event does not trigger a target, CloudOps engineers analyze key CloudWatch metrics for the AWS/Events namespace:
| Metric | Meaning & Troubleshooting Guidance |
|---|---|
MatchedEvents | Number of events matching the rule's event pattern. If zero, verify the event pattern syntax or check CloudTrail to confirm the event was emitted. |
TriggeredRules | Number of rules triggered. If MatchedEvents is positive but TriggeredRules is zero, check whether the rule is currently disabled. |
Invocations | Number of times targets were invoked by the rule. |
FailedInvocations | Number of times target invocations failed. Indicates target permissions issues, throttling, or invalid target parameters. |
DeadLetterInvocations | Number of failed events successfully forwarded to the target's DLQ. |
Permissions & Security Policies
A common failure mode is missing target permissions. EventBridge interacts with targets using two distinct permission models:
- Resource-based policies: Used when invoking AWS Lambda, Amazon SNS, Amazon SQS, or Amazon CloudWatch Logs. The target resource's policy must grant
events.amazonaws.compermission to invoke it. - IAM Service Roles: Required when triggering targets that do not support resource-based policies, such as AWS Systems Manager Automation, AWS Step Functions, or AWS CodeBuild. The IAM role must trust
events.amazonaws.comand possess permissions to execute the target API (e.g.,ssm:StartAutomationExecution).
Event Archiving & Replaying
EventBridge includes native Event Archiving and Replaying. CloudOps engineers create an event archive on an event bus with a specified retention period (or indefinite retention). If a bug in a downstream consumer or an outage causes events to be processed incorrectly, engineers can fix the consumer logic and initiate an Event Replay, specifying a historical time window. EventBridge replays all archived events matching the bus or rule, enabling seamless disaster recovery and historical backfills.
A CloudOps engineer needs to write an EventBridge event pattern that triggers an incident notification whenever an EC2 instance state changes to anything OTHER THAN running or pending across all instances in the production VPC. Which event pattern syntax correctly achieves this filter?
An operations team wants an EventBridge rule that matches AWS Health events to publish formatted alerts directly to an Amazon SNS topic subscribed to by engineers' email addresses. Currently, subscribers receive raw, cryptic JSON blobs. The team wants to display only the event service name, event description, and affected resources in plain English without introducing an intermediate AWS Lambda function. Which solution meets these requirements with minimal complexity?
An EventBridge rule designed to trigger an AWS Step Functions state machine upon an S3 object upload appears to be failing silently. CloudWatch metrics for EventBridge show that MatchedEvents is incrementing, but TriggeredRules is zero, and FailedInvocations is not recording any failures. What is the most probable cause of this behavior, and how can the team verify and backfill events after fixing the issue?