Guide de migration - AppSignal Documentation

🛟 N’hésitez pas à nous contacter 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 !

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

npm install @appsignal/nodejs

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 :

// appsignal.cjs

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

const appsignal = new Appsignal({
  active: true,
  name: "Your app name",
});

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

"scripts": {
  "server": "node --require ./appsignal.cjs index.js"
}

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

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

Intégrations

Express et Next.js nécessitent un gestionnaire d’erreurs.

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

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.

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

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.

Apollo Server
Express
Koa.js
Next.js

N’oubliez pas de supprimer/désinstaller le package d’intégration AppSignal.

Supprimer l’intégration Apollo Server

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.

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

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 est instrumenté automatiquement par le package AppSignal pour Node.js. Lire la documentation de l’intégration GraphQL 3.x Une fois que vous avez modifié votre code d’intégration, vous devez supprimer le package AppSignal pour Apollo de votre application.

Supprimer l’intégration Express

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.

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

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

Lire la documentation de l’intégration Express 3.x Une fois que vous avez modifié votre code d’intégration, vous devez supprimer le package AppSignal Express de votre application.

Supprimer l’intégration Koa.js

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.

Supprimez l’initialisation 2.x du package et de l’instrumentation AppSignal Koa de votre application.

2.x

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

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 Une fois que vous avez modifié votre code d’intégration, vous devez supprimer le package Koa.js de votre application.

Supprimer l’intégration Next.js

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.

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

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

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

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

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 :

const tracer = appsignal.tracer();

3.x :

import { trace } from "@opentelemetry/api";
// or: const { trace } = require("@opentelemetry/api");

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

En savoir plus sur les tracers dans la documentation d’instrumentation 3.x.

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 :

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

En savoir plus sur les spans dans la documentation d’instrumentation 3.x.

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

const span = tracer.currentSpan();

span.setCategory("query.sql");
span.setSQL("SELECT * FROM users");

3.x

setCategory("query.sql");
setSQL("SELECT * FROM users");

En savoir plus sur les fonctions d’aide pour les attributs de span dans la documentation d’instrumentation 3.x.

Gestion des exceptions

Les objets tracer et span ne sont plus nécessaires lors de l’utilisation de setError() et sendError().

2.x

tracer.setError(err);

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

3.x

Dans sendError(), des fonctions d’aide peuvent être utilisées pour ajouter des données supplémentaires au span d’erreur.

import { setError, sendError } from "@appsignal/nodejs";
// or: const { setError, sendError } = require("@appsignal/nodejs");

setError(err);

sendError(err, () => {
  setTag("user_id", user_id);
});

En savoir plus sur la gestion des exceptions dans la documentation 3.x sur la gestion des exceptions

​Installation de la 3.x

​npm

​Client AppSignal

​Initialiser le client AppSignal

​Javascript

​Accéder au client AppSignal

​2.x

​3.x

​Intégrations

​Désinstaller les intégrations

​Supprimer le code dépendant du package AppSignal

​Supprimer l’intégration Apollo Server

​2.x

​3.x

​Supprimer l’intégration Express

​2.x

​3.x

​Supprimer l’intégration Koa.js

​2.x

​3.x

​Supprimer l’intégration Next.js

​2.x

​3.x

​Supprimer le package d’intégration

​Noms des packages d’intégration AppSignal

​L’objet Tracer

​2.x :

​3.x :

​Spans

​2.x :

​3.x :

​Fonctions d’aide pour les attributs de span

​2.x

​3.x

​Gestion des exceptions

​2.x

​3.x

Installation de la 3.x

npm

Client AppSignal

Initialiser le client AppSignal

Javascript

Accéder au client AppSignal

2.x

3.x

Intégrations

Désinstaller les intégrations

Supprimer le code dépendant du package AppSignal

Supprimer l’intégration Apollo Server

2.x

3.x

Supprimer l’intégration Express

2.x

3.x

Supprimer l’intégration Koa.js

2.x

3.x

Supprimer l’intégration Next.js

2.x

3.x

Supprimer le package d’intégration

Noms des packages d’intégration AppSignal

L’objet Tracer

2.x :

3.x :

Spans

2.x :

3.x :

Fonctions d’aide pour les attributs de span

2.x

3.x

Gestion des exceptions

2.x

3.x