Tracing and Metrics with the AWS Distro for OpenTelemetry JavaScript Auto-Instrumentation

Introduction

The AWS Distro for OpenTelemetry (ADOT) JavaScript SDK supports automatic instrumentation for NodeJS applications. It automatically produces spans with telemetry data describing the values used by the NodeJS frameworks in your application without adding a single line of code. It is preconfigured for compatibility with AWS X-Ray and propagates the trace context across AWS services, and it can also be used with any other tracing backend.

In this guide, we walk through the steps needed to trace an application and produce metrics with auto-instrumentation.

Requirements

The current supported NodeJS versions to run an application using OpenTelemetry JavaScript are versions 18, 20, 22, and 24.

A collector is not required to send traces and logs to AWS; metrics still need the CloudWatch agent or a collector. ADOT JavaScript 0.7.0 and later can export traces and logs directly to the CloudWatch OTLP endpoints, or you can export through the CloudWatch agent or any OpenTelemetry Collector.

Installation

The easiest way to download the packages needed for auto-instrumentation is by using NPM:

Copy
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation

The @aws/aws-distro-opentelemetry-node-autoinstrumentation package provides a register script that configures the OpenTelemetry SDK with some basic defaults. This script is used for starting the Auto Instrumentation. The @opentelemetry/api, @opentelemetry/auto-instrumentations-node, @opentelemetry/core, @opentelemetry/sdk-node, and several other required @opentelemetry dependency packages are installed by default along with @aws/aws-distro-opentelemetry-node-autoinstrumentation. @opentelemetry/auto-instrumentations-node provides the library instrumentations from OpenTelemetry JS Contrib that each enables the instrumentation functionality of their respective libraries. The @opentelemetry/sdk-node library provides the functionality to configure, detect, install, and initialize all instrumentation packages supported for your application’s dependencies. Check out the OpenTelemetry registry for a full list of instrumentation packages provided by OpenTelemetry JavaScript.

Running an Application with Auto-Instrumentation

Auto-instrumentation uses a register script that is "required" when the NodeJS application is started. This script will automatically load instrumentations for NodeJS built-in modules and common packages.

The AWS Distro can be configured using the NODE_OPTIONS environment variable to run the register script.

Start your application using auto-instrumentation can be as simple as the following:

Copy
export NODE_OPTIONS="--require @aws/aws-distro-opentelemetry-node-autoinstrumentation/register"
node app.js

Alternatively, you can run:

Copy
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' app.js

Configuring Auto-Instrumentation

Note: Skip this part if you are onboarding with CloudWatch Application Signals.

Environment variables are the primary way in which the OpenTelemetry SDK for JavaScript is configured. For example:

• By default, @aws/aws-distro-opentelemetry-node-autoinstrumentation uses the OTLP exporter and is configured to send data to an OTLP endpoint, such as the CloudWatch agent or an OpenTelemetry collector, at http://localhost:4318 for both metrics and traces. To export directly to AWS without a collector, see Exporting to CloudWatch OTLP endpoints with ADOT SDKs.

• The random sampling rate for creating traces can be set through the environment variables OTEL_TRACES_SAMPLER=parentbased_traceidratio and OTEL_TRACES_SAMPLER_ARG=0.3 to configure a sampling rate of 30%. Sampling related configuration can be found in the OpenTelemetry general SDK configuration documentation.

More SDK configuration can be found in upstream opentelemetry SDK config public doc.

Using CloudWatch Application Signals

You can use CloudWatch Application Signals to automatically instrument your NodeJS applications on AWS using ADOT JavaScript auto-instrumentation so that you can monitor current application health and track long-term application performance against your business objectives. Application Signals provides you with a unified, application-centric view of your applications, services, and dependencies, and helps you monitor and triage application health.

Get started with CloudWatch Application Signals

Using X-Ray Remote Sampling

The ADOT JavaScript Auto-Instrumentation can be configured to use X-Ray remote sampling by setting the environment variable OTEL_TRACES_SAMPLER=xray. You will also need an agent or collector that proxies sampling requests to X-Ray, such as the CloudWatch agent or an OpenTelemetry collector configured for remote sampling, to allow the application to fetch sampling configuration.

You can further configure the Sampler by setting the OTEL_TRACES_SAMPLER_ARG environment variable. You can update the endpoint and the polling rate as follows:

Copy
OTEL_TRACES_SAMPLER_ARG=endpoint=<ENDPOINT>,polling_interval=<INTERVAL_IN_SECS>

By default the sampler sends requests to http://localhost:2000 and has a polling rate of 300 seconds. By setting OTEL_TRACES_SAMPLER_ARG environment variable you can change the endpoint the sampler talks with when getting sampling configuration from AWS X-Ray Console. For example setting OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:4000,polling_interval=60 would configure the sampler to communicate with http://localhost:4000 and poll the sampling rules every 60 seconds.

Using Manual Instrumentation

While the register script for ADOT JavaScript provides automatic instrumentation for popular frameworks, you might find the need to perform manual instrumentation in your application, for example, to provide custom data or to instrument code within the application itself.

To perform manual instrumentation alongside the automatic instrumentation, you will need to add @opentelemetry/api as a dependency. The version of this dependency is recommended to be the same version of the same dependency that is used by the ADOT JavaScript SDK.

To add the @opentelemetry/api dependency via NPM:

Copy
npm install @opentelemetry/api

For more detail on using the OpenTelemetry API, see the upstream OpenTelemetry JavaScript instrumentation documentation and the X-Ray guide to migrating to OpenTelemetry Node.js.

Sample Applications

• Simple Express.js Server Sample Application using ADOT JavaScript Auto-Instrumentation