AWSDOP-C02
On this page
Beginner-friendly overview

X-Ray

X-Ray is AWS's distributed tracing service. It traces requests as they travel through your application — from the frontend to a Lambda function, through an SQS queue, into a microservice, and out to a database — and visualizes the entire path with timing information so you can see exactly where slowness or errors occur.

The Microservices Visibility Problem

In a monolith, when a request is slow, you look at the single application's logs. In a distributed system of microservices, a slow request might cross five services, three queues, and two databases. When a user reports that checkout takes 8 seconds, which of those hops is responsible? Without distributed tracing, this question is extremely hard to answer.

X-Ray solves this by propagating a trace ID through every service a request touches. Each service records a segment — its portion of the work — and X-Ray assembles these into a complete picture of the request's journey.

One trace ID rides the whole request — each service files its own segment Client API Gateway 12 ms Lambda 380 ms — the slow hop DynamoDB 20 ms X-Amzn-Trace-Id header travels with the request → segment segment segment X-Ray stitches segments into one trace → timeline + service map Subsegments break a segment down further — e.g. the individual DynamoDB call inside the Lambda segment.

How Instrumentation Works

You add the X-Ray SDK to your application code and it automatically traces:

  • Incoming HTTP requests
  • Outbound calls to AWS services (S3, DynamoDB, SQS, SNS, etc.)
  • Outbound HTTP calls to external services
  • SQL queries (with supported drivers)

For Lambda, ECS, and API Gateway, X-Ray can be enabled with a configuration toggle and requires minimal or no code changes. The SDK handles trace ID generation and propagation automatically.

The Service Map

X-Ray generates a service map — a visual graph showing every service that participated in handling requests, the connections between them, and their error rates and latency distributions. At a glance, you can see which service is red (high error rate) or slow (wide latency box) and drill into the individual traces for that service.

Think road trip: the Trace is the whole trip, each Segment is one driver's leg, and Subsegments are the individual stops along that leg. For labelling the trip: Annotations are Ask-able (indexed, searchable — "find all trips for customer 42"), Metadata is Mute (stored in the trace, never searchable).

Sampling

X-Ray doesn't trace every single request by default — for high-traffic services that would generate enormous volumes of data. Instead, it samples a percentage of requests. You can configure the sample rate (e.g., 5% of requests) and define rules to always trace requests that meet certain criteria (e.g., always trace requests that return a 5xx error).