AWS X-Ray: Distributed Tracing

Modern cloud applications are rarely monolithic. A single user request might pass through an API Gateway, invoke a Lambda function, query DynamoDB, call an external API, and publish a message to SQS — all before returning a response. When something goes wrong (or goes slowly), pinpointing the bottleneck across these distributed components is extremely difficult with logs and metrics alone. This is where AWS X-Ray comes in.

---

What Is Distributed Tracing?

Distributed tracing is a technique for tracking a request as it moves through multiple services. A trace is a collection of segments (one per service) that together represent the full journey of a single request.

Think of a trace as a timeline:

[API Gateway] ──> [Lambda Function] ──> [DynamoDB]
   12 ms              85 ms               40 ms

By visualising this timeline, you can immediately see that the Lambda function accounts for most of the latency, and within that, the DynamoDB call accounts for nearly half.

---

Core Concepts

Traces

A trace is the top-level entity. It represents one end-to-end request and is identified by a unique Trace ID (e.g. 1-5e1a1234-abcdef1234567890abcdef12).

Segments

A segment represents the work done by a single service. Each service in the request path creates a segment that includes:

• Service name
• Start and end time
• HTTP request/response data
• Annotations and metadata

Subsegments

A subsegment represents a more granular unit of work within a segment. Common examples:

• An outbound HTTP call to another service
• A database query
• A call to an AWS SDK operation

Subsegments let you break down a service's processing time to find exactly where delays occur.

Annotations and Metadata

Type	Purpose	Indexed?
Annotations	Key-value pairs for filtering traces	Yes — you can search by annotation
Metadata	Additional data for debugging	No — not searchable

Use annotations for values you want to filter on (e.g. customerId, environment). Use metadata for large payloads that you only need when examining a specific trace.

---

How X-Ray Works

The X-Ray Daemon

The X-Ray daemon is a lightweight process that runs alongside your application. Your application sends trace data (segments) to the daemon over UDP on localhost:2000. The daemon batches and forwards the data to the X-Ray service.

• On EC2, you install and run the daemon as a system service.
• On ECS, you run the daemon as a sidecar container.
• On Lambda, the daemon is built in — no installation needed.
• On Elastic Beanstalk, enable X-Ray in the environment configuration.

The X-Ray SDK

To instrument your application, add the X-Ray SDK for your language (Node.js, Python, Java, Go, .NET, Ruby). The SDK automatically captures:

• Incoming HTTP requests
• Outbound HTTP calls
• AWS SDK calls
• SQL database queries

For a Node.js Express application:

const AWSXRay = require('aws-xray-sdk');
const express = require('express');

const app = express();
app.use(AWSXRay.express.openSegment('MyApp'));

// Your routes here

app.use(AWSXRay.express.closeSegment());

That is all it takes to begin capturing traces. The SDK wraps the HTTP module and AWS SDK to record subsegments automatically.

---

The X-Ray Service Map

The service map is a visual representation of your application's architecture generated automatically from trace data. Each node represents a service; edges represent calls between services. The map shows:

• Average latency between services
• Request rate (traces per minute)
• Error and fault rates (colour-coded: green = healthy, yellow = errors, red = faults)