aws-xray-sdk

What is aws-xray-sdk?

The aws-xray-sdk is an npm package that provides tools for integrating AWS X-Ray tracing into your Node.js applications. AWS X-Ray helps developers analyze and debug distributed applications, such as those built using a microservices architecture. The SDK allows you to trace requests as they travel through your application, providing insights into performance bottlenecks and errors.

What are aws-xray-sdk's main functionalities?

Automatic Instrumentation

This feature allows you to automatically capture HTTP and HTTPS requests made by your application. The SDK wraps the native HTTP and HTTPS modules to capture and record data about outgoing requests.

const AWSXRay = require('aws-xray-sdk');
const http = AWSXRay.captureHTTPs(require('http'));
const https = AWSXRay.captureHTTPs(require('https'));

http.get('http://www.example.com', (res) => {
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

Manual Instrumentation

This feature allows you to manually create and manage subsegments within your code. You can add annotations and metadata to these subsegments to provide additional context for your traces.

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

AWSXRay.captureFunc('annotations', function(subsegment) {
  subsegment.addAnnotation('userId', '12345');
  subsegment.addMetadata('key', 'value');
});

Middleware Integration

This feature allows you to integrate AWS X-Ray with popular web frameworks like Express. The SDK provides middleware that automatically creates and closes segments for incoming HTTP requests.

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

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

app.get('/', function (req, res) {
  res.send('Hello World!');
});

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

app.listen(3000);

Other packages similar to aws-xray-sdk

jaeger-client

Jaeger is an open-source end-to-end distributed tracing tool originally developed by Uber Technologies. The jaeger-client npm package allows you to instrument your Node.js applications to send trace data to a Jaeger backend. Unlike aws-xray-sdk, Jaeger is designed to work with the Jaeger tracing system and provides more flexibility in terms of deployment and configuration.

README

Requirements

• AWS SDK v2.7.15 or greater (if using captureAWS or captureAWSClient)
• Express 4.14.0 or greater (if using Express and the associated X-Ray middleware)
• MySQL 2.12.0 or greater (if using captureMySQL)
• Postgres 6.1.0 or greater (if using capturePostgres)

AWS X-Ray

The AWS X-Ray SDK automatically records information for incoming and outgoing requests and responses (via middleware), as well as local data such as function calls, time, variables (via metadata and annotations), even EC2 instance data (via plugins).

Although the AWS X-Ray SDK was originally intended to capture request/response data on a web app, the SDK provides functionality for use cases outside this as well. The SDK exposes the 'Segment' and 'Subsegment' objects to create your own capturing mechanisms, middleware, etc.

This package includes the following AWS X-Ray packages.

aws-xray-sdk-core
aws-xray-sdk-express
aws-xray-sdk-postgres
aws-xray-sdk-mysql

Setup

The core package contains the base SDK functionality. Please see the aws-xray-sdk-core README.md for more details.

Support for web frameworks

• Express
• Restify