Enable AWS X-Ray
Prerequisite: Install the AWS integration.
- Ensure the following permissions are present in the policy document for your AWS/Datadog Role:
xray:BatchGetTraces,
xray:GetTraceSummaries
The `BatchGetTraces` permission is used to return the full traces. The `GetTraceSummaries` permission is used to get a list of summaries of recent traces.
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 consumed Indexed Spans which can increase your bill.
Enabling AWS X-Ray for your functions
To get the most out of the AWS X-Ray integration:
- Enable it on your Lambda functions and API Gateways, either using the Serverless Framework plugin or manually; and
- Install the tracing libraries in your Lambda functions.
[Recommended] Datadog 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.js 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
If you do not use the Serverless Framework to deploy your serverless application, follow these instructions for manual setup:
- 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.
- Navigate to the API Gateway console. Select your API and then the stage.
- 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 and 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 calls:
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
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);
For further configuration, creating subsegments, and recording annotations, see the X-Ray Node.js docs.
Install the X-Ray tracing library:
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
patch_all()
Note that tracing aiohttp requires specific instrumentation.
For further configuration, creating subsegments, and recording annotations, see the X-Ray Python docs.
