Crawler Crawler

The Datadog AWS Lambda X-Ray integration is only supported on commercial AWS accounts. Without a commercial Lambda account, the Datadog AWS Lambda X-Ray integration is not supported on the Datadog for Government site.


AWS X-Ray lets developers trace distributed applications built using AWS products. This integration provides traces for Lambda functions in the Serverless function detail page. For more information about Serverless monitoring, refer to the dedicated documentation.



First, enable the AWS integration and ensure the following permissions are present in the policy document for your AWS/Datadog Role:


The GetTraceSummaries permission is used to get the list of recent traces. BatchGetTraces actually returns the full traces themselves.

Then, enable the X-Ray integration within Datadog.

If you are using a Customer Master Key to encrypt traces, add the kms:Decrypt method to your policy where the Resource is the Customer Master Key used for X-Ray.

Note: Enabling the AWS X-Ray integration increases the amount of Indexed Spans which can impact your bill.

Enabling AWS X-Ray for your functions

To get the most out of the AWS X-Ray integration, you’ll need to enable it on your Lambda functions and API Gateways, and install the tracing libraries in your Lambda functions.

Serverless framework plugin

The Datadog Serverless Framework plugin automatically enables X-Ray for your Lambda functions and API Gateway instances. The plugin also automatically adds the Datadog Lambda Layer to all of your Node and Python functions.

Get started with the Serverless Framework plugin and read the docs.

Lastly, install and import the X-Ray client library in your Lambda function.

Manual setup

  1. Navigate to the Lambda function in the AWS console you want to instrument. In the “Debugging and error handling” section, check the box to Enable active tracing. This turns on X-Ray for that function.
  2. Navigate to the API Gateway console. Select your API and then the stage. Then on the Logs/Tracing tab, select Enable X-Ray Tracing. To make these changes take effect, go to Resources in the left navigation panel and select Actions. Then, click Deploy API.

Note: The Datadog Lambda Layer and client libraries include the X-Ray SDK as a dependency, so you don’t need to explicitly install it in your projects.

Lastly, install and import the X-Ray client library in your Lambda function.

Installing the X-Ray client libraries

The X-Ray client library offers insights into your HTTP requests to APIs and into calls to DynamoDB, S3, MySQL and PostgreSQL (self-hosted, Amazon RDS, and Amazon Aurora), SQS, and SNS.

Install the library, import it into your Lambda projects, and patch the services you wish to instrument.

Install the X-Ray tracing library:

npm install aws-xray-sdk

# for Yarn users
yarn add aws-xray-sdk

To instrument the AWS SDK:

var AWSXRay = require('aws-xray-sdk-core');
var AWS = AWSXRay.captureAWS(require('aws-sdk'));

To instrument all downstream HTTP and HTTPS calls:

var AWSXRay = require('aws-xray-sdk');
var http = require('http');

To instrument PostgreSQL queries:

var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();

To instrument MySQL queries:

var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
var connection = mysql.createConnection(config);

To capture subsegments within chained native Promise:


To capture all outgoing Axios requests:

const AWSXRay = require('aws-xray-sdk');


const AxiosWithXray = require('axios');

For further configuration, creating subsegments, and recording annotations, consult the X-Ray Node.js docs.

Install the X-Ray tracing library:

pip install aws-xray-sdk

To patch all libraries by default, add the following to the file containing your Lambda handlers:

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

Note that tracing aiohttp requires specific instrumentation.

For further configuration, creating subsegments, and recording annotations, consult the X-Ray Python docs.

Data Collected

The AWS X-Ray integration pulls in trace data from AWS, and does not collect any metrics or logs.