Viewing traces and trace details - Amazon X-Ray
Viewing tracesExploring the trace timelineViewing segment detailsViewing subsegment details
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Viewing traces and trace details

Use the Traces page in the X-Ray console to find traces by URL, response code, or other data from the trace summary. After selecting a trace from the trace list, the Trace details page displays a map of service nodes involved in the selected trace, along with a timeline of trace segments.

Viewing traces

CloudWatch console
To view traces in the CloudWatch console

  1. Sign in to the Amazon Web Services Management Console and open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  2. Choose Traces under X-Ray traces in the left navigation pane. The Traces page allows you to filter by group, and optionally enter a filter expression to filter the traces displayed in the Traces section at the bottom of the page.

  3. Alternately, use the service map to navigate to a specific service node and then view traces, which will display the Traces page with a query already applied.

  4. Refine your query in the Query refiners section. You can choose an option from the Refine query by menu, to filter by Node, URL, and additional filters. A list of available filter values is displayed immediately below. Choose one or more entries and choose Add to query to add to the filter expression at the top of the page.

    Filter traces

  5. Type a trace ID directly into the query field to find a single trace. The trace ID can be entered in X-Ray format or in W3C format, such as a trace created using the Amazon Distro for OpenTelemetry. When querying traces created with a W3C-format trace ID, for example 4efaaf4d1e8720b39541901950019ee5, the console will display the matching trace in the X-Ray format, such as 1-4efaaf4d-1e8720b39541901950019ee5.

  6. Choose Run query at any time to display a list of matching traces within the Traces section at the bottom of the page.

  7. Choose a trace ID from the list to display the Trace details page for a single trace. A Trace map is displayed showing the nodes involved in the trace, along with a trace summary and a timeline of trace segments.

    Choose a trace ID to view the trace map and timeline for a trace

    The Trace details page displays a connected view of traces across event-driven applications that use Amazon SQS and Lambda. For more information, see tracing event-driven applications. The Traces and Trace details pages also support cross-account tracing, displaying traces from multiple accounts in the trace list and in a single trace map.

X-Ray console
To view traces in the X-Ray console

  1. Open the Traces page in the X-Ray console. You can also use the service map to navigate to a specific service node and then view traces, which will display the traces page with a filter expression already applied.

    Trace list in the X-Ray console for finding traces by URL, response code, or other data from the trace summary

  2. Choose a URL to filter the trace list.

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

    Choose a trace ID to view the trace map and timeline for a trace

Exploring the trace timeline

The Timeline section 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.

CloudWatch console
Timeline view of subsegments recorded by instrumented Amazon DynamoDB clients
X-Ray console
Timeline view of subsegments recorded by instrumented Amazon DynamoDB clients

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.

Raw data JSON document that contains all segments and subsegments that make up the trace

The X-Ray SDK records subsegments automatically when you use an instrumented Amazon 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.

Viewing segment details

From the trace timeline, choose the name of a segment to view its details. There are multiple tabs which display segment information.

Segment details window

  • The Overview tab shows information about the request and response.

  • The Resources tab for a segment shows information about the Amazon resources running your application and the X-Ray SDK. Use the Amazon EC2, Amazon 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 subsegment 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.

  • 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.

Overview information for a custom subsegment

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.

Record metadata on custom subsegments to 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.