Description

Ensure that every Amazon API Gateway REST API stage has AWS X-Ray active tracing enabled. With tracing enabled, API Gateway samples incoming requests and records traces that follow each request through the API and the services behind it.

Rationale

Without X-Ray tracing there is no end-to-end view of how requests move through the API and its backends. Timeouts, errors and unusual latency are harder to detect and diagnose, which delays incident response and root cause analysis and increases the risk of prolonged outages or unnoticed integration failures. Enabling tracing on all stages, with suitable sampling and correlation with logs and metrics, improves visibility and recovery time.

Impact

  • Provides end-to-end visibility of requests for troubleshooting and performance analysis

  • Helps detect errors and latency problems in the API and its integrations

  • X-Ray charges apply for recorded and retrieved traces beyond the free tier, depending on request volume and sampling rules

Default Value

X-Ray active tracing is disabled for new REST API stages.

Pre-Requisites

  • IAM permissions: apigateway:GET and apigateway:PATCH on the REST API stages

  • Optionally, X-Ray sampling rules suited to the request volume of the API

Remediation

Test Plan

Console:

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

  2. Open the API Gateway console and select a REST API.

  3. Select Stages and select a stage.

  4. In the Logs and tracing section, check whether X-Ray tracing is enabled.

  5. Repeat for each stage of each REST API in each region in use.

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

CLI:

List the REST APIs:

aws apigateway get-rest-apis --region <REGION> --query "items[].[id,name]" --output table

Show the tracing setting of each stage of an API:

aws apigateway get-stages --region <REGION> --rest-api-id <REST_API_ID> --query "item[].[stageName,tracingEnabled]" --output table

A stage fails if tracingEnabled is false or not set.

Implementation Steps

Console:

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

  2. Open the API Gateway console and select the REST API.

  3. Select Stages and select the affected stage.

  4. In the Logs and tracing section, choose Edit.

  5. Select X-Ray tracing.

  6. Choose Save changes.

  7. Repeat for each affected stage in each region in use.

CLI:

Enable X-Ray tracing for the stage:

aws apigateway update-stage --region <REGION> --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> --patch-operations op=replace,path=/tracingEnabled,value=true

Backout Plan

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

  2. Open the API Gateway console, select the REST API and select Stages.

  3. Select the stage and choose Edit in the Logs and tracing section.

  4. Clear X-Ray tracing and choose Save changes.

CLI:

aws apigateway update-stage --region <REGION> --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> --patch-operations op=replace,path=/tracingEnabled,value=false

Note: rolling back removes request tracing, which reduces visibility when investigating errors and performance problems.

Reference