Skip to main content

AWS X-Ray Enablement Guide

This guide explains how to enable AWS X-Ray for common AWS services so Xshield can surface application trace visibility.

Lambda Functions​

Enable tracing via AWS Console​

  1. Open AWS Lambda in the AWS Console.
  2. Select the Lambda function you want to trace.
  3. Go to Configuration.
  4. Select Monitoring and operations tools.
  5. Under Additional monitoring tools, click Edit. Lambda tracing
  6. In AWS X-Ray, enable Lambda service traces. Lambda tracing
  7. Click Save.

Enable tracing via AWS CLI​

aws lambda update-function-configuration \
  --function-name <your-lambda-function-name> \
  --tracing-config Mode=Active

API Gateway (REST APIs)​

Enable tracing via AWS Console​

  1. Open API Gateway in the AWS Console.
  2. Select the REST API you want to trace.
  3. Go to Stages. API Gateway
  4. Under Logs and tracing, click Edit. API Gateway
  5. Enable X-Ray tracing.
  6. Click Save.

Enable tracing via AWS CLI​

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

Application Instrumentation (DynamoDB and S3)​

AWS X-Ray traces are generated by instrumenting your application (for example, a Lambda function or web service). When instrumented correctly, AWS SDK calls (including DynamoDB and S3 operations) are captured as downstream segments/subsegments.

DynamoDB​

Python​

Installation:

pip install aws-xray-sdk

Basic setup:

import boto3

from aws_xray_sdk.core import patch_all

patch_all()

dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
table = dynamodb.Table("your-table-name")


def lambda_handler(event, context):
    response = table.get_item(Key={"id": "123"})
    table.put_item(Item={"id": "456", "name": "example"})
    return response

Node.js​

Installation:

npm install aws-xray-sdk-core

Basic setup:

const AWSXRay = require("aws-xray-sdk-core");
const AWS = AWSXRay.captureAWS(require("aws-sdk"));

const dynamodb = new AWS.DynamoDB.DocumentClient();

exports.handler = async () => {
  const result = await dynamodb
    .get({
      TableName: "your-table-name",
      Key: { id: "123" },
    })
    .promise();

  await dynamodb
    .put({
      TableName: "your-table-name",
      Item: { id: "456", name: "example" },
    })
    .promise();

  return result;
};

Express example:

const AWSXRay = require("aws-xray-sdk-core");
const express = require("express");

const app = express();

app.use(AWSXRay.express.openSegment("MyApp"));

app.get("/api/data", (req, res) => {
  res.sendStatus(200);
});

app.use(AWSXRay.express.closeSegment());

Java​

Maven dependencies:

<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-xray-recorder-sdk-core</artifactId>
  <version>2.4.0</version>
</dependency>

<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  <version>2.4.0</version>
</dependency>

Basic setup:

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.handlers.TracingHandler;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;

public class MyApplication {
    private static final AmazonDynamoDB dynamoDB = AmazonDynamoDBClientBuilder
        .standard()
        .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
        .build();
}

S3​

Python​

import boto3

from aws_xray_sdk.core import patch_all

patch_all()

s3 = boto3.client("s3")


def lambda_handler(event, context):
    response = s3.list_buckets()
    s3.get_object(Bucket="my-bucket", Key="my-file.txt")
    s3.put_object(Bucket="my-bucket", Key="new-file.txt", Body="Hello World")
    s3.delete_object(Bucket="my-bucket", Key="old-file.txt")
    return response

Node.js​

const AWSXRay = require("aws-xray-sdk-core");
const AWS = AWSXRay.captureAWS(require("aws-sdk"));

const s3 = new AWS.S3();

exports.handler = async () => {
  const listResult = await s3
    .listObjectsV2({ Bucket: "my-bucket" })
    .promise();

  await s3
    .getObject({ Bucket: "my-bucket", Key: "my-file.txt" })
    .promise();

  await s3
    .putObject({ Bucket: "my-bucket", Key: "new-file.txt", Body: "Hello World" })
    .promise();

  return listResult;
};

Java​

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.handlers.TracingHandler;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;

public class S3Example {
    private static final AmazonS3 s3Client = AmazonS3ClientBuilder
        .standard()
        .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
        .build();
}

References​