OpenTelemetry Node.js Integration (Beta)

The first release with OpenTelemetry support is @appsignal/nodejs package 2.4.0.

The AppSignal Node.js integration supports OpenTelemetry trace data. Our @appsignal/nodejs package ships with an OpenTelemetry processor that converts OpenTelemetry trace data to AppSignal trace data and sends it to AppSignal.

🔧 Setting up the MySQL integration? Please let us know if you're seeing unexpected results or have any feedback on this integration. We're here to help!

What is OpenTelemetry?

OpenTelemetry is an open-source project that facilitates the instrumentation of standardized telemetry data collection. This means that rather than every APM vendor building and maintaining their integrations, everyone can collaborate on the same base integrations to provide instrumentation for the benefit of everyone. OpenTelemetry currently supports several popular programming languages, including Node.js.

OpenTelemetry integrations consist of multiple components: tracing, metrics, and logs. These components are still a work in progress in most programming languages, with tracing for many languages being the most stable component. We support OpenTelemetry's tracing component in our Node.js integration to provide better error reporting and performance measurements.

Learn more about OpenTelemetry via the project's official website →

Supported Libraries

Our integration supports the following libraries from OpenTelemetry instrumentations:

Additional instructions for packages, if necessary, are listed in the instrumenting packages section.

Application Requirements

Currently, an app will need a working AppSignal integration for one of the following frameworks to create an AppSignal root span:

Express
Koa.js

Installation

Before continuing, make sure you have AppSignal installed on your application. You can follow our installation guide if you haven't already done this.

OpenTelemetry Integration

Configuring AppSignal

If AppSignal is configured correctly, your application will have an appsignal.js config file in the root or src directory. If no appsignal.js config file exists, create one and move the configuration code into it. Once completed, your configuration file should look like the example below.

// appsignal.js
const { Appsignal } = require("@appsignal/nodejs");
 
// Configure AppSignal
const appsignal = new Appsignal({
  active: true
  // AppSignal configurations already defined for your app
});
 
// Export the AppSignal client to use in other files
module.exports = { appsignal };

Ensure a required web framework integration is configured, like Express, like in the example below of an index.js file.

// index.js (Your filename may be different)
const { appsignal } = require("./appsignal");
 
// Add any other AppSignal instrumentation such as for Express
const express = require("express");
const { expressMiddleware } = require("@appsignal/express");
 
const app = express();
// Add this after any other express middleware, but before any routes
app.use(expressMiddleware(appsignal));

Installing OpenTelemetry Packages

To be able to use the OpenTelemetry integration, you will need to add OpenTelemetry to your app. You can do this by running one of the below commands for your app's package manager.

NPM

npm install @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node

Yarn

yarn add @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node

Configuring OpenTelemetry and AppSignal

Create a tracing.js file in your app's directory (either in the root or src directory, depending on your app's directory structure). In this tracing.js file, add the code example shown below. Make sure only to use the imports you need; see the code comments in the example below.

// tracing.js
// Require the AppSignal config
const { appsignal } = require("./appsignal");
// Require the AppSignal OpenTelemetry SpanProcessor
const { SpanProcessor } = require("@appsignal/nodejs");
 
// Require OpenTelemetry
const opentelemetry = require("@opentelemetry/sdk-node");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
 
// Import the necessary instrumentation
// This will be done in the next steps
 
// Configure OpenTelemetry to instrument specific libraries
const sdk = new opentelemetry.NodeSDK({
  // Configure the desired instrumentations here, as described in the next steps
  instrumentations: []
});
 
sdk.start()
 
const tracer = new NodeTracerProvider();
// Configure OpenTelemetry to use the AppSignal SpanProcessor.
// This will transform the OpenTelemetry trace data to AppSignal trace data.
tracer.addSpanProcessor(new SpanProcessor(appsignal));
tracer.register();

Updating `package.json` Scripts

The tracing.js file is required whenever your app starts. To ensure tracing is automatically loaded, open the package.json file and in the scripts section, add --require ./tracing.js property to a script that runs your node.js server (see example below), this ensures tracing is always loaded first in your app.

⚠️ Your application will currently require ./appsignal.js; you can replace this requirement with ./tracing.js. You do not need to require both files.

// package.json. Your app's package.json may have more content.
{
   "main": "index.js",
   "scripts": {
     "server": "node --require ./tracing.js index.js"
   }
   // ...
}

🎉 You've now configured your app to use AppSignal with OpenTelemetry! Next, you can add instrumentation for the libraries we support. When you've completed your configuration, restart your app to receive events from OpenTelemetry in AppSignal.

Instrumenting Packages

Need Help?

We're here to help! If you run into any issues or if any of the above is unclear, contact us at support@appsignal.com for help. Please explain your issue along with all the version numbers of packages you are using in your app.