Von AppSignal für JavaScript migrieren

Browser monitoring ist ein Beta-Feature von AppSignal Labs. Das Paket @appsignal/browser wird unter dem beta-Tag auf npm veröffentlicht, und seine Konfiguration und API können sich zwischen Beta-Releases noch ändern. Teilen Sie Ihr Feedback in unserer Discord-Community.

@appsignal/browser ersetzt @appsignal/javascript, dessen Framework-Integrationen und dessen Plugin-Pakete. Dieser Leitfaden ordnet die alte API der neuen zu. Das neue SDK sammelt Breadcrumbs und web vitals nach init() und meldet Fehler in den Browser-Ansichten. Migrieren Sie, sobald Sie bereit sind, die neue API zu übernehmen, und sehen Sie sich die folgenden Änderungen an.

Was sich ändert

Ein Paket statt mehrerer. Error tracking, Breadcrumbs und web vitals sind alle in @appsignal/browser. Das neue SDK hat keine passenden Plugin- oder Framework-Pakete mehr. Manche Funktionen sind eingebaut, andere erfordern Anwendungscode. Funktionen statt einer Instanz. Es gibt kein Client-Objekt, das Sie erzeugen, herumgeben oder einer Komponente übergeben. Sie rufen init() einmal auf und importieren die Funktionen, die Sie brauchen, dort, wo Sie sie brauchen. Nicht abgefangene Fehler werden ohne Nachfrage gemeldet. @appsignal/plugin-window-events gab es, weil Sie sie aktiv einschalten mussten. Sie sind jetzt standardmäßig an. Das SDK verwirft nichtssagende Cross-Origin-Skriptfehler. Verwenden Sie beforeError, um anderes Rauschen von Browsern oder Erweiterungen herauszufiltern. Fehler werden an den browser-namespace gemeldet. @appsignal/javascript meldete an frontend, und es gibt keine namespace-Option mehr. Neue Fehler erscheinen im Browser-Bereich. Bestehende frontend-Fehler bleiben in ihrer aktuellen Liste. Bestehende Incidents im frontend-namespace bleiben, wo sie sind.

Benachrichtigungseinstellungen werden pro namespace konfiguriert, die für frontend eingerichteten gelten also nicht für browser. Richten Sie sie nach der Migration erneut ein, sonst kommen Front-end-Fehler an, ohne dass jemand benachrichtigt wird.

Ihre bestehenden frontend-Incidents behalten ihre Zuweisungen, Zustände und Schweregrade. Das neue Paket meldet an den browser-namespace. Dessen neue Issues starten ohne Zuweisung, wie jedes andere neue Issue. Keine spans, Dekoratoren oder Overrides. Das neue SDK hat kein Gegenstück zur alten span-API. Verwenden Sie setTags() für Tags auf nachfolgenden Fehlern und beforeError oder beforeBreadcrumb, um sensible Daten zu entfernen. Der optionale Kontext, den Sie an captureError() übergeben, ist in dieser Beta nicht in gewöhnlichen Fehlerberichten enthalten.

Konfiguration

`@appsignal/javascript`	`@appsignal/browser`
`new Appsignal({ ... })`	`init({ ... })`
`key`	`key`, unverändert. Derselbe Front-end API key.
`revision`	`appVersion`
`namespace`	Kein Gegenstück. Fehler werden immer an `browser` gemeldet.
`ignoreErrors: [/pattern/]`	`beforeError`, das bei einem Treffer `null` zurückgibt.
`matchBacktracePaths`	Kein Gegenstück. Kontaktieren Sie uns, wenn Sie darauf angewiesen sind.
Kein Gegenstück	`active`, um das SDK außerhalb der Produktion vollständig abzuschalten.
Kein Gegenstück	`endpoint`, `errors.sampleRate`, `breadcrumbs.`, `privacy.`.

Vorher:

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

Nachher:

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

Nicht abgefangene Exceptions, Konsolen-Breadcrumbs und Netzwerk-Breadcrumbs werden alle von diesem einen Aufruf abgedeckt.

Methoden

`@appsignal/javascript`	`@appsignal/browser`
`appsignal.sendError(error)`	`captureError(error)`
`appsignal.sendError(error, (span) => span.setTags({ ... }))`	Kein direktes Gegenstück für Tags pro Fehler. `setTags({ ... })` gilt für nachfolgende Fehler, bis diese Tags gelöscht werden.
`appsignal.wrap(fn)`	Kein Gegenstück. Verwenden Sie `try`/`catch` mit `captureError`.
`appsignal.addBreadcrumb({ category, action, message, metadata })`	`addBreadcrumb({ category, message, data })`. Es gibt kein `action`-Feld, und `metadata` heißt jetzt `data`.
`appsignal.createSpan()`, `appsignal.send(span)`	Kein Gegenstück.
`appsignal.addDecorator(fn)`	`setTags()` für Tags, `beforeError` für alles andere.
`appsignal.addOverride(fn)`	`beforeError` und `beforeBreadcrumb`.
`appsignal.use(plugin())`	Kein Gegenstück. Eingebaut.
Kein Gegenstück	`setRouteTemplate()`, das Fehler und web vitals nach Route gruppiert.
Kein Gegenstück	`setTags()`, `clearTags()`, `destroy()`.

appsignal.wrap() führte Ihren Code aus und meldete ausgelöste Fehler. Das zurückgegebene Promise wurde mit demselben Fehler abgelehnt, sodass Ihr Code ihn abfangen konnte. Der direkte Ersatz macht beide Hälften ausdrücklich:

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

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

Framework-Integrationen

Paket	Ersatz
`@appsignal/react`	`@appsignal/browser/react`. Übergeben Sie `captureError` statt einer `instance`-Prop. Es gibt keine `override`-Prop und keine separate `LegacyBoundary`-Komponente.
`@appsignal/vue`, `@appsignal/angular`, `@appsignal/preact`, `@appsignal/ember`, `@appsignal/stimulus`	Kein Gegenstück. Fehler, die diese Frameworks durchlassen, werden automatisch gemeldet. Melden Sie die, die das Framework selbst abfängt, mit `captureError()` aus seinem Error-Handler.
`@appsignal/urql`	Kein Gegenstück. Melden Sie GraphQL-Fehler mit `captureError()` aus dem Error Exchange Ihres Clients.
`@appsignal/plugin-path-decorator`	`setRouteTemplate()`, das eingebaute Gegenstück.

Die React Error Boundary ändert ihre Form:

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>

Die neue Boundary hat keine action-Prop. Rufen Sie setRouteTemplate() für die Route auf, nach der Fehler gruppiert werden. Wenn Sie setTags() verwenden, rufen Sie es nach init() auf und löschen Sie die Tags, wenn sie nicht mehr gelten sollen.

Schritte zur Migration

Installieren Sie @appsignal/browser@beta und entfernen Sie @appsignal/javascript samt jedem @appsignal/plugin-*- und Framework-Integrationspaket.
Ersetzen Sie Ihren new Appsignal({ ... })-Aufruf durch init({ ... }), anhand der Konfigurationstabelle in diesem Leitfaden. Fügen Sie endpoint und active hinzu.
Ersetzen Sie sendError durch captureError und wrap durch try/catch.
Verschieben Sie ignoreErrors-Muster, Dekoratoren und Overrides in beforeError und beforeBreadcrumb.
Rufen Sie bei jeder Router-Navigation setRouteTemplate() auf.
Tauschen Sie den Import der React Error Boundary, falls Sie eine verwenden.
Richten Sie Benachrichtigungseinstellungen für den browser-namespace ein.
Deployen Sie, und bestätigen Sie dann, dass Fehler und web vitals im Browser-Bereich Ihrer Anwendung ankommen.

Sourcemaps brauchen keine Änderung. Sie werden weiterhin über den Revisions-String abgeglichen, den nun appVersion liefert.

SDKs & Telemetrie

Sprach-SDKs

Telemetrie-Tools

Von AppSignal für JavaScript migrieren

Was sich ändert

Konfiguration

Methoden

Framework-Integrationen

Schritte zur Migration

​Was sich ändert

​Konfiguration

​Methoden

​Framework-Integrationen

​Schritte zur Migration

Was sich ändert

Konfiguration

Methoden

Framework-Integrationen

Schritte zur Migration