OpenTelemetry using Node.js

This guide demonstrates how to configure OpenTelemetry in a Node.js app to send telemetry data to Axiom.

OpenTelemetry provides a unified approach to collecting telemetry data from your Node.js and TypeScript apps. This guide demonstrates how to configure OpenTelemetry in a Node.js app to send telemetry data to Axiom using OpenTelemetry SDK.

Prerequisites

To configure OpenTelemetry in a Node.js app for sending telemetry data to Axiom, certain prerequisites are necessary. These include:

• Node:js: Node.js version 14 or newer.
• Node.js app: Use your own app written in Node.js, or you can start with the provided app.ts sample.
• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to create, read, update, and delete datasets.

Core Application (app.ts)

app.ts is the core of the app. It uses Express.js to create a simple web server. The server has an endpoint /rolldice that returns a random number, simulating a basic API. It also demonstrates the usage of span links to establish relationships between spans across different traces.

/*app.ts*/

// Importing OpenTelemetry instrumentation for tracing
import './instrumentation'; 
import { trace, context } from '@opentelemetry/api';

// Importing Express.js: A minimal and flexible Node.js web app framework
import express from 'express';

// Setting up the server port: Use the PORT environment variable or default to 8080
const PORT = parseInt(process.env.PORT || '8080');
const app = express();

// Get the tracer from the global tracer provider
const tracer = trace.getTracer('node-traces');

/**
 * Function to generate a random number between min and max (inclusive).
 * @param min - The minimum number (inclusive).
 * @param max - The maximum number (exclusive).
 * @returns A random number between min and max.
 */
function getRandomNumber(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min) + min);
}

// Defining a route handler for '/rolldice' that returns a random dice roll
app.get('/rolldice', (req, res) => {
  const span = trace.getSpan(context.active());
  /**
   * Spans can be created with zero or more Links to other Spans that are related.
   * Links allow creating connections between different traces 
   */
  const rollDiceSpan = tracer.startSpan('roll_dice_span', {
    links: span ? [{ context: span.spanContext() }] : [],
  });
  
  // Set the rollDiceSpan as the currently active span
  context.with(trace.setSpan(context.active(), rollDiceSpan), () => {
    const diceRoll = getRandomNumber(1, 6).toString();
    res.send(diceRoll);
    rollDiceSpan.end();
  });
});

// Defining a route handler for '/roll_with_link' that creates a parent span and calls '/rolldice'
app.get('/roll_with_link', (req, res) => {
  /**
   * A common scenario is to correlate one or more traces with the current span.
   * This can help in tracing and debugging complex interactions across different parts of the app.
   */
  const parentSpan = tracer.startSpan('parent_span');
  
  // Set the parentSpan as the currently active span
  context.with(trace.setSpan(context.active(), parentSpan), () => {
    const diceRoll = getRandomNumber(1, 6).toString();
    res.send(`Dice roll result (with link): ${diceRoll}`);
    parentSpan.end();
  });
});

// Starting the server on the specified PORT and logging the listening message
app.listen(PORT, () => {
  console.log(`Listening for requests on http://localhost:${PORT}`);
});

Exporter (instrumentation.ts)

instrumentation.ts sets up the OpenTelemetry instrumentation. It configures the OTLP (OpenTelemetry Protocol) exporters for traces and initializes the Node SDK with automatic instrumentation capabilities.

/*instrumentation.ts*/

// Importing necessary OpenTelemetry packages including the core SDK, auto-instrumentations, OTLP trace exporter, and batch span processor
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

// Initialize OTLP trace exporter with the endpoint URL and headers
const traceExporter = new OTLPTraceExporter({
  url: 'https://api.axiom.co/v1/traces',
  headers: {
    'Authorization': 'Bearer $API_TOKEN',
    'X-Axiom-Dataset': '$DATASET'
  },
});

// Creating a resource to identify your service in traces
const resource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: 'node traces', 
});

// Configuring the OpenTelemetry Node SDK
const sdk = new NodeSDK({
  // Adding a BatchSpanProcessor to batch and send traces
  spanProcessor: new BatchSpanProcessor(traceExporter),

  // Registering the resource to the SDK
  resource: resource,

  // Adding auto-instrumentations to automatically collect trace data
  instrumentations: [getNodeAutoInstrumentations()],
});

// Starting the OpenTelemetry SDK to begin collecting telemetry data
sdk.start();

Installing the Dependencies

Navigate to the root directory of your project and run the following command to install the required dependencies:

npm install

This command will install all the necessary packages listed in your package.json below

Setting Up TypeScript Development Environment

To run the TypeScript app, you need to set up a TypeScript development environment. This includes adding a package.json file to manage your project’s dependencies and scripts, and a tsconfig.json file to manage TypeScript compiler options.

Add package.json

Create a package.json file in the root of your project with the following content:

{
    "name": "typescript-traces",
    "version": "1.0.0",
    "description": "",
    "main": "app.js",
    "scripts": {
        "build": "tsc",
        "start": "ts-node app.ts",
        "dev": "ts-node-dev --respawn app.ts"
    },
    "keywords": [],
    "author": "",
    "license": "ISC",
    "dependencies": {
        "@opentelemetry/api": "^1.6.0",
        "@opentelemetry/api-logs": "^0.46.0",
        "@opentelemetry/auto-instrumentations-node": "^0.39.4",
        "@opentelemetry/exporter-metrics-otlp-http": "^0.45.0",
        "@opentelemetry/exporter-metrics-otlp-proto": "^0.45.1",
        "@opentelemetry/exporter-trace-otlp-http": "^0.45.0",
        "@opentelemetry/sdk-logs": "^0.46.0",
        "@opentelemetry/sdk-metrics": "^1.20.0",
        "@opentelemetry/sdk-node": "^0.45.1",
        "express": "^4.18.2"
    },
    "devDependencies": {
        "@types/express": "^4.17.21",
        "@types/node": "^16.18.71",
        "ts-node": "^10.9.2",
        "ts-node-dev": "^2.0.0",
        "tsc-watch": "^4.6.2",
        "typescript": "^4.9.5"
    }
}

Add tsconfig.json

Create a tsconfig.json file in the root of your project with the following content:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

This configuration file specifies how the TypeScript compiler should transpile TypeScript files into JavaScript.

Running the Instrumented Application

To run your Node.js app with OpenTelemetry instrumentation, make sure your API token, and dataset is set in the instrumentation.ts file.

In Development Mode

For development purposes, especially when you need automatic restarts upon file changes, use:

npm run dev

This command will start the OpenTelemetry instrumentation in development mode using ts-node-dev. It sets up the exporter for tracing and restarts the server automatically whenever you make changes to the files.

In Production Mode

To run the app in production mode, you need to first build the TypeScript files into JavaScript. Run the following command to build your application:

npm run build

This command compiles the TypeScript files to JavaScript based on the settings specified in tsconfig.json. Once the build process is complete, you can start your app in production mode with:

npm start

The server will start on the specified port, and you can interact with it by sending requests to the /rolldice endpoint.

Observe the telemetry data in Axiom

As you interact with your app, traces will be collected and exported to Axiom, where you can monitor and analyze your app’s performance and behavior.

Observing the telemetry data in Axiom

Dynamic OpenTelemetry traces dashboard

This data can then be further viewed and analyzed in Axiom’s dashboard, providing insights into the performance and behaviour of your app.

Dynamic OpenTelemetry traces dashboard

Send data from an existing Node project

Manual Instrumentation

Manual instrumentation in Node.js requires adding code to create and manage spans around the code blocks you want to trace.

1. Initialize Tracer:

Import and configure a tracer in your Node.js app. Use the tracer configured in your instrumentation setup (instrumentation.ts).

// Assuming OpenTelemetry SDK is already configured
const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('example-tracer');

2. Create Spans:

Wrap the code blocks that you want to trace with spans. Start and end these spans within your code.

const span = tracer.startSpan('operation_name');
try {
  // Your code here
  span.end();
} catch (error) {
  span.recordException(error);
  span.end();
}

3. Annotate Spans:

Add metadata and logs to your spans for the trace data.

span.setAttribute('key', 'value');
span.addEvent('event name', { eventKey: 'eventValue' });

Automatic Instrumentation

Automatic instrumentation in Node.js simplifies adding telemetry data to your app. It uses pre-built libraries to automatically instrument common frameworks and libraries.

1. Install Instrumentation Libraries:

Use OpenTelemetry packages that automatically instrument common Node.js frameworks and libraries.

npm install @opentelemetry/auto-instrumentations-node

2. Instrument Application: Configure your app to use these libraries, which will automatically generate spans for standard operations.

// In your instrumentation setup (instrumentation.ts)
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  // ... other configurations ...
  instrumentations: [getNodeAutoInstrumentations()]
});

After you set them up, these libraries automatically trace relevant operations without additional code changes in your app.

Reference

List of OpenTelemetry trace fields

Field Category	Field Name	Description
Unique Identifiers
	_rowid	Unique identifier for each row in the trace data.
	span_id	Unique identifier for the span within the trace.
	trace_id	Unique identifier for the entire trace.
Timestamps
	_systime	System timestamp when the trace data was recorded.
	_time	Timestamp when the actual event being traced occurred.
HTTP Attributes
	attributes.custom[“http.host”]	Host information where the HTTP request was sent.
	attributes.custom[“http.server_name”]	Server name for the HTTP request.
	attributes.http.flavor	HTTP protocol version used.
	attributes.http.method	HTTP method used for the request.
	attributes.http.route	Route accessed during the HTTP request.
	attributes.http.scheme	Protocol scheme (HTTP/HTTPS).
	attributes.http.status_code	HTTP response status code.
	attributes.http.target	Specific target of the HTTP request.
	attributes.http.user_agent	User agent string of the client.
Network Attributes
	attributes.net.host.port	Port number on the host receiving the request.
	attributes.net.peer.port	Port number on the peer (client) side.
	attributes.custom[“net.peer.ip”]	IP address of the peer in the network interaction.
Operational Details
	duration	Time taken for the operation.
	kind	Type of span (for example,, server, client).
	name	Name of the span.
	scope	Instrumentation scope.
	service.name	Name of the service generating the trace.
Resource Process Attributes
	resource.process.command	Command line string used to start the process.
	resource.process.command_args	List of command line arguments used in starting the process.
	resource.process.executable.name	Name of the executable running the process.
	resource.process.executable.path	Path to the executable running the process.
	resource.process.owner	Owner of the process.
	resource.process.pid	Process ID.
	resource.process.runtime.description	Description of the runtime environment.
	resource.process.runtime.name	Name of the runtime environment.
	resource.process.runtime.version	Version of the runtime environment.
Telemetry SDK Attributes
	telemetry.sdk.language	Language of the telemetry SDK.
	telemetry.sdk.name	Name of the telemetry SDK.
	telemetry.sdk.version	Version of the telemetry SDK.

List of imported libraries

The instrumentation.ts file imports the following libraries:

@opentelemetry/sdk-node

This package is the core SDK for OpenTelemetry in Node.js. It provides the primary interface for configuring and initializing OpenTelemetry in a Node.js app. It includes functionalities for managing traces and context propagation. The SDK is designed to be extensible, allowing for custom configurations and integration with different telemetry backends like Axiom.

@opentelemetry/auto-instrumentations-node

This package offers automatic instrumentation for Node.js apps. It simplifies the process of instrumenting various common Node.js libraries and frameworks. By using this package, developers can automatically collect telemetry data (such as traces) from their apps without needing to manually instrument each library or API call. This is important for apps with complex dependencies, as it ensures comprehensive and consistent telemetry collection across the app.

@opentelemetry/exporter-trace-otlp-proto

The @opentelemetry/exporter-trace-otlp-proto package provides an exporter that sends trace data using the OpenTelemetry Protocol (OTLP). OTLP is the standard protocol for transmitting telemetry data in the OpenTelemetry ecosystem. This exporter allows Node.js apps to send their collected traces to any backend that supports OTLP, such as Axiom. The use of OTLP ensures broad compatibility and a standardized way of transmitting telemetry data.

@opentelemetry/sdk-trace-base

Contained within this package is the BatchSpanProcessor, among other foundational elements for tracing in OpenTelemetry. The BatchSpanProcessor is a component that collects and processes spans (individual units of trace data). As the name suggests, it batches these spans before sending them to the configured exporter (in this case, the OTLPTraceExporter). This batching mechanism is efficient as it reduces the number of outbound requests by aggregating multiple spans into fewer batches. It helps in the performance and scalability of trace data export in an OpenTelemetry-instrumented app.