Aws Health Events

AWS Health Event Review

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

When to Use This Skill

Incident Investigation (automatic activation):

• An active incident may be caused by an AWS service disruption or degradation.
• You observe service degradation, elevated error rates, latency spikes,

connection failures, throttling, or capacity issues.

• You need to determine whether an AWS-side event is the root cause or a

contributing factor to the current incident.

• You want to correlate observed symptoms with known AWS Health events.

Chat Reporting (on-demand activation):

• A user requests a health event summary or report for their account.
• A user wants to review the health posture of their AWS environment over a

specific time period.

• A user asks about recent AWS service issues affecting their account or region.

Prerequisites

• The account must have an AWS Business Support+, Enterprise Support, or

Unified Operations support plan to access the AWS Health API.

• The agent must have permissions to call the following IAM actions:
• health:DescribeEvents
• health:DescribeEventDetails
• health:DescribeAffectedEntities
• health:DescribeEventTypes
• The AWS Health API is only available in the us-east-1 region. All API

calls must target the us-east-1 endpoint regardless of where the affected resources are located.

• Health event data is available for up to 90 days. Events older than 90 days

cannot be retrieved via the API.

---

Step 1: Gather Incident Context

Before searching Health events, extract key details from the current incident:

1. Affected AWS services — identify the service(s) experiencing issues (e.g., EC2, RDS, Lambda, ELB, ECS). 2. Timeframe — determine when the incident started and its current duration. Use ISO 8601 timestamps. 3. Affected resources — collect specific resource identifiers (instance IDs, ARNs, endpoint names, cluster names). 4. Region and availability zone — identify the AWS region and, if known, the specific availability zone(s) affected. 5. Symptoms — note the observed symptoms (latency spikes, 5xx errors, connection timeouts, throttling, capacity errors).

Use these details as filter criteria in subsequent steps.

---

Step 2: Search Health Events

Use the AWS Health API DescribeEvents operation to retrieve events matching the incident context. All calls must target the us-east-1 endpoint.

API call pattern

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

Filtering strategies

Pagination handling

• Follow the nextToken from each response to retrieve subsequent pages.
• Continue paginating until nextToken is null or a maximum of 500 events

have been collected.

• Set maxResults to 100 per page for efficient retrieval.

---

Step 3: Filter Relevant Events

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.

Relevance filtering criteria

Evaluate each event from the DescribeEvents response using these fields (available without calling DescribeEventDetails):

Filtering rules

1. Keep events where the service matches an affected service or a related service from the Service Dependency Map. 2. Keep events where the active period (startTime to endTime, or to present if open) overlaps with the incident timeframe. 3. Keep events where the region or availabilityZone matches the incident's affected region/AZ. 4. Discard accountNotification events unless the incident context specifically suggests an account-level issue (e.g., abuse notification, certificate expiry). 5. Discard closed events that ended more than 2 hours before the incident started (unlikely to be contributing).

Result

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

---

Step 4: Get Event Details

For each relevant event identified in Step 3, retrieve full descriptions and timelines using DescribeEventDetails.

API call pattern

aws health describe-event-details \
  --region us-east-1 \
  --event-arns '["<arn-1>", "<arn-2>", ..., "<arn-10>"]'

Batching rules

• The API accepts a maximum of 10 event ARNs per request.
• If more than 10 relevant events need details, issue multiple batched calls of

up to 10 ARNs each until all relevant events are detailed.

Extract from each event detail

• Event description — the latestDescription text explaining the event.
• Timeline — start time, end time (null if ongoing), last updated time.
• Status — current status (open, closed, upcoming).
• Service and region — confirm the affected service and region.
• Event type — the category (issue, scheduledChange, accountNotification)

and specific type code.

Handling failedSet

• The response contains a successfulSet and a failedSet.
• If any event ARNs appear in failedSet, report the failed ARN and error

message to the operator.

• Continue processing all events from successfulSet without blocking on

failures.

---

Step 5: Identify Affected Entities

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.

API call pattern

aws health describe-affected-entities \
  --region us-east-1 \
  --filter '{"eventArns": ["<event-arn>"]}'
  --max-results 100

Entity matching

When the incident context includes specific resource identifiers:

1. Retrieve all affected entities for the event (paginate up to 500 entities per event using nextToken). 2. Perform exact string matching of each entity's entityValue against the incident context resource identifiers. 3. Present matched entities in a separate section before non-matched entities. 4. Include entity status (IMPAIRED, UNIMPAIRED, UNKNOWN, PENDING) and last updated time for each entity.

Error handling

• If DescribeAffectedEntities returns an error for a specific event ARN,

report the event ARN that failed and continue processing remaining events.

---

Step 6: Correlate with Incident

Score each Health event for relevance to the current incident using the following criteria:

Relevance scoring

Scoring rules

• Service match: The event's service code matches one of the affected

services from the incident context.

• Timeframe overlap: The event's active period (start time through end time,

or through present if still open) intersects with the incident's timeframe (start time through end time, or through present if ongoing).

• Region/AZ match: The event's region or availability zone matches the

incident's affected region or AZ.

• Resource match: At least one affected entity's entityValue matches a

resource identifier from the incident context.

Contributing factor labeling

• Any open event classified as High or Medium relevance SHALL be labeled as

a "likely contributing factor" in addition to its relevance classification.

• Closed events with High relevance should be noted as potential recent causes

if the incident started shortly after the event closed.

When resource identifiers are unavailable

If the incident context does not include specific resource identifiers, score relevance using only service, timeframe, and region/AZ factors:

• High: Matching service + overlapping timeframe + matching region or AZ
• Medium: Matching service + overlapping timeframe
• Low: Matching service only

---

Step 7: Present Structured Output

Present findings in a clear, structured format organized for quick comprehension and action.

Output structure

1. Summary — total events found, broken down by category and status. 2. Correlated events — grouped by event type category in this order:

• Issues (service disruptions) — present first
• Scheduled changes (maintenance) — present second
• Account notifications — present last

3. Within each group — sort by:

• Relevance classification (High → Medium → Low)
• Then by start time descending (most recent first)

4. Per event — include:

• Event type category and service
• Region and availability zone (if applicable)
• Status (open/closed/upcoming)
• Start time and end time (ISO 8601)
• Description (summarized to 256 characters max)
• Relevance classification and matching criteria
• Contributing factor label (if applicable)

5. Actionable next steps — for each correlated event, include at least one recommendation such as:

• Check specific affected resources
• Review related service limits or quotas
• Verify recent configuration changes
• Monitor the AWS Health Dashboard for updates
• Contact AWS Support if the event is ongoing

When no events are found

If no relevant Health events are identified:

• Explicitly state that no matching AWS Health events were found.
• Confirm the search parameters used (service, time range, region).
• Recommend checking other potential causes:
• Recent deployments or configuration changes
• Resource limits or quota exhaustion
• Network connectivity issues
• Application-level errors

---

Decision Tree: Event Search Strategy

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

---

Service Dependency Map

When the initial service-specific search returns no results, broaden the search to related services that share infrastructure dependencies:

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 Handling

---

Tips for Effective Health Event Review

• Always check us-east-1: The Health API endpoint is only in us-east-1,

regardless of where your resources are located.

• Start narrow, then broaden: Begin with the specific affected service and

a 7-day window. Only expand if no results are found.

• Check both open and closed events: A recently closed event may still be

causing residual impact.

• Correlate with support cases: If a Health event references a service

disruption, check if related support cases exist using the support-cases skill.

• Account-specific vs public events: Account-specific events directly affect

your resources. Public events are service-wide but may still impact you.

• Look at scheduled changes: Upcoming or recent maintenance windows can

explain transient issues that resolve on their own.

Changelog

1.0.0

• Initial version

AWS Health Events Skill

This skill enables the AWS DevOps Agent to retrieve and analyze AWS Health events during incident investigation, root cause analysis, and operational troubleshooting.

Purpose

When an operational incident occurs, AWS Health events provide critical visibility into service disruptions, scheduled maintenance, and account-specific notifications that may explain or correlate with observed issues. This skill searches AWS Health events by service, time window, severity, region, and event type to surface AWS-side events as potential root causes or contributing factors.

Key Capabilities

• Retrieve open and resolved AWS Health events via the Health API
• Search and filter events by service, severity, time range, region, and event type
• Identify affected resources impacted by Health events
• Correlate Health events with current incidents to determine root cause or contributing factors
• Generate health posture reports summarizing account health over configurable time periods

Prerequisites

• IAM permissions for health:Describe* actions (health:DescribeEvents, health:DescribeEventDetails, health:DescribeAffectedEntities, health:DescribeEventTypes)
• AWS Health API access (requires AWS Business Support+, Enterprise Support, or Unified Operations support plan)

Limitations

• The AWS Health API is only available in the us-east-1 region for commercial accounts
• Health event data retention is limited by the AWS Health service retention period
• API rate limits apply — the skill implements exponential backoff for throttled requests

Agent Types

This skill is used by the following agent types:

• Chat tasks — conversational health event lookup, reporting, and analysis
• Incident RCA — automated root cause analysis during active incidents

Uploading to AWS DevOps Agent

To deploy this skill to your Agent Space:

1. Zip the aws-health-events/ directory (only including allowed extensions):

   cd skills
   zip -r aws-health-events.zip aws-health-events/ -i '*.md' '*.txt' '*.json' '*.yaml' '*.yml' '*.xml' '*.csv' '*.tsv' '*.html' '*.htm' '*.png' '*.jpg' '*.jpeg' '*.gif' '*.svg' '*.webp' '*.pdf' -x '*/.claude/*' '*/scripts/*' '*/README.md' '*/.skilleval.yaml' '*/.skilleval.yml' '*/CHANGELOG.md' '*/evals/*'

2. In the AWS DevOps Agent Operator Web App, navigate to the Skills page. 3. Click Add skill → Upload skill. 4. Drag and drop the aws-health-events.zip file (max 6 MB). 5. Select the agent types: Chat tasks and Incident RCA. 6. Click Upload.

For more details, see Uploading a skill in the AWS DevOps Agent User Guide.

How to Use This Skill

This skill is most suitable for chat and investigation. Below are sample prompts for each use-case.

Chat

• "Create a health events report for the last 30 days, including breakdowns by service and event type."
• "Show me all open AWS Health events affecting my account."
• "Are there any scheduled maintenance events for RDS in the next 7 days?"
• "Summarize all EC2 health events from the past quarter."
• "What health events have occurred in us-west-2 this month?"
• "Give me a health posture summary for my account over the last 90 days."

Investigation

• "Investigate the RDS connectivity alarm — are there any related AWS Health events?"
• "We're seeing elevated error rates on our ECS service. Check if there's an AWS-side issue."
• "Our Lambda functions are timing out. Is there an active Health event for Lambda in us-east-1?"
• "There's a latency spike on our ALB starting around 2am UTC — correlate with any Health events."
• "Multiple services in us-west-2 are degraded. Check for regional Health events."
• "The same EBS performance issue keeps recurring. Are there related Health events or scheduled changes?"

AWS Health API Reference

Quick reference for the AWS Health API operations used by this skill.

DescribeEvents

Returns a list of Health events matching specified filter criteria.

Key Parameters

Response Fields

---

DescribeEventDetails

Returns detailed information for one or more Health events, including full descriptions.

Key Parameters

Response Fields

---

DescribeAffectedEntities

Returns a list of resources (entities) affected by a specific Health event.

Key Parameters

Response Fields

---

Common Service Codes

---

Event Type Categories

---

Event Statuses

---

Entity Status Codes

---

Important Constraints

• API endpoint: The AWS Health API is available only in the us-east-1

region. All API calls must target this region regardless of where the affected resources are located.

• Batch size: DescribeEventDetails accepts a maximum of 10 event ARNs

per request. For more than 10 events, issue multiple batched calls.

• Pagination: All list operations are paginated. Use nextToken from the

response to retrieve subsequent pages until nextToken is null.

• Rate limiting: Standard AWS API rate limits apply. Use exponential backoff

for retries on throttling errors (HTTP 429).

• Event scope: Use eventScopeCode to distinguish between account-specific

events (ACCOUNT_SPECIFIC) and public service events (PUBLIC).

• Data availability: Health events are available for up to 90 days. Events

older than 90 days cannot be retrieved via the API.

• IAM permissions required: health:DescribeEvents,

health:DescribeEventDetails, health:DescribeAffectedEntities, health:DescribeEventTypes.

• Affected entities: Only events with eventScopeCode=ACCOUNT_SPECIFIC have

affected entities. Public events do not return entity data.