Migration Guide

🛟 Don't hesitate to contact us if you run into any issues while upgrading your application's AppSignal for Node.js package. We're here to help!

⚠️ Our 2.x integration is deprecated, but 2.x documentation is still available here.

This documentation lists the changes between the 2.x and 3.x releases of AppSignal's Node.js package.

If you are upgrading from 2.x to 3.x you will need to modify your integration to work successfully.

If you run into any issues while upgrading your application, be sure to contact us for support.

Installing 3.x

To install AppsSignal for Node.js 3.x run the following command in your application's root directory.

npm

npm install --save @appsignal/nodejs

yarn

yarn add @appsignal/nodejs

AppSignal Client

When upgrading to 3.x from 2.x, you need to change how your application initializes and accesses the AppSignal client.

Initialize AppSignal Client

To initialize the AppSignal client and export it, you will need to create a new appsignal.cjs file, like in the example below:

// appsignal.cjs
 
const { Appsignal } = require("@appsignal/nodejs");
 
const appsignal = new Appsignal({
  active: true,
  name: "Your app name",
});

You will need to require (--require ./appsignal.cjs) your appsignal.cjs file when starting your application. For example, in your application's package.json file, like in the example below:

Javascript

// package.json
 
"scripts": {
  "server": "node --require ./appsignal.cjs index.js"
}

Access AppSignal Client

In 3.x the AppSignal client is accessed from the globally exported Appsignal.client object. The below examples show how to do this within the context of a custom metrics counter.

2.x

import { appsignal } from "./appsignal";
// or: const appsignal = new Appsignal({...});
 
const meter = appsignal.metrics();
meter.incrementCounter("slow_queries", 1);

3.x

import { Appsignal } from "@appsignal/nodejs";
 
const meter = Appsignal.client.metrics();
meter.incrementCounter("slow_queries", 1);

Integrations

AppSignal for Node.js 3.x supports all 2.x integrations out of the box. This means the packages for each integration no longer need to be installed.

When moving to 3.x from 2.x you will need to remove any AppSignal integration packages installed for your application.

⚠️ Express and Next.js require an Error Handler.

Uninstall Integrations

To take advantage of the AppSignal for Node.js 3.x out-of-the-box integration support, you'll first need to "undo" the integration installations that were necessary in the 2.x version.

Remove AppSignal Package Dependent Code

The examples below are illustrative and based on AppSignal's 2.x and 3.x integration documentation. The code in your application may differ from the examples in this documentation.

Don't forget to remove/uninstall the AppSignal integration package.

Remove Apollo Server Integration

Remove the 2.x initialization of the Appsignal Apollo Server package and plugin from your application, and replace it with the 3.x installation instructions.

Your Apollo application will be instrumented automatically.

2.x

const { createApolloPlugin } = require("@appsignal/apollo-server");
const { ApolloServer, gql } = require("apollo-server-express");
 
const server = new ApolloServer({
  /* ... */
  plugins: [createApolloPlugin(appsignal)],
});

Read 2.x Apollo Integration Documentation

3.x

Apollo Server is instrumented automatically by the AppSignal for Node.js package.

Read 3.x GraphQL Integration Documentation

Once you've modified your integration code, you need to remove the Apollo AppSignal package from your application.

Remove Express Integration

Remove the 2.x initialization of AppSignal Express package and middleware from your application, and replace it with the 3.x installation instructions.

2.x

const express = require("express");
 
const {
  expressMiddleware,
  expressErrorHandler,
} = require("@appsignal/express");
// your app code goes here
 
// add this after all other express middleware, but before any routes
app.use(expressMiddleware(appsignal));
 
// add this after all routes, but before any other error handlers
app.use(expressErrorHandler(appsignal));

Read 2.x Express Integration Documentation

3.x

const { expressErrorHandler } = require("@appsignal/nodejs");
 
const app = express();
// your app code goes here
 
// add this after all routes, but before any other error handlers
app.use(expressErrorHandler());

Read 3.x Express Integration Documentation

Once you've modified your integration code, you need to remove the Appsignal Express package from your application.

Remove Koa.js Integration

Remove the 2.x initialization of the Appsignal Koa package and instrumentation from your application.

2.x

appsignal.instrument(require("@appsignal/koa"));

Read 2.x Koa.js Integration Documentation

3.x

Koa.js is instrumented automatically by the AppSignal for Node.js package.

Read 3.x Koa.js Integration Documentation

Once you've modified your integration code, you need to remove the Koa.js package from your application.

Remove Next.js Integration

The "Web Vitals Reporting" feature has been deprecated and is no longer available on AppSignal for Node.js 3.x.

2.x

const { getRequestHandler } = require("@appsignal/nextjs");

Read 2.x Next.js Integration Documentation

3.x

Next.js is instrumented automatically by the AppSignal for Node.js package.

Read 3.x Next.js Integration Documentation

Remove Integration Package

Once the imports and code dependent on those imports are removed, you need to uninstall the integration package.

This can be done by running yarn remove / npm uninstall, like in the example below.

yarn remove @appsignal/express
npm uninstall @appsignal/express

The yarn remove / npm uninstall commands will remove package dependencies and update your application's package.json and npm's package-lock.json, or yarn's yarn.lock file.

Replace @appsignal/express in the example above with the integration package name you are removing.

AppSignal Integration Package Names

IntegrationPackage Name
Apollo Server@appsignal/apollo-server
Express@appsignal/express
Koa.js@appsignal/koa
Next.js@appsignal/nextjs

The Tracer Object

There's no longer a custom AppSignal tracer object. OpenTelemetry exposes a tracer provider which allows you to create new spans.

2.x:

const tracer = appsignal.tracer();

3.x:

import { trace } from "@opentelemetry/api";
 
const tracer = trace.getTracer("my-interesting-app");

Read more about tracers in the 3.x instrumentation documentation.

Spans

There's no longer a custom AppSignal span object. AppSignal's tracer functions, such as rootSpan(), createSpan(), currentSpan() and withSpan() functions are no longer available.

Spans must be created by calling the startActiveSpan method on a tracer object. New spans are automatically the children of the span they were created in.

2.x:

tracer.withSpan(tracer.createSpan(), async (span) => {
  span.setName("your span's name");
  // logic to trace here
});

3.x:

tracer.startActiveSpan("your span's name", async (span) => {
  /// logic to trace here
  span.end();
});

Read more about spans in the 3.x instrumentation documentation.

Span Attribute Helpers

The helper functions used to set span attributes have also changed.

setSQL has been replaced with setBody, set has been renamed to setTag, and additional helper functions have been added. setName has been removed, as spans must be given a name when they are created.

2.x

const span = tracer.currentSpan();
 
span.setCategory("query.sql");
span.setSQL("SELECT * FROM users");

3.x

setCategory("query.sql");
setSQL("SELECT * FROM users");

Read more about spans attribute helpers in the 3.x instrumentation documentation.

Exception Handling

Tracer and span objects are no longer needed when using setError() and sendError().

2.x

tracer.setError(err);
 
tracer.sendError(err, (span) => {
  span.setName("daily.task");
  span.set("user_id", user_id);
});

3.x

In sendError(), helpers can be used to add additional data to the error span.

import { setError, sendError } from "@appsignal/nodejs";
 
setError(err);
 
sendError(err, () => {
  setTag("user_id", user_id);
});

Read more about exception handling in the 3.x exception handling documentation

Need more help?

Contact us and speak directly with the engineers working on AppSignal. They will help you get set up, tweak your code and make sure you get the most out of using AppSignal.

Contact us

Start a trial - 30 days free

AppSignal is a great way to monitor your Ruby, Elixir & Node.js applications. Works great with Rails, Phoenix, Express and other frameworks, with support for background jobs too. Let's improve your apps together.

Start a trial