AWS X-Ray in a nutshell (illustrated)

3 min readMar 11, 2022


If you are a bit confused with the AWS X-Ray service, here is a visual explanation on how AWS X-Ray works.

Quick service description

AWS X-Ray is a distributed tracing tool.

It helps you analyze and debug production, distributed applications which is handy in the case of microservices architectures (where lots of microservices need to communicate together over https).

By using AWS X-Ray you can get a neat “service map” to troubleshoot and understand the path of the request, the response codes for each microservice, the average response time, etc …

Example of “Service Map”: it seems my API gateway gave some 4xx responses 😮

One thing worth noting is that X-Ray integrates with some AWS services (API Gateway, Lambda, …) but you can also use X-Ray in you application code (Node.js, etc …).

I can select “Metrics” instead of “Icons” so I can view the avg response time

Let’s go in the “Traces” section of X-Ray:

Selecting Traces section

Here I can access the “traces”:

The response code is what the client got as a response to its request to the entry point of the app

If I click on the first one (status OK 200), I’ll get the “segments” making up this “trace” and the details for each segment (quite useful to troubleshoot).

You can also use the X-Ray SDK to create subsegments (take a look, I’ve created a “Wait 1 second” subsegment inside the code of my Lambda before making HTTP call to an external API:

Segments of a Trace

Here is what the code inside my Node.js Lambda function looks like to create the sub-segment:

Node.js code to create a subsegment (by using the current thread segment provided by the SDK)

How does it work ?

Here are 2 illustrations that might help you to understand how AWS X-Ray works:

How AWS X-Ray could work on your own “micro-service node” (Node.js webserver for instance)
How AWS X-Ray knows that segments belong to the same trace ? By passing the trace ID to outgoing requests

The end

I hope this story helped you




This is my personal blog where I post (in my spare time) computer science “cheatsheets”. I mainly do it for myself but it may benefit others.