> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide

<Note>
  🛟 Don't hesitate to [contact us](mailto:support@appsignal.com) if you run into
  any issues while upgrading your application's AppSignal for Node.js package.
  We're here to help!
</Note>

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](mailto:support@appsignal.com) for support.

## Installing 3.x

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

#### npm

<CodeGroup>
  ```bash Bash theme={null}
  npm install @appsignal/nodejs
  ```
</CodeGroup>

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

<CodeGroup>
  ```javascript Node.js theme={null}
  // appsignal.cjs

  const { Appsignal } = require("@appsignal/nodejs");

  const appsignal = new Appsignal({
    active: true,
    name: "Your app name",
  });
  ```
</CodeGroup>

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

<CodeGroup>
  ```json JSON theme={null}
  "scripts": {
    "server": "node --require ./appsignal.cjs index.js"
  }
  ```
</CodeGroup>

### 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](/metrics/custom#counter).

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { appsignal } from "./appsignal";
  // or: const appsignal = new Appsignal({...});

  const meter = appsignal.metrics();
  meter.incrementCounter("slow_queries", 1);
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Appsignal } from "@appsignal/nodejs";
  // or: const { Appsignal } = require("@appsignal/nodejs");

  const meter = Appsignal.client.metrics();
  meter.incrementCounter("slow_queries", 1);
  ```
</CodeGroup>

## Integrations

<Tip>
  Express and Next.js require an [Error
  Handler](/nodejs/3.x/integrations/express#error-handler).
</Tip>

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

<Warning>
  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.
</Warning>

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

<Tip>
  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.
</Tip>

* [Apollo Server](#remove-apollo-server-integration)
* [Express](#remove-express-integration)
* [Koa.js](#remove-koajs-integration)
* [Next.js](#remove-nextjs-integration)

**Don't forget to [remove/uninstall the AppSignal integration package](#remove-integration-package)**.

### Remove Apollo Server Integration

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```javascript Node.js theme={null}
  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)],
  });
  ```
</CodeGroup>

#### 3.x

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

[Read 3.x GraphQL Integration Documentation](/nodejs/3.x/integrations/graphql)

Once you've modified your integration code, you need to [remove the Apollo AppSignal package](#remove-apollo-server-integration) from your application.

### Remove Express Integration

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```javascript Node.js theme={null}
  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));
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript Node.js theme={null}
  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());
  ```
</CodeGroup>

[Read 3.x Express Integration Documentation](/nodejs/3.x/integrations/express)

Once you've modified your integration code, you need to [remove the Appsignal Express package](#remove-express-integration) from your application.

### Remove Koa.js Integration

<Warning>
  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.
</Warning>

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

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import appsignalKoa from "@appsignal/koa";
  // or: const appsignalKoa = require("@appsignal/koa");
  appsignal.instrument(appsignalKoa);
  ```
</CodeGroup>

#### 3.x

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

[Read 3.x Koa.js Integration Documentation](/nodejs/3.x/integrations/koajs)

Once you've modified your integration code, you need to [remove the Koa.js package](#remove-koajs-integration) from your application.

### Remove Next.js Integration

<Warning>
  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.
</Warning>

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

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { getRequestHandler } from "@appsignal/nextjs";
  // or: const { getRequestHandler } = require("@appsignal/nextjs");
  ```
</CodeGroup>

#### 3.x

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

[Read 3.x Next.js Integration Documentation](/nodejs/3.x/integrations/nextjs)

### 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 Bash theme={null}
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:

<CodeGroup>
  ```javascript Node.js theme={null}
  const tracer = appsignal.tracer();
  ```
</CodeGroup>

#### 3.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { trace } from "@opentelemetry/api";
  // or: const { trace } = require("@opentelemetry/api");

  const tracer = trace.getTracer("my-interesting-app");
  ```
</CodeGroup>

[Read more about tracers in the 3.x instrumentation documentation.](/nodejs/3.x/instrumentation/instrumentation)

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

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.withSpan(tracer.createSpan(), async (span) => {
    span.setName("your span's name");
    // logic to trace here
  });
  ```
</CodeGroup>

#### 3.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.startActiveSpan("your span's name", async (span) => {
    /// logic to trace here
    span.end();
  });
  ```
</CodeGroup>

[Read more about spans in the 3.x instrumentation documentation.](/nodejs/3.x/instrumentation/instrumentation)

### 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

<CodeGroup>
  ```javascript Node.js theme={null}
  const span = tracer.currentSpan();

  span.setCategory("query.sql");
  span.setSQL("SELECT * FROM users");
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript JavaScript theme={null}
  setCategory("query.sql");
  setSQL("SELECT * FROM users");
  ```
</CodeGroup>

[Read more about spans attribute helpers in the 3.x instrumentation documentation.](/nodejs/3.x/instrumentation/instrumentation#helpers)

## Exception Handling

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

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.setError(err);

  tracer.sendError(err, (span) => {
    span.setName("daily.task");
    span.set("user_id", user_id);
  });
  ```
</CodeGroup>

#### 3.x

In `sendError()`, [helpers](/nodejs/3.x/instrumentation/instrumentation#helpers) can be used to add additional data to the error span.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { setError, sendError } from "@appsignal/nodejs";
  // or: const { setError, sendError } = require("@appsignal/nodejs");

  setError(err);

  sendError(err, () => {
    setTag("user_id", user_id);
  });
  ```
</CodeGroup>

[Read more about exception handling in the 3.x exception handling documentation](/nodejs/3.x/instrumentation/exception-handling)