AWS X-Ray console

The AWS X-Ray console enables you to view service maps and traces for requests that your applications serve.

The console's service map is a visual representation of the JSON service graph that X-Ray generates from the trace data generated by your applications.

The map consists of service nodes for each application in your account that serves requests, upstream client nodes that represent the origins of the requests, and downstream service nodes that represent web services and resources used by an application while processing a request.

You can use filters to view a service map or traces for a specific request, service, connection between two services (an edge), or requests that satisfy a condition. X-Ray provides a filter expression language for filtering requests, services, and edges based on data in request headers, response status, and indexed fields on the original segments.

Viewing the service map

View the service map in the X-Ray console to identify services where errors are occurring, connections with high latency, or traces for requests that were unsuccessful.

To view the service map

1. Open the service map page of the X-Ray console.

   

2. Choose a service node to view requests for that node, or an edge between two nodes to view requests that traveled that connection.

3. Use the histogram to filter traces by duration, and select status codes for which you want to view traces. Then choose View traces to open the trace list with the filter expression applied.

   

The service map indicates the health of each node by coloring it based on the ratio of successful calls to errors and faults:

• Green for successful calls

• Red for server faults (500 series errors)

• Yellow for client errors (400 series errors)

• Purple for throttling errors (429 Too Many Requests)

In the center of each node, the console shows the average response time and number of traces that it sent per minute during the chosen time range.

If your service map is large, the console defaults to a zoomed out view. Use the on-screen controls or mouse to zoom in and out and move the image around.

Controls

• – Zoom in or out. You can also use the mouse wheel to zoom in or out.

• – Scroll the service map. Click and drag to scroll by using the mouse.

• – Frame the selected node or edge in the center of map.

Viewing the service map by group

Using a filter expression, you can define criteria by which to accept traces into a group. Use the following steps to then display that specific group in the service map.

To view a group service map

1. Open the service map page of the X-Ray console.

2. Choose a group name from the dropdown menu to the left of the search bar.

   

Changing the node presentation

Use the following options to change the way your service map is presented. You can toggle on service icons to better follow the stream of services, and you can change the weights of your nodes to better represent traffic or health.

To change the node presentation

1. Open the service map page of the X-Ray console, or an individual trace map.

   Node options are in the bottom right of the map.

2. Choose a presentation for your node.

   Service Icons enabled

   Service Icons – When enabled, shows an icon for the AWS service respresented by the node, instead of the default summary of activity.

   

   Node weight by None

   None – No node resizing, all nodes are of the same weight.

   

   Node weight by Health

   Health – The node size is calculated by the total number of impacted requests. Impacted requests include fault, error, and throttle. For example, a node with 10% total impacted requests out of 1000 sampled (100 requests impacted) has a larger node size than a node with only 50% total impacted requests out of 100 sampled (50 requests impacted).

   

   Node weight by Traffic

   Traffic – The node size is calculated by the total number of sampled requests. For example, a node with 1000 sampled requests has a larger node size than one with 100 sampled requests.

   

Viewing traces

Use the trace list in the X-Ray console to find traces by URL, response code, or other data from the trace summary.

To use the trace list

1. Open the Trace overview in the X-Ray console.

   

2. Choose a URL to filter the trace list.

3. Choose a trace ID to view the timeline for a trace.

   

The Timeline view shows a hierarchy of segments and subsegments. The first entry in the list is the segment, which represents all data recorded by the service for a single request.

Below the segment are subsegments. This example shows subsegments recorded by instrumented Amazon DynamoDB clients, and a custom subsegment.

The X-Ray SDK records subsegments automatically when you use an instrumented AWS SDK, HTTP, or SQL client to make calls to external resources. You can also tell the SDK to record custom subsegments for any function or block of code. Additional subsegments recorded while a custom subsegment is open become children of the custom subsegment.

From the Timeline view, you can also access the raw trace data that the console uses to generate the timeline. Choose Raw data to see the JSON document that contains all the segments and subsegments that make up the trace.

Viewing the trace map

Use the trace map to visually map the end-to-end path of a single request.

To view a trace map

1. Open the Trace overview in the X-Ray console.

2. Choose a URL to filter the trace list.

3. Choose a trace ID to view the timeline for a trace. The trace map is displayed above the trace timeline.

Viewing segment details

From the trace timeline, choose the name of a segment to view its details. The Overview tab shows information about the request and response.

The Resources tab for a segment shows information about the AWS resources running your application and the X-Ray SDK. Use the Amazon EC2, AWS Elastic Beanstalk, or Amazon ECS plugin for the SDK to record service-specific resource information.

The remaining tabs show Annotations, Metadata, and Exceptions recorded on the segment. Exceptions are captured automatically when thrown from an instrumented request. Annotations and metadata contain additional information that you record by using the methods that the SDK provides.

Viewing subsegment details

From the trace timeline, choose the name of a segment to view its details. For subsegments generated with instrumented clients, the Overview tab contains information about the request and response from your application's point of view. This example shows a subsegment from an instrumented call to DynamoDB.

The Resources tab for a subsegment shows details about the DynamoDB table, operation called, and request ID.

For custom subsegments, the Overview tab shows the name of the subsegment, which you can set to specify the area of the code or function that it records.

Use custom subsegments to organize subsegments from instrumented clients into groups. You can also record metadata and annotations on subsegments, which can help you debug functions.

In this example, the application records the state of each Game object that it saves to DynamoDB. It does this by passing the object into the putMetadata method on the subsegment. The X-Ray SDK serializes the object into JSON and adds it to the segment document.