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

# Guide de migration

<Note>
  🛟 N'hésitez pas à [nous contacter](mailto:support@appsignal.com) si vous
  rencontrez des problèmes lors de la mise à niveau du package AppSignal pour
  Node.js de votre application. Nous sommes là pour vous aider !
</Note>

Cette documentation liste les changements entre les versions 2.x et 3.x du package Node.js d'AppSignal.

Si vous effectuez une mise à niveau de 2.x vers 3.x, vous devrez modifier votre intégration pour qu'elle fonctionne correctement.

Si vous rencontrez des problèmes lors de la mise à niveau de votre application, n'hésitez pas à [nous contacter](mailto:support@appsignal.com) pour obtenir de l'aide.

## Installation de la 3.x

Pour installer AppSignal pour Node.js 3.x, exécutez la commande suivante dans le répertoire racine de votre application.

#### npm

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

## Client AppSignal

Lors de la mise à niveau de 2.x vers 3.x, vous devez modifier la manière dont votre application initialise et accède au client AppSignal.

### Initialiser le client AppSignal

Pour initialiser le client AppSignal et l'exporter, vous devrez créer un nouveau fichier `appsignal.cjs`, comme dans l'exemple ci-dessous :

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

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

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

Vous devrez requérir (`--require ./appsignal.cjs`) votre fichier `appsignal.cjs` au démarrage de votre application. Par exemple, dans le fichier `package.json` de votre application, comme dans l'exemple ci-dessous :

#### Javascript

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

### Accéder au client AppSignal

Dans la version 3.x, le client AppSignal est accessible depuis l'objet `Appsignal.client` exporté globalement. Les exemples ci-dessous montrent comment procéder dans le contexte d'un [compteur de métriques personnalisé](/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>

## Intégrations

<Tip>
  Express et Next.js nécessitent un [gestionnaire
  d'erreurs](/nodejs/3.x/integrations/express#error-handler).
</Tip>

AppSignal pour Node.js 3.x prend en charge toutes les intégrations 2.x de manière native. Cela signifie que les packages pour chaque intégration n'ont plus besoin d'être installés.

Lors du passage de la version 2.x à la 3.x, vous devrez supprimer tous les packages d'intégration AppSignal installés pour votre application.

### Désinstaller les intégrations

<Warning>
  Les intégrations 2.x ne sont pas compatibles avec l'intégration Node.js 3.x.
  Vous devez suivre les étapes de migration décrites ci-dessous pour utiliser
  les intégrations Node.js.
</Warning>

Pour profiter de la prise en charge native des intégrations d'AppSignal pour Node.js 3.x, vous devrez d'abord « annuler » les installations d'intégration qui étaient nécessaires dans la version 2.x.

#### Supprimer le code dépendant du package AppSignal

<Tip>
  Les exemples ci-dessous sont illustratifs et basés sur la documentation des
  intégrations 2.x et 3.x d'AppSignal. Le code de votre application peut
  différer des exemples de cette documentation.
</Tip>

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

**N'oubliez pas de [supprimer/désinstaller le package d'intégration AppSignal](#remove-integration-package)**.

### Supprimer l'intégration Apollo Server

<Warning>
  Le package `@appsignal/apollo-server` 2.x n'est pas compatible avec
  l'intégration Node.js 3.x. Vous devez suivre les étapes de migration décrites
  ci-dessous si vous souhaitez utiliser Apollo Server avec notre intégration
  3.x.
</Warning>

Supprimez l'initialisation 2.x du package et du plugin Appsignal Apollo Server de votre application, et remplacez-la par les instructions d'installation 3.x.

Votre application Apollo sera instrumentée automatiquement.

#### 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 est instrumenté automatiquement par le package AppSignal pour Node.js.

[Lire la documentation de l'intégration GraphQL 3.x](/nodejs/3.x/integrations/graphql)

Une fois que vous avez modifié votre code d'intégration, vous devez [supprimer le package AppSignal pour Apollo](#remove-apollo-server-integration) de votre application.

### Supprimer l'intégration Express

<Warning>
  Le package `@appsignal/express` 2.x n'est pas compatible avec l'intégration
  Node.js 3.x. Vous devez suivre les étapes de migration décrites ci-dessous si
  vous souhaitez utiliser express avec notre intégration 3.x.
</Warning>

Supprimez l'initialisation 2.x du package et du middleware AppSignal Express de votre application, et remplacez-la par les instructions d'installation 3.x.

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

[Lire la documentation de l'intégration Express 3.x](/nodejs/3.x/integrations/express)

Une fois que vous avez modifié votre code d'intégration, vous devez [supprimer le package AppSignal Express](#remove-express-integration) de votre application.

### Supprimer l'intégration Koa.js

<Warning>
  Le package `@appsignal/koa` 2.x n'est pas compatible avec l'intégration
  Node.js 3.x. Vous devez suivre les étapes de migration décrites ci-dessous si
  vous souhaitez utiliser Koa.js avec notre intégration 3.x.
</Warning>

Supprimez l'initialisation 2.x du package et de l'instrumentation AppSignal Koa de votre 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 est instrumenté automatiquement par le package AppSignal pour Node.js.

[Lire la documentation de l'intégration Koa.js 3.x](/nodejs/3.x/integrations/koajs)

Une fois que vous avez modifié votre code d'intégration, vous devez [supprimer le package Koa.js](#remove-koajs-integration) de votre application.

### Supprimer l'intégration Next.js

<Warning>
  Le package `@appsignal/nextjs` 2.x n'est pas compatible avec l'intégration
  Node.js 3.x. Vous devez suivre les étapes de migration décrites ci-dessous si
  vous souhaitez utiliser Next.js avec notre intégration 3.x.
</Warning>

La fonctionnalité « Web Vitals Reporting » a été dépréciée et n'est plus disponible dans AppSignal pour 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 est instrumenté automatiquement par le package AppSignal pour Node.js.

[Lire la documentation de l'intégration Next.js 3.x](/nodejs/3.x/integrations/nextjs)

### Supprimer le package d'intégration

Une fois les imports et le code dépendant de ces imports supprimés, vous devez désinstaller le package d'intégration.

Cela peut être fait en exécutant `npm uninstall`, comme dans l'exemple ci-dessous.

```bash Bash theme={null}
npm uninstall @appsignal/express
```

Les commandes `npm uninstall` supprimeront les dépendances de package et mettront à jour les fichiers `package.json` de votre application et `package-lock.json` de npm.

Remplacez `@appsignal/express` dans l'exemple ci-dessus par le nom du package d'intégration que vous supprimez.

#### Noms des packages d'intégration AppSignal

| Intégration   | Nom du package             |
| ------------- | -------------------------- |
| Apollo Server | `@appsignal/apollo-server` |
| Express       | `@appsignal/express`       |
| Koa.js        | `@appsignal/koa`           |
| Next.js       | `@appsignal/nextjs`        |

## L'objet Tracer

Il n'y a plus d'objet tracer AppSignal personnalisé. OpenTelemetry expose un fournisseur de tracer qui vous permet de créer de nouveaux 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>

[En savoir plus sur les tracers dans la documentation d'instrumentation 3.x.](/nodejs/3.x/instrumentation/instrumentation)

## Spans

Il n'y a plus d'objet span AppSignal personnalisé. Les fonctions de tracer d'AppSignal, telles que `rootSpan()`, `createSpan()`, `currentSpan()` et `withSpan()`, ne sont plus disponibles.

Les spans doivent être créés en appelant la méthode `startActiveSpan` sur un objet tracer. Les nouveaux spans sont automatiquement les enfants du span dans lequel ils ont été créés.

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

[En savoir plus sur les spans dans la documentation d'instrumentation 3.x.](/nodejs/3.x/instrumentation/instrumentation)

### Fonctions d'aide pour les attributs de span

Les fonctions d'aide utilisées pour définir les attributs de span ont également changé.

`setSQL` a été remplacé par `setBody`, `set` a été renommé `setTag`, et des fonctions d'aide supplémentaires ont été ajoutées. `setName` a été supprimé, car les spans doivent recevoir un nom au moment de leur création.

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

[En savoir plus sur les fonctions d'aide pour les attributs de span dans la documentation d'instrumentation 3.x.](/nodejs/3.x/instrumentation/instrumentation#helpers)

## Gestion des exceptions

Les objets tracer et span ne sont plus nécessaires lors de l'utilisation de `setError()` et `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

Dans `sendError()`, des [fonctions d'aide](/nodejs/3.x/instrumentation/instrumentation#helpers) peuvent être utilisées pour ajouter des données supplémentaires au span d'erreur.

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

[En savoir plus sur la gestion des exceptions dans la documentation 3.x sur la gestion des exceptions](/nodejs/3.x/instrumentation/exception-handling)