aws-health-events

Files (10)

• .skilleval.yaml
• CHANGELOG.md
• README.md
• SKILL.md
• benchmark.json · evals/
• eval_queries.json · evals/
• evals.json · evals/
• report.json · evals/
• trigger_report.json · evals/
• health-api-reference.md · references/

SKILL.md (first lines)

# 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

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

### 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`):

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

From aws/tools-for-devops-agent, Apache-2.0.

More from aws/tools-for-devops-agent