Amazon API Gateway active tracing support for Amazon X-Ray - Amazon X-Ray
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).

Amazon API Gateway active tracing support for Amazon X-Ray

You can use X-Ray to trace and analyze user requests as they travel through your Amazon API Gateway APIs to the underlying services. API Gateway supports X-Ray tracing for all API Gateway endpoint types: Regional, edge-optimized, and private. You can use X-Ray with Amazon API Gateway in all Amazon Web Services Regions where X-Ray is available. For more information, see Trace API Gateway API Execution with Amazon X-Ray in the Amazon API Gateway Developer Guide.

Note

X-Ray only supports tracing for REST APIs through API Gateway.

Amazon API Gateway provides active tracing support for Amazon X-Ray. Enable active tracing on your API stages to sample incoming requests and send traces to X-Ray.

To enable active tracing on an API stage

  1. Open the API Gateway console at https://console.amazonaws.cn/apigateway/.

  2. Choose an API.

  3. Choose a stage.

  4. On the Logs/Tracing tab, choose Enable X-Ray Tracing and then choose Save Changes.

  5. Choose Resources in the left side navigation panel.

  6. To redeploy the API with the new settings, choose the Actions dropdown, and then choose Deploy API.

API Gateway uses sampling rules that you define in the X-Ray console to determine which requests to record. You can create rules that only apply to APIs, or that apply only to requests that contain certain headers. API Gateway records headers in attributes on the segment, along with details about the stage and request. For more information, see Configuring sampling rules.

Note

When tracing REST APIs with API Gateway HTTP integration, each segment's service name is set to the request URL path from API Gateway to your HTTP integration endpoint, resulting in a service node on the X-Ray trace map for each unique URL path. A large number of URL paths may cause the trace map to exceed the limit of 10,000 nodes, resulting in an error.

To minimize the number of service nodes created by API Gateway, consider passing parameters within the URL query string or in the request body via POST. Either approach will ensure parameters are not part of the URL path, which may result in fewer distinct URL paths and service nodes.

For all incoming requests, API Gateway adds a tracing header to incoming HTTP requests that don't already have one.

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
X-Ray trace ID format

An X-Ray trace_id consists of three numbers separated by hyphens. For example, 1-58406520-a006649127e371903a2de979. This includes:

  • The version number, which is 1.

  • The time of the original request in Unix epoch time using 8 hexadecimal digits.

    For example, 10:00AM December 1st, 2016 PST in epoch time is 1480615200 seconds or 58406520 in hexadecimal digits.

  • A globally unique 96-bit identifier for the trace in 24 hexadecimal digits.

If active tracing is disabled, the stage still records a segment if the request comes from a service that sampled the request and started a trace. For example, an instrumented web application can call an API Gateway API with an HTTP client. When you instrument an HTTP client with the X-Ray SDK, it adds a tracing header to the outgoing request that contains the sampling decision. API Gateway reads the tracing header and creates a segment for sampled requests.

If you use API Gateway to generate a Java SDK for your API, you can instrument the SDK client by adding a request handler with the client builder, in the same way that you would manually instrument an Amazon SDK client. See Tracing Amazon SDK calls with the X-Ray SDK for Java for instructions.