Terminal
Terminal/Skill
Pulls AWS Health events for a service, region and time window to check whether AWS-side issues explain an incident or outage.
By Amazon Web Services
Works with
npx skills add aws/tools-for-devops-agent --skill aws-health-eventsUse this skill when investigating an incident and you need to check for AWS-side service events that may be causing or contributing to the observed issue. Also use this skill when a user requests a summary report of AWS Health events over a configurable time period.
Incident Investigation (automatic activation):
Chat Reporting (on-demand activation):
health:DescribeEventshealth:DescribeEventDetailshealth:DescribeAffectedEntitieshealth:DescribeEventTypesus-east-1 endpoint regardless of where the affected
resources are located.Before searching Health events, extract key details from the current incident:
Use these details as filter criteria in subsequent steps.
Use the AWS Health API DescribeEvents operation to retrieve events matching
the incident context. All calls must target the us-east-1 endpoint.
aws health describe-events \
--region us-east-1 \
--filter '{
"services": ["<SERVICE_CODE>"],
"startTimes": [{"from": "<ISO-8601-start>"}],
"regions": ["<affected-region>"],
"eventStatusCodes": ["open", "closed"],
"eventTypeCategories": ["issue", "scheduledChange", "accountNotification"]
}' \
--max-results 100
| Strategy | How to Apply |
|---|---|
| By service | Use the services filter with the AWS Health service code (e.g., EC2, RDS, ELASTICLOADBALANCING), because service-specific events are most likely to correlate with the incident. |
| By time range | Use startTimes with a from value set to 7 days before the incident start, because events that started before the incident may still be active and causing impact. |
| By region | Use the regions filter to scope events to the affected region, because regional events are more likely to impact the specific resources under investigation. |
| By availability zone | Use the availabilityZones filter when the incident is isolated to a specific AZ, because AZ-scoped events have the highest correlation with AZ-specific failures. |
| By status | Include both open and closed statuses, because recently closed events may have caused residual impact that is still being observed. |
| By event scope | Include both ACCOUNT_SPECIFIC and PUBLIC events, because public service events affect all accounts in the region while account-specific events target your resources directly. |
nextToken from each response to retrieve subsequent pages.nextToken is null or a maximum of 500 events
have been collected.maxResults to 100 per page for efficient retrieval.Before retrieving full event details, filter the events returned in Step 2 to
identify only those relevant to the current investigation. This avoids
unnecessary DescribeEventDetails calls for events that are clearly unrelated.
Evaluate each event from the DescribeEvents response using these fields
(available without calling DescribeEventDetails):
| Field | Relevance Signal |
|---|---|
service | Must match one of the affected services from the incident context, or a related service from the Service Dependency Map |
eventTypeCategory | Prioritize issue events for active incidents; include scheduledChange if the incident coincides with a maintenance window |
eventTypeCode | Match against known operational event patterns (e.g., AWS_EC2_OPERATIONAL_ISSUE, AWS_RDS_MAINTENANCE) |
statusCode | Prioritize open events; include closed only if the event ended within 2 hours of the incident start |
startTime / endTime | The event's active period must overlap with the incident timeframe |
region / availabilityZone | Must match the incident's affected region or AZ |
service matches an affected service or a related
service from the Service Dependency Map.region or availabilityZone matches the
incident's affected region/AZ.accountNotification events unless the incident context
specifically suggests an account-level issue (e.g., abuse notification,
certificate expiry).closed events that ended more than 2 hours before the incident
started (unlikely to be contributing).After filtering, proceed to Step 4 only with the relevant subset of events. If all events are filtered out, report that no relevant Health events were found and suggest alternative investigation paths (see Step 7).
For each relevant event identified in Step 3, retrieve full descriptions
and timelines using DescribeEventDetails.
aws health describe-event-details \
--region us-east-1 \
--event-arns '["<arn-1>", "<arn-2>", ..., "<arn-10>"]'
latestDescription text explaining the event.successfulSet and a failedSet.failedSet, report the failed ARN and error
message to the operator.successfulSet without blocking on
failures.For events with eventScopeCode of ACCOUNT_SPECIFIC, retrieve the list of
affected resources using DescribeAffectedEntities.
Important: Only call DescribeAffectedEntities for ACCOUNT_SPECIFIC events. PUBLIC events do not return entity data.
aws health describe-affected-entities \
--region us-east-1 \
--filter '{"eventArns": ["<event-arn>"]}'
--max-results 100
When the incident context includes specific resource identifiers:
nextToken).entityValue against the
incident context resource identifiers.IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING) and
last updated time for each entity.DescribeAffectedEntities returns an error for a specific event ARN,
report the event ARN that failed and continue processing remaining events.Score each Health event for relevance to the current incident using the following criteria:
| Classification | Criteria | Label |
|---|---|---|
| High | Matching service + overlapping timeframe + matching affected resource (or matching region/AZ if no resource IDs available) | Likely contributing factor (if event is open) |
| Medium | Matching service + overlapping timeframe (no resource match) | Likely contributing factor (if event is open) |
| Low | Matching service only (no timeframe overlap) | Background context |
entityValue matches a
resource identifier from the incident context.If the incident context does not include specific resource identifiers, score relevance using only service, timeframe, and region/AZ factors:
Present findings in a clear, structured format organized for quick comprehension and action.
If no relevant Health events are identified:
Is this a chat-based health report request?
├── YES → Search the user-specified time period (default 30 days, max 90 days)
│ Organize results by category, service, and status
│ Present as a summary report
└── NO → Continue with incident investigation flow below
Is the affected AWS service known?
├── YES → Search events for that service within the past 7 days
│ ├── Events found → Proceed to Step 3 (Filter Relevant Events)
│ └── No events found → Broaden to related services (see Service Dependency Map)
│ ├── Events found → Proceed to Step 3
│ └── No events found → Expand time window to 14 days and retry
│ ├── Events found → Proceed to Step 3
│ └── No events found → Report no events found, suggest other investigation paths
└── NO → Search all services filtered by region and availability zone (past 7 days)
├── Events found → Proceed to Step 3
└── No events found → Expand time window to 14 days
├── Events found → Proceed to Step 3
└── No events found → Report no events found, suggest other investigation paths
Does the incident involve a specific availability zone?
├── YES → Include the AZ filter in all searches above
└── NO → Filter by region only
When the initial service-specific search returns no results, broaden the search to related services that share infrastructure dependencies:
| Primary Service | Related Services to Check |
|---|---|
| ELB / ALB / NLB | EC2, VPC, Route 53 |
| RDS | EC2, EBS |
| ECS / EKS | EC2, VPC, ELB |
| Lambda | VPC, CloudWatch |
| CloudFront | S3, Route 53 |
| API Gateway | Lambda, VPC |
| ElastiCache | EC2, VPC |
| DynamoDB | VPC (if VPC endpoints used) |
| S3 | CloudFront, VPC (if VPC endpoints used) |
| Kinesis | EC2, VPC |
Search up to 3 related services when broadening. Use the Health API service
codes from the references document (e.g., ELASTICLOADBALANCING for ELB,
ROUTE53 for Route 53).
| Error Condition | Agent Behavior |
|---|---|
Missing health:Describe* permissions | Report the missing permissions and specify the required IAM actions: health:DescribeEvents, health:DescribeEventDetails, health:DescribeAffectedEntities, health:DescribeEventTypes. Provide the IAM policy snippet needed. |
| Throttling (HTTP 429) | Retry with exponential backoff: wait 1s → 2s → 4s (max 3 retries). If still throttled after 3 retries, report that the Health API is currently rate-limited and recommend trying again shortly. |
| Service error (HTTP 5xx) | Report the error code and recommend the operator check the AWS Health Dashboard directly as a fallback. |
| Timeout (30 seconds) | Cancel the request and report a timeout error. Suggest the operator check the Health Dashboard directly or retry with narrower filters. |
| Zero events found | Report that no events matched the specified filters. Confirm the search parameters used. Suggest broadening the search or checking other investigation paths. |
| Invalid time range (start > end) | Report the invalid time range error. Ask the operator to provide corrected timestamps. |
| DescribeEventDetails failedSet | Report the failed event ARNs and error messages. Continue processing events from the successfulSet. |
| DescribeAffectedEntities error | Report the event ARN for which entity retrieval failed. Continue processing remaining events. |
| Unknown service name (chat report) | Inform the user the service was not recognized. List services that have events in the requested time period. |