AWS Documentation » AWS X-Ray » Developer Guide » AWS X-Ray Console

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.

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 traces page of 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.

The document that you see in the console doesn't represent the data as it was sent to X-Ray by your application. Instead, it represents the processed documents generated by the X-Ray services. X-Ray creates the full trace document by compiling segment documents sent by your application, and creating inferred segments for downstream calls to services that don't send segments themselves. X-Ray also removes data that doesn't comply with the segment document schema.

For example, when you call DynamoDB with an instrumented client, the X-Ray SDK records a subsegment with details about the call from its point of view. However, DynamoDB doesn't send a corresponding segment. X-Ray uses the information in the subsegment to create an inferred segment to represent the DynamoDB resource in the service map, and adds it to the trace document.

Viewing Segment Details

From the trace timeline, choose the name of a segment to view its details. The Overview 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 provided by the SDK.

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 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 subsegment showing details about the DynamoDB table, operation called, and request ID.

For custom subsegments, the Overview 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, simply 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.