Migration Guide

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 AppSignal for Node.js 3.x run the following command in your application's root directory.

npm

npm install @appsignal/nodejs

AppSignal Client

When upgrading from 2.x to 3.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";
// or: const { Appsignal } = require("@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.

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

• Apollo Server
• Express
• Koa.js
• Next.js

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

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

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

import express from "express";
// or: 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));

3.x

import { expressErrorHandler } from "@appsignal/nodejs";
// or: 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

import appsignalKoa from "@appsignal/koa";
// or: const appsignalKoa = require("@appsignal/koa");
appsignal.instrument(appsignalKoa);

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

import { getRequestHandler } from "@appsignal/nextjs";
// or: const { getRequestHandler } = require("@appsignal/nextjs");

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 npm uninstall, like in the example below.

npm uninstall @appsignal/express

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

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

AppSignal Integration Package Names

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";
// or: const { trace } = require("@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";
// or: const { setError, sendError } = require("@appsignal/nodejs");
 
setError(err);
 
sendError(err, () => {
  setTag("user_id", user_id);
});

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