Datadog APM can create synthetic root spans for requests that pass through Amazon API Gateway to container- or EC2-hosted services. The spans power end-to-end traces, service maps, and sampling based on the gateway itself.

Prerequisites

• Amazon API Gateway is deployed as a REST API (v1) or HTTP API (v2).

  Note: If using HTTP API (v2), context.requestTimeEpoch provides second-level granularity, unlike REST APIs (v1) which provide millisecond precision. This means span duration is approximate.

• DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED is set in the application container:

  Copy

    export DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED=true
    

  Or enable it through the Datadog ECS Fargate CDK construct:

  Copy

    new DatadogECSFargate(this, 'Datadog', {
      apm: { isEnabled: true, traceInferredProxyServices: true },
    });
    
  

• Your underlying application is running a supported web framework.

• Your application tracer meets the minimum version.

Supported versions and web frameworks

Setup

To create inferred spans, API Gateway must pass the following headers to your backend services:

Header	Value
x-dd-proxy	'aws-apigateway' Note: Single quotes must be included.
x-dd-proxy-request-time-ms	context.requestTimeEpoch
x-dd-proxy-domain-name	context.domainName
x-dd-proxy-httpmethod	context.httpMethod
x-dd-proxy-path	context.path
x-dd-proxy-stage	context.stage

To pass in the required headers, you can use the AWS CDK or AWS Console:

AWS CDK

Add the headers under requestParameters and use $context variables:

const resource = api.root.addResource('myresource');
 resource.addMethod('ANY', new apigateway.Integration({
   # other configurations
   options: {
     # other options
     requestParameters: {
       "integration.request.header.x-dd-proxy": "'aws-apigateway'",
       "integration.request.header.x-dd-proxy-request-time-ms": "context.requestTimeEpoch",
       "integration.request.header.x-dd-proxy-domain-name": "context.domainName",
       "integration.request.header.x-dd-proxy-httpmethod": "context.httpMethod",
       "integration.request.header.x-dd-proxy-path": "context.path",
       "integration.request.header.x-dd-proxy-stage": "context.stage",
     }
   }
 })
 # other settings here
 });

AWS Console

1. In the AWS Management Console, navigate to API Gateway and go to your API’s Resources page.

2. Go to Integration request and click Edit.

3. Under Edit integration request, go to URL request headers parameters. Click Add request header parameter.

To create inferred spans, API Gateway must pass the following headers to your backend services:

Header	Value
x-dd-proxy	aws-apigateway
x-dd-proxy-request-time-ms	${context.requestTimeEpoch}000
x-dd-proxy-domain-name	$context.domainName
x-dd-proxy-httpmethod	$context.httpMethod
x-dd-proxy-path	$context.path
x-dd-proxy-stage	$context.stage

Note: context.requestTimeEpoch returns a timestamp in seconds in v2 APIs. Datadog expects milliseconds, so you must multiply it by 1000 by appending 000.

Attach the parameter mapping that injects the headers:

Copy

   import { DatadogAPIGatewayV2ParameterMapping }
     from 'datadog-cdk-constructs-v2';

   const ddIntegration = new apigatewayv2_integrations.HttpUrlIntegration(
     'HttpUrlIntegration',
     'https://example.com',
     { parameterMapping: DatadogAPIGatewayV2ParameterMapping },
   );

   new apigatewayv2.HttpApi(this, 'HttpApi', {
     apiName: 'my-http-api',
     routes: [{
       path: '/{proxy+}',
       methods: [apigatewayv2.HttpMethod.ANY],
       integration: ddIntegration,
     }],
   });

Update sampling rules

Head-based sampling still applies when using API Gateway tracing. Because the synthetic span becomes the new trace root, update your rules so the service value matches the API Gateway service name shown in Datadog.

For example, if the original sampling rule is:

# before: sampled upstream service
DD_TRACE_SAMPLING_RULES='[{"service":"pythonapp","sample_rate":0.5}]'

Update the rule in one of the following ways:

1. Change the service value to match your API Gateway’s name as it appears in Datadog:

   Copy

      # option 1: sample the gateway root span
      DD_TRACE_SAMPLING_RULES='[{"service":"my-api-gateway","sample_rate":0.5}]'
      

2. Remove the service key to apply the rule to all root spans:

   Copy

      # option 2: apply to all roots
      DD_TRACE_SAMPLING_RULES='[{"sample_rate":0.5}]'
      

Further Reading

Additional helpful documentation, links, and articles:

Tutorial - Enabling Tracing for a Go Application on Amazon ECS with FargateDOCUMENTATION Amazon ECS on AWS FargateDOCUMENTATION Amazon EKS on AWS FargateDOCUMENTATION