> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# X Ray
> AWS X-Ray distributed tracing guide explaining concepts, instrumentation for Python and Node.js, deployment patterns, sampling strategies, and using the console to analyze traces and service maps.
In this lesson you'll learn what AWS X-Ray does, the core tracing concepts it uses, and practical guidance for instrumenting applications (Python and Node.js). AWS X-Ray provides distributed tracing and visualization for microservices and serverless architectures so you can identify latency, errors, and service dependencies across an entire request path.
What does X-Ray do?
* 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.
Core concepts
| Concept | What it represents |
| -: | - |
| Trace | A full, end-to-end record of a single request as it travels through your system. |
| Segment | The portion of a trace representing work done by a single service or resource (e.g., a web server, Lambda function, or EC2 instance). |
| Subsegment | A finer-grained unit inside a segment for specific operations (e.g., a DB query, downstream HTTP call). |
| Service map | Visual graph in the X-Ray console showing services and the connections between them, with latency and error rates. |
| Annotations | Indexed key-value pairs you add to traces to make filtering/searching faster (e.g., `orderId`, `userId`). |
| Metadata | Non-indexed debugging data attached to traces (useful for richer context without increasing indexing costs). |
| Sampling | Rules that control the fraction of requests recorded as traces to balance observability and cost. |
| X-Ray daemon | Local process or sidecar that receives UDP packets from instrumented apps and forwards them to the X‑Ray service. |
How tracing fits into your application (flow)
1. Instrumentation
* Use the X-Ray SDKs or integrated AWS services (API Gateway, Application Load Balancer, Lambda) to generate segments and subsegments.
2. Propagation
* A trace header (for example, the `X-Amzn-Trace-Id` HTTP header) is propagated with requests so downstream services can join the same trace.
3. 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.
4. 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.
Examples: Instrumenting a Python application
* Install the SDK:
```bash theme={null}
pip install aws-xray-sdk
```
* Basic usage (automatic patching + manual subsegments)
```python theme={null}
from aws_xray_sdk.core import xray_recorder, patch_all
# Patch supported libraries (requests, boto3, sqlalchemy, etc.)
patch_all()
def handler(event, context):
# Create a named subsegment for a specific operation
subsegment = xray_recorder.begin_subsegment('my-operation')
try:
# Do work here (e.g., call another service, query DB)
result = do_some_work()
except Exception:
# Exceptions recorded in the segment are visible in the console
raise
finally:
xray_recorder.end_subsegment()
return result
```
* Decorator-style capture for functions:
```python theme={null}
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('process-data')
def process_data(payload):
# This function will be recorded as a subsegment named 'process-data'
...
```
Examples: Instrumenting a Node.js application
* Install the SDK:
```bash theme={null}
npm install aws-xray-sdk
```
* Basic usage (capture HTTP clients and AWS SDK calls; create subsegments)
```javascript theme={null}
const AWSXRay = require('aws-xray-sdk');
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
// Capture HTTP/HTTPS calls globally
AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.captureHTTPsGlobal(require('https'));
function handler(req, res) {
const segment = AWSXRay.getSegment(); // current segment
const subsegment = segment.addNewSubsegment('my-suboperation');
try {
// perform work
} catch (err) {
subsegment.addError(err);
throw err;
} finally {
subsegment.close();
}
res.end('done');
}
```
Deployment notes
* 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).
Deployment patterns and use cases
| Resource | Common deployment pattern | Notes |
| -: | - | - |
| Lambda | Enable active tracing or use SDK inside function | Best for serverless microservices; minimal config to start tracing. |
| Containers / ECS / Kubernetes | Run X-Ray daemon as sidecar per task/pod | Sidecar keeps network boundaries clear and simplifies SDK configuration. |
| EC2 | Run daemon as a systemd service or Docker container on host | Use for legacy apps or hosts with multiple instrumented processes. |
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.
Links and references
* AWS X-Ray Developer Guide: [https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html](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](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html)
* aws-xray-sdk Python: [https://pypi.org/project/aws-xray-sdk/](https://pypi.org/project/aws-xray-sdk/)
* aws-xray-sdk Node.js: [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
This article summarized AWS X-Ray concepts, how tracing flows through your application, example instrumentation for Python and Node.js, deployment considerations, and how to use the X-Ray console to analyze traces and service maps. Iterate on sampling rules and annotations as you gain visibility to maintain cost-effective and actionable observability.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.