Documentation navigation

OpenTelemetry Node.js integration Beta

The AppSignal Node.js integration has experimental support for OpenTelemetry trace data. Our @appsignal/nodejs package ships with an OpenTelemetry processor that can transform OpenTelemetry trace data into AppSignal trace data to send to AppSignal.com. This is our first step in supporting the OpenTelemetry ecosystem in AppSignal.

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

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

What is OpenTelemetry?

OpenTelemetry is a community project that aims to provide instrumentation for various languages and the libraries within their ecosystems. Rather than every APM vendor building and maintaining its own integrations, everyone can collaborate on the same base integrations to provide instrumentation. This makes the instrumentation better for everyone.

OpenTelemetry integrations consist of multiple components (tracing, metrics and logs) and are a work in progress for most languages. The tracing component is stable for a lot of languages. The tracing component is the first part we want to integrate with for our Node.js integration to provide error reporting and performance measurements.

Supported libraries

Our integration supports the following libraries from OpenTelemetry instrumentations:

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

Support for more packages will follow later.

Installation

At this time, an app will need an AppSignal integration for a web framework like Express, Koa.js or Apollo Server to create an AppSignal root span. Events tracked by OpenTelemetry will be added as child spans to this root span. Our OpenTelemetry integration only supports adding events to an existing AppSignal root span at this time. This will not be necessary in the future.

OpenTelemetry integration

Configuring AppSignal

First make sure to follow the installation guide to add AppSignal to an application. At this time the app should use a web framework like Express or Koa.js for the root integration.

You should have an appsignal.js config file in the app (either in the root or src/ directory depending on the app's directory structure). If you do not have a file specific for AppSignal config (const appsignal = new AppSignal(...)), move this code to a new appsignal.js file in the project.

1
2
3
4
5
6
7
8
9
10
11
// appsignal.js
const { Appsignal } = require("@appsignal/nodejs");

// Configure AppSignal
const appsignal = new Appsignal({
  active: true
  // Any other AppSignal config for the app
});

// Export the AppSignal client to use in other files
module.exports = { appsignal };

Require appsignal.js in the app at the top of the main app file. Make sure another integration for a web framework, like Express, is configured.

1
2
3
4
5
6
7
8
9
10
// app.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 the app. Add OpenTelemetry packages to the app by running the command below for the package manager the app uses.

1
2
3
# Use the command for the package manager the app uses
npm install @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node
yarn add @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node

Configuring OpenTelemetry and AppSignal

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// 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

In the app's package.json, update the way the app is started to require the tracing.js file on start. Update any script that starts the app in package.json to add --require ./tracing.js to it. This ensures the tracing is always loaded first in the app and a manual require of tracing.js is not always required.

1
2
3
4
5
6
7
8
// package.json. The app's package.json may have more content.
{
   "main": "app.js",
   "scripts": {
     "server": "node --require ./tracing.js app.js"
   }
   // ...
}

Now AppSignal and OpenTelemetry are integrated in the app and with each other. Add instrumentation for any packages in the next section. When you're done with the configuration, start the app to start receiving events from OpenTelemetry from the libraries we support.

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 the app.

We'd like to set cookies, read why.