Migration Guide - AppSignal Documentation

🛟 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!

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

"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

Express and Next.js require an Error Handler.

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

The 2.x integrations are not compatible with the 3.x Node.js integration. You must follow the migration steps outlined below to use Node.js 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.

Apollo Server
Express
Koa.js
Next.js

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

Remove Apollo Server Integration

The 2.x @appsignal/apollo-server package is not compatible with the 3.x Node.js integration. You must follow the migration steps outlined below if you wish to use Apollo Server with our 3.x 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

The 2.x @appsignal/express package is not compatible with the 3.x Node.js integration. You must follow the migration steps outlined below if you wish to use express with our 3.x 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

The 2.x @appsignal/koa package is not compatible with the 3.x Node.js integration. You must follow the migration steps outlined below if you wish to use Koa.js with our 3.x 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 2.x @appsignal/nextjs package is not compatible with the 3.x Node.js integration. You must follow the migration steps outlined below if you wish to use Next.js with our 3.x 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.

Bash

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

Integration	Package 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";
// or: const { trace } = require("@opentelemetry/api");

const tracer = trace.getTracer("my-interesting-app");

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();
});

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");

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);
});

​Installing 3.x

​npm

​AppSignal Client

​Initialize AppSignal Client

​Javascript

​Access AppSignal Client

​2.x

​3.x

​Integrations

​Uninstall Integrations

​Remove AppSignal Package Dependent Code

​Remove Apollo Server Integration

​2.x

​3.x

​Remove Express Integration

​2.x

​3.x

​Remove Koa.js Integration

​2.x

​3.x

​Remove Next.js Integration

​2.x

​3.x

​Remove Integration Package

​AppSignal Integration Package Names

​The Tracer Object

​2.x:

​3.x:

​Spans

​2.x:

​3.x:

​Span Attribute Helpers

​2.x

​3.x

​Exception Handling

​2.x

​3.x

Installing 3.x

npm

AppSignal Client

Initialize AppSignal Client

Javascript

Access AppSignal Client

2.x

3.x

Integrations

Uninstall Integrations

Remove AppSignal Package Dependent Code

Remove Apollo Server Integration

2.x

3.x

Remove Express Integration

2.x

3.x

Remove Koa.js Integration

2.x

3.x

Remove Next.js Integration

2.x

3.x

Remove Integration Package

AppSignal Integration Package Names

The Tracer Object

2.x:

3.x:

Spans

2.x:

3.x:

Span Attribute Helpers

2.x

3.x

Exception Handling

2.x

3.x