Instrumenting Your Application with AWS X-Ray

Architecture and Goal

The goal is to trace a web request as it travels through our application stack. The setup will be:

An Amazon EC2 instance running a simple Node.js (Express) application.
The AWS X-Ray Daemon running on the same EC2 instance to collect and forward trace data.
The AWS X-Ray SDK integrated into the Node.js application code to generate trace data.
An IAM Role attached to the EC2 instance granting permissions to send data to X-Ray.

Finally, we will view the trace data, including the service map, in the AWS X-Ray console.

Step 1: Create an IAM Role for EC2

Your EC2 instance needs permission to communicate with the AWS X-Ray service.

Navigate to the IAM console.
Go to Roles and click Create role.
For Trusted entity type, select AWS service.
For Use case, select EC2 and click Next.
In the Add permissions search box, type AWSXRayDaemonWriteAccess.
Check the box next to the policy and click Next.
Give the role a descriptive Role name (e.g., EC2-XRay-Access-Role).
Review the details and click Create role.

Step 2: Launch and Configure an EC2 Instance

Now, launch an EC2 instance that will run the X-Ray daemon and your Node.js application.

Navigate to the EC2 console and click Launch instances.
Give your instance a name (e.g., X-Ray-Demo-Server).
Select an Amazon Machine Image (AMI), such as Amazon Linux 2.
Choose an Instance type, like t2.micro (which is Free Tier eligible).
Create or select a Key pair to allow SSH access.
In Network settings, ensure that you have a security group that allows inbound traffic on:
- SSH (port 22) from your IP address for access.
- Custom TCP (port 8080) from anywhere, as this is where our sample app will run.
Expand the Advanced details section. For IAM instance profile, select the EC2-XRay-Access-Role you created in the previous step.

In the User data field, paste the following script. This script will install Node.js, Git, and the AWS X-Ray daemon when the instance launches.


#!/bin/bash

# Install Node.js and npm

yum update -y

yum install -y nodejs



# Install Git

yum install -y git



# Download and install the X-Ray Daemon

curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm -o /home/ec2-user/xray.rpm

yum install -y /home/ec2-user/xray.rpm

Click Launch instance.

Step 3: Deploy and Instrument the Node.js Application

Once the instance is running, connect to it via SSH to deploy and instrument the application.

SSH into your EC2 instance.

Clone a sample Node.js application:


git clone https://github.com/aws-samples/aws-xray-sdk-node-sample.git

cd aws-xray-sdk-node-sample

Install Application Dependencies and the X-Ray SDK: The package.json in this sample project already includes the aws-xray-sdk as a dependency.
```
npm install
```
Examine the Instrumented Code (index.js):

Open the main application file (index.js) to see how the X-Ray SDK is used. The key parts are:
- Importing the SDK:
```
const AWSXRay = require('aws-xray-sdk');
```
- Capturing AWS SDK calls: This automatically traces any calls made with the AWS SDK.
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
- Using Express middleware: These lines wrap your application's routes to trace incoming HTTP requests.
```
const app = express();

app.use(AWSXRay.express.openSegment('MyApp')); // Creates the main segment



// ... Your application routes go here ...



app.use(AWSXRay.express.closeSegment()); // Closes the segment
```

Step 4: Run the Application and Generate Trace Data

Start the X-Ray Daemon: The daemon listens on UDP port 2000 for data from the SDK.
```
# Run the daemon in the background

xray -o -b 0.0.0.0:2000 &
```
Start the Node.js Application:
```
node index.js
```
You should see the output Example app listening on port 8080!
Generate Traffic:

Open a new terminal (or use your local machine) and send a request to your application using the EC2 instance's public IP address.
```
curl http://YOUR_EC2_PUBLIC_IP:8080
```
Repeat this command several times to generate enough trace data.

Step 5: View the Traces in the AWS X-Ray Console

Navigate to the AWS X-Ray console.
On the left-hand menu, click on Service map. You should see a map with at least two nodes: one for the client and one for your application (MyApp). The nodes will be green if requests are successful.
Click on Traces. You will see a list of recent traces.
Click on a Trace ID to view the trace details. You will see a timeline showing the full duration of the request.
Examine the Segments in the timeline. You will see the main segment created by your Express app (MyApp) and potentially subsegments if your application were making downstream calls (e.g., to S3 or DynamoDB). You can click on each segment to see its metadata, annotations, and timing details.

Instrumenting Your Application with AWS X-Ray

📚 Recommended AWS Resources