AWS X-Ray in 5 Minutes

What is AWS X-Ray?

X-ray is AWS's distributed tracing system. What the hell is a distributed tracing system? That means that you can trace requests as they travel through your architecture. Distributed tracing allows you to find any bottlenecks that may exist in your application flow. When working in a micro-service world distributed tracing is a powerful tool that allows developers, operations, architects, and managers to see the big picture view of the application. Splunk provides a great explanation of distributed tracing.

X-Ray is AWS's distributed tracing solution. It allows users to trace requests through an application then view and filter information from that request. You can view things like a request and response in X-Ray. AWS X-Ray also generates a service graph that shows a visual of the entire path a call travels from the client all the way to the backend.

aws x-ray logo

AWS X-Ray service logo

How does AWS X-Ray work?

X-ray uses an SDK and a daemon/agent. To use X-Ray you'll need to integrate with the SDK and install the X-Ray agent then you're good to go. X-Ray will receive data from services in segments. It groups any common segments together into something called traces. Traces are then used to generate a service graph. A service graph shows a visual representation of your application.


A segment contains information about a resource's work done and the request. This includes information like the resource name, request details, the request method, URL, duration, and any errors. X-Ray gathers this information through headers, application code, and metadata. AWS gathers a lot of this data automatically. To get more in-depth information X-Ray allows annotations and metadata to enhance each trace. That's a more advanced concept so check out the documentation if that's of interest.

Every segment decomposes into a subsegment. X-Ray subsegments provide a fine-grained look at a request. Sometimes an AWS service won't support X-Ray tracing making the subsegment unavailable. When a subsegment isn't available X-Ray will try to use an inferred segment. An inferred segment allows you to see downstream services even if distributed tracing isn't supported by a particular service.


A trace tracks the path of a request through your application. A trace is a collection of all segments with a matching trace id. AWS adds a trace id in a header named X-Amzn-Trace-Id. As a request moves through the architecture X-Ray tracks the trace id along with other request data. The AWS X-Ray SDK will trace the first request each second and 5% of all subsequent requests, but, this sample rate is modifiable.

Service Map

Each AWS resource that sends data to X-Ray will appear in the service map. AWS uses the X-Ray data to create a JSON document called service graph which it then uses to build the service map. The lines that connect each node on the service map are called edges. To find out what services are in the application X-Ray uses a tracing header to track a request as it moves between services.

AWS X-Ray service map example

AWS X-Ray service map example

When do I use AWS X-Ray?

AWS X-Ray will be most helpful in a micro-service architecture. Micro-service architectures tend to be hard to visualize. X-Ray's service map can help provide a clear view of an otherwise murky architecture. Implementation of X-Ray only requires minor configuration updates to enable. The real limitations of X-Ray come down to language support and AWS services that support it.

X-Ray language support

  • C#
  • Golang
  • Java
  • Node.js
  • Python
  • Ruby


AWS X-Ray is an invaluable tool for micro-services. If you're working in a micro-service architecture and haven't enabled X-Ray give it a try. Enabling X-Ray is simple and the service map it provides is great if you're a visual learner. Like all AWS services, it's cheap to use. The cost model is 100,000 free traces recorded a month, 1 million traces retrieved or scanned free each month. If you exceed that the cost is .000005 cents per trace or $5 per million traces. If you liked this article check out my other articles on my tech blog or on my medium profile. Thanks for reading!