Send OpenTelemetry data from a TypeScript app to Axiom

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

Prerequisites

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

• Node:js: Node.js version 14 or newer.
• Node.js Application: Use your own application written in Node.js, or you can start with the provided app.ts sample.
• Axiom API Key: Obtain an Axiom API Key with ingesting and querying permissions from your Access Settings. If you don’t have an Axiom account, sign up for a free account at Axiom.
• Dataset: You will need a dataset to which traces will be sent. You can create one from the Data Settings.

Core Application (app.ts)

app.ts is the core of the application. 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.

/*app.ts*/

// Importing OpenTelemetry instrumentation for tracing
import './instrumentation'; 

// Importing Express.js: A minimal and flexible Node.js web application 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();

/**
 * 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) => {
  res.send(getRandomNumber(1, 6).toString());
});

// 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 application, 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 application 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 application 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 application 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 application, traces will be collected and exported to Axiom, where you can monitor and analyze your application’s performance and behavior.

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 application.

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 application. 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 application. 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 application 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

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 application. 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 applications. 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 applications without needing to manually instrument each library or API call. This is important for applications with complex dependencies, as it ensures comprehensive and consistent telemetry collection across the application.

@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 applications 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 application.