aws-observability
aws/agent-toolkit-for-aws
Build, configure, and optimize AWS observability across CloudWatch, X-Ray, CloudTrail, and ADOT.
What is aws-observability?
Provides domain expertise for AWS observability across metrics, logs, and traces. Covers CloudWatch (Log Insights queries, alarms, dashboards, custom metrics, EMF), X-Ray tracing, CloudTrail auditing, and ADOT collector configuration. Use when troubleshooting monitoring, setting up alarms, querying logs, or configuring distributed tracing.
- Write and optimize CloudWatch Log Insights queries with fields, filters, stats, parsing, and subqueries
- Configure metric, composite, and anomaly detection alarms with proper missing data handling
- Design and build CloudWatch dashboards with cross-account/region widgets and dynamic labels
- Publish custom metrics via PutMetricData, EMF, and metric filters
- Set up X-Ray tracing with ADOT, sampling rules, and annotations
- Configure ADOT collectors for traces and EMF metrics
How to install aws-observability
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-observability- AWS account with CloudWatch, X-Ray, CloudTrail, and/or ADOT access
- AWS CLI or AWS MCP server for running commands and validating configurations
- (Optional) CDK for infrastructure-as-code alarm and dashboard templates
How to use aws-observability
- 1.Identify your observability need (logs, metrics, alarms, traces, or auditing) from the routing table
- 2.Read the corresponding reference file (log-insights.md, alarms.md, metrics.md, tracing.md, dashboards.md, troubleshooting.md, cloudtrail.md, or synthetics.md)
- 3.For alarms and dashboards, use the provided CDK template (alarm-template.ts) or ADOT config (otel-config.yaml) as a starting point
- 4.Apply the guidance to your AWS resources using AWS CLI or AWS MCP server
- 5.Validate configurations against current AWS documentation for runtime versions, quotas, and feature matrices
Use cases
- Investigate application performance issues by querying CloudWatch Logs Insights and correlating with metrics
- Set up alarms for Lambda functions with CDK templates and monitor INSUFFICIENT_DATA states
- Create synthetic canaries to monitor endpoint availability and troubleshoot failures
- Trace distributed requests across microservices using X-Ray and ADOT
- Audit who deleted a resource or changed configuration using CloudTrail
- DevOps engineers building monitoring and alerting infrastructure
- Backend developers troubleshooting application performance and errors
- AWS architects designing observability strategies across accounts and regions
- SREs investigating incidents and optimizing alarm configurations
- Security and compliance teams auditing resource changes with CloudTrail
aws-observability FAQ
Use this skill when you need to write Log Insights queries, configure alarms, set up X-Ray tracing, build dashboards, or troubleshoot observability issues. It provides structured guidance, query examples, and common failure patterns. Always confirm runtime versions and quotas against current AWS docs before production deployment.
No. This skill focuses on observability (metrics, alarms, traces, dashboards, auditing) not application logging infrastructure. For container log drivers or application log setup, consult AWS documentation or other resources.
Yes. All guidance works with standard AWS CLI access. The AWS MCP server is optional and enables running CLI commands and validating configurations directly within the agent.
Annotations are indexed key-value pairs searchable in X-Ray console; metadata is unindexed and useful for detailed debugging. Use annotations for filtering (e.g., user_id, environment) and metadata for large or complex data.
Check the alarm configuration (metric, statistic, period), verify the metric is publishing data, confirm the threshold and comparison operator, and review the missing data treatment setting. See alarms.md and troubleshooting.md for detailed diagnosis steps.
Full instructions (SKILL.md)
Source of truth, from aws/agent-toolkit-for-aws.
name: aws-observability description: Builds, configures, debugs, and optimizes AWS observability using CloudWatch (Logs Insights, Metrics, Alarms, Dashboards, EMF), X-Ray, CloudTrail, and ADOT. Covers Log Insights query syntax (fields, filter, stats, parse, pattern, join, subqueries), alarm configuration (metric, composite, anomaly detection, missing data treatment), dashboard design, custom metrics (PutMetricData, EMF, metric filters), X-Ray tracing (ADOT, sampling rules, annotations vs metadata), ADOT collector config, and CloudTrail auditing. Use when the user mentions CloudWatch, Log Insights, alarms, INSUFFICIENT_DATA, dashboards, custom metrics, EMF, X-Ray, traces, sampling, CloudTrail, who deleted, ADOT, OpenTelemetry, observability, monitoring, synthetics, canaries, or troubleshooting alarm behavior. Do NOT use for application logging setup, container log drivers, or security threat detection. version: 1
AWS Observability
Overview
Domain expertise for AWS observability across metrics, logs, and traces. Covers CloudWatch platform capabilities (alarms, dashboards, Log Insights, custom metrics, EMF), X-Ray trace analysis, CloudTrail operational auditing, and ADOT collector configuration.
Works best with the AWS MCP server — enables running CLI commands, querying CloudWatch, and validating configurations directly. All guidance also works with standard AWS CLI access.
Note: Reference files contain specific runtime versions, quota values, and feature matrices that may change. When precision matters (e.g., deploying to production, choosing a runtime, or checking a quota), confirm values against current AWS documentation rather than relying solely on the values in these files.
Routing
| User need | Action |
|---|---|
| Writing Log Insights queries | Read log-insights.md |
| Configuring alarms (metric, composite, anomaly) | Read alarms.md |
| Publishing custom metrics or using EMF | Read metrics.md |
| Setting up X-Ray tracing or ADOT | Read tracing.md |
| Building dashboards | Read dashboards.md |
| Debugging observability issues | Read troubleshooting.md — starts with the 5 most common fixes |
| Debugging canary failures | Read synthetics.md — see Common failures table |
| CloudTrail operational auditing | Read cloudtrail.md |
| Setting up Lambda monitoring with CDK | Use alarm-template.ts as a starting point |
| Creating synthetic canaries | Read synthetics.md |
| Configuring ADOT collector | Use otel-config.yaml as a starting point |
| Spans multiple areas | Read the most specific reference first, then consult others as needed |
Files
| File | Content |
|---|---|
| alarms.md | Metric, composite, anomaly detection alarms — configuration, constraints, recommended defaults |
| log-insights.md | Complete query syntax, commands, functions, known issues, reusable query library |
| metrics.md | Custom metrics, EMF spec, metric filters, high-resolution, retention |
| tracing.md | X-Ray → ADOT migration, sampling rules, annotations vs metadata, collector config |
| dashboards.md | Widget types, cross-account/region, dynamic labels, sharing |
| troubleshooting.md | Error → cause → fix for all observability services |
| cloudtrail.md | Operational auditing, event types, S3+Athena queries |
| synthetics.md | Canary runtime/blueprint constraints, VPC networking, common failures |
| alarm-template.ts | Best-practice CDK Lambda monitoring (alarms + dashboard) |
| otel-config.yaml | ADOT collector config for X-Ray traces + CloudWatch EMF metrics |
Related skills
More from aws/agent-toolkit-for-aws and the wider catalog.
aws-sdk-js-v3-usage
AWS SDK for JavaScript v3 development patterns and best practices.
aws-sdk-python-usage
AWS SDK for Python (boto3/botocore) development patterns and best practices.
aws-sdk-swift-usage
AWS SDK for Swift patterns and async client usage for S3, DynamoDB, CloudWatch, and other AWS services.
aws-serverless
Build, deploy, debug, and optimize serverless applications on AWS Lambda, API Gateway, Step Functions, and EventBridge.
aws-transform
Performs code upgrades, migrations, and transformations using the AWS Transform (ATX) CLI. Use when upgrading language versions, migrating AWS SDKs, migrating frameworks (Angular, Vue.js, Spring Boot, React), upgrading libraries, optimizing performance, migrating x86 to Graviton, analyzing codebases / generating documentation, or defining custom transformations with natural language. Runs locally on a few repositories or at scale across hundreds via AWS Batch/Fargate.
configuring-vpc-endpoints-for-private-aws-service-access
Configure VPC endpoints for private AWS service access using AWS PrivateLink