| name | opensearch-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot Amazon OpenSearch Service problems (managed clusters and Serverless collections) by analyzing domain configurations, cluster health, indexing failures, search performance, storage pressure, JVM memory, shard management, snapshot/restore, access policies, VPC connectivity, Dashboards, UltraWarm/cold storage, and Serverless issues. Activate when: cluster health RED or YELLOW, search latency, indexing failures or throughput degradation, JVM memory pressure or GC pauses, disk watermark breaches, storage full, shard imbalance or unassigned shards, too many shards, mapping conflicts, bulk indexing errors, access policy denials, fine-grained access control (FGAC) issues, VPC connectivity problems, snapshot failures, restore issues, repository configuration, Dashboards access or visualization errors, UltraWarm or cold storage tier issues, ISM policy failures, index rollover problems, Serverless collection issues, Serverless capacity/scaling, split brain, dedicated master node issues, or the user says something is wrong with OpenSearch without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with OpenSearch Service, CloudWatch, CloudTrail, EC2 (for VPC/security groups), IAM, and optionally S3/KMS permissions. OpenSearch REST API access via curl recommended for direct cluster diagnostics.
|
OpenSearch Diagnostics
When to use
Any OpenSearch Service investigation where the console alone is insufficient — cluster health debugging, search performance analysis, indexing troubleshooting, shard management, storage pressure, JVM tuning, access policy resolution, VPC connectivity, snapshot/restore, Dashboards issues, UltraWarm/cold tier management, ISM lifecycle, or Serverless collection problems.
Investigation workflow
Step 1 — Collect and triage
aws opensearch describe-domain --domain-name <domain>
curl -XGET "https://<endpoint>/_cluster/health?pretty"
curl -XGET "https://<endpoint>/_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,disk.used_percent,node.role"
curl -XGET "https://<endpoint>/_cat/indices?v&s=health,index&h=health,status,index,pri,rep,docs.count,store.size"
aws cloudwatch get-metric-statistics --namespace AWS/ES --metric-name ClusterStatus.red --dimensions Name=DomainName,Value=<domain> Name=ClientId,Value=<account-id> --start-time <start> --end-time <end> --period 300 --statistics Maximum
aws cloudwatch get-metric-statistics --namespace AWS/ES --metric-name FreeStorageSpace --dimensions Name=DomainName,Value=<domain> Name=ClientId,Value=<account-id> --start-time <start> --end-time <end> --period 300 --statistics Minimum
aws cloudwatch get-metric-statistics --namespace AWS/ES --metric-name JVMMemoryPressure --dimensions Name=DomainName,Value=<domain> Name=ClientId,Value=<account-id> --start-time <start> --end-time <end> --period 300 --statistics Maximum
Step 2 — Domain deep dive
curl -XGET "https://<endpoint>/_cat/shards?v&s=state,index&h=index,shard,prirep,state,docs,store,node,unassigned.reason"
curl -XGET "https://<endpoint>/_nodes/stats?pretty"
curl -XGET "https://<endpoint>/_cluster/settings?include_defaults=true&pretty"
curl -XGET "https://<endpoint>/_cat/allocation?v"
aws opensearch describe-domain-config --domain-name <domain>
aws cloudwatch get-metric-statistics --namespace AWS/ES --metric-name CPUUtilization --dimensions Name=DomainName,Value=<domain> Name=ClientId,Value=<account-id> --start-time <start> --end-time <end> --period 300 --statistics Average,Maximum
Step 3 — Detailed investigation
aws opensearch describe-domain --domain-name <domain> --query 'DomainStatus.LogPublishingOptions'
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=es.amazonaws.com --max-results 20
curl -XGET "https://<endpoint>/<index>/_settings?pretty"
curl -XGET "https://<endpoint>/<index>/_mapping?pretty"
curl -XGET "https://<endpoint>/_cluster/allocation/explain?pretty"
Read references/opensearch-guardrails.md before concluding on any OpenSearch issue.
Tool quick reference
