# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.LoggingAndMonitoring.html
- https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights.html
- https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/limitless-monitoring.pi.html
- https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- RDS logging and monitoring guidance includes CloudWatch, CloudTrail, Enhanced Monitoring, Performance Insights, SNS, and Trusted Advisor as reliability evidence sources.
- Aurora Performance Insights monitors DB load and supports filtering by waits and SQL; AWS docs also flag Performance Insights mode/lifecycle considerations that must be checked for current deployments.

Sampled live evidence:
- Read-only regional availability sampling reported Amazon RDS, Amazon Aurora, and Amazon CloudWatch as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Sampled APIs `RDS+DescribeDBInstances` and `PI+DescribeDimensionKeys` were reported `isAvailableIn` in those regions.

Review implications:
- Performance investigation needs time window, DB load/AAS, wait events, top SQL, CPU/IO/memory/network, connection counts, storage, engine version, failover events, and recent changes.
- Availability of RDS APIs does not prove Performance Insights is enabled or that query-level evidence exists.

# RDS and Aurora Performance Evidence Guide

Use this reference for Amazon RDS/Aurora latency, connection exhaustion, slow SQL, lock waits, replica lag, failover behavior, storage pressure, CPU/I/O saturation, Performance Insights, Enhanced Monitoring, and database capacity investigations.

## What people get wrong

The lazy story is:

> Resize the database; CPU or connections are high.

Wrong. Database incidents often come from query plans, locks, connection pools, I/O, replication, failover, storage, or application behavior. Resizing can hide root cause and increase cost without fixing the workload.

Common bad assumptions:

- High CPU is the root cause.
- More connections improves throughput.
- Replica lag means the reader is too small.
- Performance Insights top SQL is always the culprit.
- Failover success means no user impact.
- Storage autoscaling removes storage risk.

## RDS/Aurora failure modes

- Connection pool storms exhaust DB connections or memory.
- Lock waits/deadlocks make healthy CPU look misleading.
- Query plan regression or missing index increases DB load and I/O.
- Aurora replica lag, cluster cache behavior, or writer/read endpoint routing causes stale or slow reads.
- Storage, burst balance, IOPS, temp space, or transaction logs saturate before CPU.
- Maintenance, parameter changes, failover, or backups correlate with performance but are not inspected.

## Minimum safe workflow

1. Identify engine, deployment topology, instance classes, writer/readers, timeframe, symptoms, and customer impact.
2. Build evidence timeline from CloudWatch, Performance Insights, Enhanced Monitoring, RDS events, logs, and deployment changes.
3. Separate symptoms from hypotheses: CPU, connections, waits, locks, I/O, storage, SQL, replication, failover, and app traffic.
4. Inspect top SQL/waits, connection pool settings, recent schema/parameter changes, and slow query/error logs where available.
5. Recommend low-risk mitigations first: query/index review, pool tuning, throttling callers, read routing, alarm thresholds, or controlled scaling.
6. Require approval for failover, reboot, parameter apply, scale, index creation, or query kill actions.
7. State what cannot be proven without database logs, PI data, or workload context.

## Verification targets

- CloudWatch metrics: CPUUtilization, DatabaseConnections, FreeableMemory, Read/WriteIOPS, Read/WriteLatency, DiskQueueDepth, FreeStorageSpace, ReplicaLag, Deadlocks
- Performance Insights DB load, waits, top SQL, dimensions, and retention/Advanced mode availability
- Enhanced Monitoring OS process/thread evidence and RDS/Aurora events
- slow query/error logs, lock/deadlock evidence, query plans, indexes, transaction age, and connection pool config
- cluster topology, endpoints, failover history, parameter groups, maintenance window, backups, and storage settings
- recent deployments, migrations, traffic changes, batch jobs, and application error rates

## When to push back

Push back if the user asks to:

- resize before inspecting waits, SQL, and connections
- kill sessions or fail over without impact/rollback approval
- ignore application connection pool behavior
- create indexes in production without plan and lock/space analysis
- call top SQL root cause without workload and wait context
- treat replica lag as purely instance-size problem

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Engine, instance or cluster topology, writer/reader role, version, parameter group, Region/AZ, and impact window
- CloudWatch metrics, Enhanced Monitoring, Performance Insights, logs, alarms, DB events, and deployment correlation
- Connections, CPU, memory, IOPS, latency, queue depth, replica lag, locks, waits, slow SQL, and storage growth
- Mitigation tradeoff: query/index fix, connection pool, parameter tuning, scaling, failover, maintenance, or rollback

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS RDS Aurora Performance Investigator: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```