Description

Ensure that API Gateway REST API stages have AWS X-Ray tracing enabled, so that requests flowing through the API can be traced end-to-end across integrated services for performance analysis and troubleshooting.

Rationale

Without X-Ray tracing, diagnosing latency issues or failures that span API Gateway and downstream services (such as Lambda or other backend integrations) requires manually correlating logs across multiple services, which is slow and error-prone. Enabling X-Ray tracing provides a distributed trace of each request, showing time spent in each component, making it significantly easier to identify performance bottlenecks and the root cause of errors.

Impact

  • Provides end-to-end distributed tracing for requests through the API and its integrations

  • Improves the speed and accuracy of performance troubleshooting and root-cause analysis

  • Incurs additional cost based on the volume of traces recorded

Default Value

X-Ray tracing is disabled by default for a newly created API Gateway REST API stage.

Pre-Requisites

  • IAM permissions to update stage tracing settings (apigateway:PATCH)

  • Downstream services (e.g., Lambda) configured with X-Ray tracing/active instrumentation where end-to-end tracing is desired

Test Plan

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Navigate to API Gateway and select the REST API to review.

  3. Select Stages, then select the stage to review.

  4. Open the Logs/Tracing tab.

  5. Verify that Enable X-Ray Tracing is checked.

  6. If X-Ray tracing is disabled, follow the implementation steps.

Implementation Steps

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Navigate to API Gateway and select the REST API to update.

  3. Select Stages, then select the stage to update.

  4. Open the Logs/Tracing tab and select Edit.

  5. Check Enable X-Ray Tracing.

  6. Save the changes.

  7. Verify traces begin appearing in the AWS X-Ray console after subsequent API calls.

Backout Plan

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com.

  2. Navigate to API Gateway and select the REST API to update.

  3. Select Stages, then select the affected stage.

  4. Open the Logs/Tracing tab and select Edit.

  5. Uncheck Enable X-Ray Tracing.

  6. Save the changes.

Reference