AWS X-Ray

AWS X-Ray

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.

Overview

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, see Serverless monitoring.

Setup

Installation

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

xray:BatchGetTraces,
xray:GetTraceSummaries

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 (CMK) to encrypt traces, add the kms:Decrypt method to your policy where the Resource is the CMK 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, 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.

Enriching X-Ray segments with Datadog’s Lambda libraries (optional)

Note: This functionality is limited to AWS Lambda functions written in Node.js or Python runtimes.

Datadog’s Lambda Libraries enrich X-Ray segments with additional metadata, which is made available in both APM traces and the Serverless View. To instrument your Lambda functions with the Datadog Lambda Libraries, consult detailed instructions by runtime and deployment tool or the following custom installation instructions:

Python Lambda functions

  • Import the Datadog Lambda Library as a layer or package. See detailed instructions.
  • Set your function’s handler to datadog_lambda.handler.handler.
  • Set the environment variable DD_LAMBDA_HANDLER to your original handler, for example, myfunc.handler.
  • (Optional) Unless you are using trace merging, set the environment variable DD_TRACE_ENABLED to false.

Node Lambda functions

  • Import the Datadog Lambda Library as a layer or package. See detailed instructions.
  • Set your function’s handler to /opt/nodejs/node_modules/datadog-lambda-js/handler.handler if using the layer, or node_modules/datadog-lambda-js/dist/handler.handler if using the package.
  • Set the environment variable DD_LAMBDA_HANDLER to your original handler, for example, myfunc.handler.
  • (Optional) Unless you are using trace merging, set the environment variable DD_TRACE_ENABLED to false.

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');
AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.captureHTTPsGlobal(require('https'));
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:

AWSXRay.capturePromise();

To capture all outgoing Axios requests:

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

AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.capturePromise();

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
patch_all()

Note: 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.