- Provides end-to-end distributed tracing for requests that traverse multiple services.
- Collects trace data, visualizes timelines and service maps, and highlights latency and failure points.
- Helps you pinpoint slow operations (database calls, external HTTP requests), error sources, and resource relationships.
How tracing fits into your application (flow)
- Instrumentation
- Use the X-Ray SDKs or integrated AWS services (API Gateway, Application Load Balancer, Lambda) to generate segments and subsegments.
- Propagation
- A trace header (for example, the
X-Amzn-Trace-IdHTTP header) is propagated with requests so downstream services can join the same trace.
- A trace header (for example, the
- Collection
- The X-Ray SDK sends trace data to the local X-Ray daemon (or sidecar), which buffers and uploads it to the X-Ray service.
- Visualization
- Use the X-Ray console to inspect traces, timeline details, and the service map; filter traces using annotations, status, or latency.
Sampling controls how many traces are recorded — tune sampling rules to capture representative traffic while controlling cost. Be cautious when adding high-cardinality annotations (for example, full email addresses or raw tokens), as they can increase storage and query costs and lead to privacy concerns.
- Install the SDK:
- Basic usage (automatic patching + manual subsegments)
- Decorator-style capture for functions:
- Install the SDK:
- Basic usage (capture HTTP clients and AWS SDK calls; create subsegments)
- Lambda
- Enable active tracing in the Lambda function configuration to integrate the execution environment with X-Ray automatically. Optionally, add the X-Ray SDK within your function for finer-grained subsegments and custom annotations.
- Containers / EC2
- Run the X-Ray daemon as a sidecar, system service, or host agent. SDKs send UDP packets to the daemon, which batches and uploads trace data to X-Ray.
- Sampling rules
- Customize sampling rules to prioritize traces from key endpoints or production traffic while limiting volume from noisy endpoints (for example, health checks).
Viewing traces and service maps
- Trace details: Use the timeline view to inspect segments and subsegments, see latencies, exceptions, and annotations.
- Service map: Visualize dependency graph, identify slow edges, and see aggregated latency and error rates between services.
- Search & filter: Use annotations (indexed) to filter traces by business identifiers (for example,
orderId), and use metadata for richer debugging context that does not need indexing.
Instrument hot paths first and add annotations for the most important business identifiers (for example,
orderId or transactionId) — this makes filtering and diagnosing issues in the X-Ray console much faster.- AWS X-Ray Developer Guide: https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html
- Instrumenting AWS Lambda with X-Ray: https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html
- aws-xray-sdk Python: https://pypi.org/project/aws-xray-sdk/
- aws-xray-sdk Node.js: https://www.npmjs.com/package/aws-xray-sdk