| name | documentdb-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot Amazon DocumentDB problems by analyzing cluster configurations, instance health, query performance, index management, connectivity, replication, and following structured runbooks. Activate when: cluster creation failures, instance issues, storage problems, query performance degradation, index management, profiler analysis, connection failures, TLS configuration, connection pooling, read replica lag, global cluster issues, MongoDB compatibility differences, driver problems, change stream configuration, consumer issues, snapshot failures, PITR, authentication errors, encryption issues, or the user says something is wrong with DocumentDB without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with DocumentDB (docdb), CloudWatch, CloudTrail, EC2, KMS, IAM, and optionally mongo shell for direct cluster diagnostics.
|
DocumentDB Diagnostics
When to use
Any Amazon DocumentDB investigation where the console alone is insufficient — cluster health analysis, query performance debugging, connectivity troubleshooting, replication monitoring, MongoDB compatibility issues, change stream problems, backup/restore, or security configuration.
Investigation workflow
Step 1 — Collect and triage
aws docdb describe-db-clusters
aws docdb describe-db-clusters --db-cluster-identifier <cluster-id>
aws docdb describe-db-instances --filters Name=db-cluster-id,Values=<cluster-id>
aws cloudwatch get-metric-statistics --namespace AWS/DocDB --metric-name CPUUtilization --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/DocDB --metric-name FreeableMemory --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/DocDB --metric-name DatabaseConnections --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Maximum
Step 2 — Domain deep dive
aws docdb describe-db-cluster-parameters --db-cluster-parameter-group-name <param-group>
aws docdb describe-events --source-type db-cluster --duration 1440
aws docdb describe-events --source-type db-instance --duration 1440
aws docdb describe-db-cluster-endpoints --db-cluster-identifier <cluster-id>
mongo --tls --host <cluster-endpoint> --username <user> --password <pass> --eval "db.serverStatus()"
mongo --tls --host <cluster-endpoint> --username <user> --password <pass> --eval "db.currentOp()"
Step 3 — Detailed investigation
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=rds.amazonaws.com --max-results 20
aws docdb describe-db-cluster-snapshots --db-cluster-identifier <cluster-id>
aws docdb describe-global-clusters
aws cloudwatch get-metric-statistics --namespace AWS/DocDB --metric-name ReadReplicaLag --dimensions Name=DBInstanceIdentifier,Value=<instance-id> --start-time <start> --end-time <end> --period 60 --statistics Maximum
aws kms describe-key --key-id <key-id>
aws ec2 describe-security-groups --group-ids <sg-id>
Read references/documentdb-guardrails.md before concluding on any DocumentDB issue.
Tool quick reference
| Tool / API | When to use |
|---|
describe-db-clusters | Cluster configuration and status |
describe-db-instances | Instance details and health |
describe-db-cluster-parameters | Parameter group settings |
describe-events | Recent cluster and instance events |
describe-db-cluster-endpoints | Cluster endpoints configuration |
describe-db-cluster-snapshots | Snapshot details |
describe-global-clusters | Global cluster configuration |
mongo serverStatus() | Real-time server statistics |
mongo currentOp() | Active operations |
CloudWatch DocDB metrics | Performance and capacity metrics |
Gotchas: Amazon DocumentDB
- DocumentDB is NOT MongoDB. It is API-compatible with MongoDB 3.6, 4.0, and 5.0 but uses a different storage engine (Aurora-based). Not all MongoDB features are supported. Always check the DocumentDB documentation for supported operations, not MongoDB documentation.
- TLS is required by default. All connections must use TLS. The rds-combined-ca-bundle.pem certificate must be specified in the connection string. Disabling TLS requires modifying the cluster parameter group (tls=disabled), which is NOT recommended for production.
- No $lookup across collections in older versions. DocumentDB 4.0 added limited $lookup support. DocumentDB 5.0 has broader $lookup support. Always verify aggregation pipeline stage support for your engine version.
- Change streams have 24-hour retention. Change stream events are retained for 24 hours (configurable up to 7 days with change_stream_log_retention_duration parameter). Consumers must process events within the retention window or they are lost. Change streams require a resume token for reliable processing.
- Elastic clusters use sharding (different from standard). Elastic clusters distribute data across shards using a shard key. Standard clusters use a single-writer, multi-reader architecture. Elastic clusters have different API endpoints and connection patterns. Not all features available in standard clusters work in elastic clusters.
- Parameter groups differ from MongoDB config. DocumentDB uses cluster parameter groups (similar to RDS), not MongoDB configuration files. Parameters like profiler, TTL monitor, and audit logging are controlled via parameter groups. Some MongoDB parameters have no DocumentDB equivalent.
- No direct mongodump/mongorestore. DocumentDB does not support mongodump/mongorestore for backup. Use AWS native snapshots, PITR, or AWS DMS for data migration. For logical exports, use mongoexport/mongoimport or custom scripts.
- Index builds are foreground by default. Index creation blocks writes on the collection in DocumentDB (unlike MongoDB 4.2+ which has background index builds). Plan index creation during maintenance windows. Monitor index build progress with currentOp().
Anti-hallucination rules
- Always cite specific cluster identifiers, instance IDs, CloudWatch metrics, or mongo shell output as evidence.
- DocumentDB is NOT MongoDB. Never reference MongoDB-specific features without verifying DocumentDB support.
- TLS is required by default. Never suggest connecting without TLS unless the parameter is explicitly disabled.
- Change streams have limited retention (24h default). Never assume unlimited retention.
- Index builds block writes. Never suggest building indexes on production collections without planning for write impact.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
24 runbooks
| Category | IDs | Covers |
|---|
| A — Cluster | A1-A3 | Creation failures, instance issues, storage |
| B — Performance | B1-B3 | Query performance, index management, profiler |
| C — Connectivity | C1-C3 | Connection failures, TLS, connection pooling |
| D — Replication | D1-D2 | Read replicas, global clusters |
| E — Compatibility | E1-E2 | MongoDB differences, driver issues |
| F — Change Streams | F1-F2 | Stream configuration, consumer issues |
| G — Backup | G1-G2 | Snapshot failures, PITR |
| H — Security | H1-H2 | Authentication, encryption |
| Z — Catch-All | Z1 | General troubleshooting |
