API Gateway REST API Stage Has X-Ray Tracing Enabled

Overview

This check verifies that your API Gateway REST API stages have AWS X-Ray tracing enabled. X-Ray tracing helps you understand how your API is performing by capturing data about requests and responses as they flow through your system.

When enabled, X-Ray samples incoming requests and produces distributed traces that show the complete path of a request across all connected AWS services.

Risk

Without X-Ray tracing, you lose visibility into what happens when requests pass through your API Gateway and downstream services. This means:

• Slower troubleshooting: When something goes wrong, you cannot see where requests are failing or slowing down
• Missed issues: Timeouts, errors, and unusual latency patterns may go undetected
• Longer outages: Without clear visibility, it takes longer to identify and fix problems (higher Mean Time To Recovery)

Severity: Low

Remediation Steps

Prerequisites

You need permission to modify API Gateway stages. Specifically, you need the apigateway:UpdateStage permission.

AWS Console Method

1. Open the API Gateway console
2. Select your REST API from the list
3. Click Stages in the left navigation panel
4. Select the stage you want to update (e.g., prod, dev)
5. Click the Logs/Tracing tab
6. Under X-Ray Tracing, check the box to Enable X-Ray Tracing
7. Click Save Changes

Repeat these steps for each stage that needs tracing enabled.

AWS CLI Method

Use the update-stage command to enable X-Ray tracing on a specific stage:

aws apigateway update-stage \
    --rest-api-id <your-rest-api-id> \
    --stage-name <your-stage-name> \
    --patch-operations op=replace,path=/tracingEnabled,value=true \
    --region us-east-1

Finding your REST API ID:

aws apigateway get-rest-apis --region us-east-1 --query 'items[*].[id,name]' --output table

Listing stages for a REST API:

aws apigateway get-stages --rest-api-id <your-rest-api-id> --region us-east-1

Enable tracing on all stages of an API:

REST_API_ID="<your-rest-api-id>"

for STAGE in $(aws apigateway get-stages --rest-api-id "$REST_API_ID" --region us-east-1 --query 'item[*].stageName' --output text); do
    echo "Enabling X-Ray tracing on stage: $STAGE"
    aws apigateway update-stage \
        --rest-api-id "$REST_API_ID" \
        --stage-name "$STAGE" \
        --patch-operations op=replace,path=/tracingEnabled,value=true \
        --region us-east-1
done

CloudFormation

Use the TracingEnabled property on the AWS::ApiGateway::Stage resource:

AWSTemplateFormatVersion: '2010-09-09'
Description: Enable X-Ray tracing on API Gateway REST API stage

Parameters:
  RestApiId:
    Type: String
    Description: The ID of the REST API
  StageName:
    Type: String
    Description: The name of the stage
  DeploymentId:
    Type: String
    Description: The ID of the deployment

Resources:
  ApiGatewayStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      RestApiId: !Ref RestApiId
      StageName: !Ref StageName
      DeploymentId: !Ref DeploymentId
      TracingEnabled: true
      Description: API Gateway stage with X-Ray tracing enabled

Outputs:
  StageArn:
    Description: ARN of the API Gateway stage
    Value: !Sub 'arn:aws:apigateway:${AWS::Region}::/restapis/${RestApiId}/stages/${StageName}'

Key property:

• TracingEnabled: true - Enables X-Ray tracing for the stage

Terraform

Use the xray_tracing_enabled argument on the aws_api_gateway_stage resource:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

variable "rest_api_id" {
  description = "The ID of the REST API"
  type        = string
}

variable "deployment_id" {
  description = "The ID of the deployment"
  type        = string
}

variable "stage_name" {
  description = "The name of the stage"
  type        = string
  default     = "prod"
}

resource "aws_api_gateway_stage" "example" {
  rest_api_id   = var.rest_api_id
  deployment_id = var.deployment_id
  stage_name    = var.stage_name

  xray_tracing_enabled = true

  tags = {
    Environment = "production"
  }
}

output "stage_invoke_url" {
  description = "The invoke URL of the stage"
  value       = aws_api_gateway_stage.example.invoke_url
}

Key argument:

• xray_tracing_enabled = true - Enables X-Ray tracing for the stage

Verification

After enabling X-Ray tracing, verify the change was applied:

1. In the API Gateway console, select your stage and check the Logs/Tracing tab
2. Confirm that X-Ray Tracing shows as enabled
3. Make a test request to your API
4. Open the X-Ray console and look for traces from your API

CLI Verification

Check the tracing status for a specific stage:

aws apigateway get-stage \
    --rest-api-id <your-rest-api-id> \
    --stage-name <your-stage-name> \
    --region us-east-1 \
    --query 'tracingEnabled'

This should return true if tracing is enabled.

Re-run the Prowler check:

prowler aws --checks apigateway_restapi_tracing_enabled --region us-east-1

Additional Resources

• AWS X-Ray Developer Guide
• Tracing user requests to REST APIs using X-Ray
• AWS::ApiGateway::Stage CloudFormation Reference
• Terraform aws_api_gateway_stage Resource

Notes

• Sampling: X-Ray uses sampling to reduce overhead. Not every request will be traced. You can configure sampling rules in the X-Ray console to adjust the sample rate.
• Downstream services: For full end-to-end visibility, ensure X-Ray is also enabled on Lambda functions, ECS tasks, or other services that your API calls.
• Costs: X-Ray charges based on traces recorded and retrieved. Review the X-Ray pricing page to understand potential costs.
• Compliance frameworks: This check is mapped to KISA-ISMS-P and PCI compliance frameworks.