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!

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

shell
npm install --save @appsignal/nodejs

yarn

shell
yarn add @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:

javascript
// 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

json
// 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

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

3.x

javascript
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.

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

javascript
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

javascript
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

javascript
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

javascript
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

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

shell
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:

javascript
const tracer = appsignal.tracer();

3.x:

javascript
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:

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

3.x:

javascript
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

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

3.x

javascript
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

javascript
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.

javascript
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