Migrer depuis AppSignal pour JavaScript

Browser monitoring est une fonctionnalité en beta d’AppSignal Labs. Le package @appsignal/browser est publié sous le tag beta sur npm, et sa configuration ainsi que son API peuvent encore changer d’une release beta à l’autre. Partagez vos retours dans notre communauté Discord.

@appsignal/browser remplace @appsignal/javascript, ses intégrations de frameworks et ses packages de plugins. Ce guide fait correspondre l’ancienne API à la nouvelle. Le nouveau SDK collecte les breadcrumbs et les web vitals après init() et rapporte les erreurs dans les vues Browser. Migrez quand vous êtes prêt à adopter sa nouvelle API, et passez en revue les changements ci-dessous.

Ce qui change

Un package au lieu de plusieurs. Error tracking, breadcrumbs et web vitals sont tous dans @appsignal/browser. Le nouveau SDK n’a plus de packages de plugins ou de frameworks correspondants. Certaines fonctionnalités sont intégrées ; d’autres demandent du code applicatif. Des fonctions au lieu d’une instance. Il n’y a pas d’objet client à créer, à faire circuler ou à passer à un composant. Vous appelez init() une fois et importez les fonctions dont vous avez besoin, là où vous en avez besoin. Les erreurs non interceptées sont rapportées sans qu’on le demande. @appsignal/plugin-window-events existait parce qu’il fallait les activer explicitement. Elles sont actives par défaut désormais. Le SDK écarte les erreurs opaques de scripts cross-origin. Utilisez beforeError pour filtrer les autres bruits de navigateur ou d’extension. Les erreurs sont rapportées dans le namespace browser. @appsignal/javascript rapportait dans frontend, et il n’y a plus d’option namespace. Les nouvelles erreurs apparaissent dans la section Browser. Les erreurs frontend existantes restent dans leur liste actuelle. Les incidents existants du namespace frontend restent où ils sont.

Les réglages de notification se configurent par namespace : ceux que vous avez définis pour frontend ne s’appliquent donc pas à browser. Configurez-les de nouveau après la migration, sinon les erreurs front-end arriveront sans notifier personne.

Vos incidents frontend existants conservent leurs assignations, leurs états et leurs niveaux de gravité. Le nouveau package rapporte dans le namespace browser. Ses nouvelles issues démarrent sans assignation, comme toute autre nouvelle issue. Plus de spans, de décorateurs ni de surcharges. Le nouveau SDK n’a pas d’équivalent pour l’ancienne API de span. Utilisez setTags() pour des tags sur les erreurs suivantes, et beforeError ou beforeBreadcrumb pour retirer des données sensibles. Le contexte optionnel passé à captureError() n’est pas inclus dans les rapports d’erreur ordinaires pendant cette bêta.

Configuration

`@appsignal/javascript`	`@appsignal/browser`
`new Appsignal({ ... })`	`init({ ... })`
`key`	`key`, inchangée. La même Front-end API key.
`revision`	`appVersion`
`namespace`	Aucun équivalent. Les erreurs sont toujours rapportées dans `browser`.
`ignoreErrors: [/pattern/]`	`beforeError`, en retournant `null` en cas de correspondance.
`matchBacktracePaths`	Aucun équivalent. Contactez-nous si vous en dépendez.
Aucun équivalent	`active`, pour désactiver complètement le SDK en dehors de la production.
Aucun équivalent	`endpoint`, `errors.sampleRate`, `breadcrumbs.`, `privacy.`.

Avant :

import Appsignal from "@appsignal/javascript";
import { plugin as windowEvents } from "@appsignal/plugin-window-events";
import { plugin as consoleBreadcrumbs } from "@appsignal/plugin-breadcrumbs-console";
import { plugin as networkBreadcrumbs } from "@appsignal/plugin-breadcrumbs-network";

export const appsignal = new Appsignal({
  key: "<YOUR_FRONTEND_API_KEY>",
  revision: "<YOUR_APP_REVISION>",
  ignoreErrors: [/ResizeObserver/],
});

appsignal.use(windowEvents());
appsignal.use(consoleBreadcrumbs());
appsignal.use(networkBreadcrumbs());

Après :

import { init } from "@appsignal/browser";

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  active: process.env.NODE_ENV === "production",
  appVersion: "<YOUR_APP_REVISION>",
  beforeError: (event) => (/ResizeObserver/.test(event.message) ? null : event),
});

Les exceptions non interceptées, les breadcrumbs de console et les breadcrumbs réseau sont tous couverts par ce seul appel.

Méthodes

`@appsignal/javascript`	`@appsignal/browser`
`appsignal.sendError(error)`	`captureError(error)`
`appsignal.sendError(error, (span) => span.setTags({ ... }))`	Aucun équivalent direct pour des tags par erreur. `setTags({ ... })` s’applique aux erreurs suivantes, jusqu’à ce que ces tags soient effacés.
`appsignal.wrap(fn)`	Aucun équivalent. Utilisez `try`/`catch` avec `captureError`.
`appsignal.addBreadcrumb({ category, action, message, metadata })`	`addBreadcrumb({ category, message, data })`. Il n’y a pas de champ `action`, et `metadata` devient `data`.
`appsignal.createSpan()`, `appsignal.send(span)`	Aucun équivalent.
`appsignal.addDecorator(fn)`	`setTags()` pour les tags, `beforeError` pour tout le reste.
`appsignal.addOverride(fn)`	`beforeError` et `beforeBreadcrumb`.
`appsignal.use(plugin())`	Aucun équivalent. Intégré.
Aucun équivalent	`setRouteTemplate()`, qui regroupe erreurs et web vitals par route.
Aucun équivalent	`setTags()`, `clearTags()`, `destroy()`.

appsignal.wrap() exécutait votre code et rapportait les erreurs levées. La promesse retournée était rejetée avec la même erreur, afin que votre code puisse l’intercepter. Le remplacement direct rend les deux moitiés explicites :

import { captureError } from "@appsignal/browser";

try {
  await riskyOperation();
} catch (error) {
  captureError(error);
  throw error;
}

Intégrations de frameworks

Package	Remplacement
`@appsignal/react`	`@appsignal/browser/react`. Passez `captureError` au lieu d’une prop `instance`. Il n’y a pas de prop `override`, ni de composant `LegacyBoundary` distinct.
`@appsignal/vue`, `@appsignal/angular`, `@appsignal/preact`, `@appsignal/ember`, `@appsignal/stimulus`	Aucun équivalent. Les erreurs que ces frameworks laissent passer sont rapportées automatiquement. Rapportez celles que le framework intercepte lui-même avec `captureError()` depuis son gestionnaire d’erreurs.
`@appsignal/urql`	Aucun équivalent. Rapportez les erreurs GraphQL avec `captureError()` depuis l’error exchange de votre client.
`@appsignal/plugin-path-decorator`	`setRouteTemplate()`, l’équivalent intégré.

L’error boundary React change de forme :

import { ErrorBoundary } from "@appsignal/react";
import { appsignal } from "./appsignal";

<ErrorBoundary instance={appsignal} action="Dashboard" tags={{ plan: "pro" }}>
  <Dashboard />
</ErrorBoundary>

import { captureError } from "@appsignal/browser";
import { ErrorBoundary } from "@appsignal/browser/react";

<ErrorBoundary captureError={captureError}>
  <Dashboard />
</ErrorBoundary>

La nouvelle boundary n’a pas de prop action. Appelez setRouteTemplate() pour la route utilisée pour regrouper les erreurs. Si vous utilisez setTags(), appelez-la après init() et effacez-la quand ces tags ne doivent plus s’appliquer.

Étapes de la migration

Installez @appsignal/browser@beta et retirez @appsignal/javascript ainsi que chaque package @appsignal/plugin-* et d’intégration de framework.
Remplacez votre appel new Appsignal({ ... }) par init({ ... }), en vous appuyant sur le tableau de configuration de ce guide. Ajoutez endpoint et active.
Remplacez sendError par captureError, et wrap par try/catch.
Déplacez les motifs ignoreErrors, les décorateurs et les surcharges dans beforeError et beforeBreadcrumb.
Appelez setRouteTemplate() à chaque navigation de votre routeur.
Changez l’import de l’error boundary React, si vous en utilisez une.
Configurez les réglages de notification pour le namespace browser.
Déployez, puis vérifiez que les erreurs et les web vitals arrivent dans la section Browser de votre application.

Les sourcemaps ne demandent aucun changement. Ils sont toujours mis en correspondance sur la chaîne de révision, que fournit désormais appVersion.

SDK & télémétrie

SDK de langage

Outils de télémétrie

Migrer depuis AppSignal pour JavaScript

Ce qui change

Configuration

Méthodes

Intégrations de frameworks

Étapes de la migration

​Ce qui change

​Configuration

​Méthodes

​Intégrations de frameworks

​Étapes de la migration

Ce qui change

Configuration

Méthodes

Intégrations de frameworks

Étapes de la migration