Zum Hauptinhalt springen
🛟 Zögern Sie nicht, uns zu kontaktieren, falls beim Upgrade des AppSignal-für-Node.js-Pakets Ihrer Anwendung Probleme auftreten. Wir helfen Ihnen gerne!
Diese Dokumentation listet die Änderungen zwischen den Releases 2.x und 3.x des AppSignal-Node.js-Pakets auf. Wenn Sie von 2.x auf 3.x aktualisieren, müssen Sie Ihre Integration anpassen, damit sie weiterhin funktioniert. Wenn beim Upgrade Ihrer Anwendung Probleme auftreten, kontaktieren Sie uns gerne für Support.

​
Installation von 3.x

Um AppSignal für Node.js 3.x zu installieren, führen Sie den folgenden Befehl im Stammverzeichnis Ihrer Anwendung aus.

​
npm

npm install @appsignal/nodejs

​
AppSignal Client

Beim Upgrade von 2.x auf 3.x müssen Sie ändern, wie Ihre Anwendung den AppSignal-Client initialisiert und darauf zugreift.

​
AppSignal-Client initialisieren

Um den AppSignal-Client zu initialisieren und zu exportieren, müssen Sie eine neue Datei appsignal.cjs erstellen, wie im Beispiel unten: 
// appsignal.cjs

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

const appsignal = new Appsignal({
  active: true,
  name: "Your app name",
});
Sie müssen Ihre Datei appsignal.cjs beim Starten Ihrer Anwendung einbinden (--require ./appsignal.cjs). Zum Beispiel in der Datei package.json Ihrer Anwendung, wie im Beispiel unten:

​
Javascript

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

​
Auf den AppSignal-Client zugreifen

In 3.x wird der AppSignal-Client über das global exportierte Objekt Appsignal.client aufgerufen. Die folgenden Beispiele zeigen, wie Sie dies im Kontext eines benutzerdefinierten Metrik-Counters tun.

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

​
Integrationen

Express und Next.js benötigen einen Error Handler.
AppSignal für Node.js 3.x unterstützt alle 2.x-Integrationen out-of-the-box. Das bedeutet, dass die Pakete für die einzelnen Integrationen nicht mehr installiert werden müssen. Beim Wechsel von 2.x auf 3.x müssen Sie alle für Ihre Anwendung installierten AppSignal-Integrationspakete entfernen.

​
Integrationen deinstallieren

Die 2.x-Integrationen sind nicht mit der 3.x-Node.js-Integration kompatibel. Sie müssen die unten beschriebenen Migrationsschritte befolgen, um die Node.js-Integrationen zu verwenden.
Um die out-of-the-box-Integrationsunterstützung von AppSignal für Node.js 3.x zu nutzen, müssen Sie zunächst die Integrationsinstallationen „rückgängig machen“, die in der Version 2.x erforderlich waren.

​
Vom AppSignal-Paket abhängigen Code entfernen

Die folgenden Beispiele sind illustrativ und basieren auf der Integrationsdokumentation von AppSignal für 2.x und 3.x. Der Code in Ihrer Anwendung kann sich von den Beispielen in dieser Dokumentation unterscheiden.
Vergessen Sie nicht, das AppSignal-Integrationspaket zu entfernen/deinstallieren.

​
Apollo-Server-Integration entfernen

Das 2.x-Paket @appsignal/apollo-server ist nicht mit der 3.x-Node.js-Integration kompatibel. Sie müssen die unten beschriebenen Migrationsschritte befolgen, wenn Sie Apollo Server mit unserer 3.x-Integration verwenden möchten.
Entfernen Sie die 2.x-Initialisierung des AppSignal-Apollo-Server-Pakets und des Plugins aus Ihrer Anwendung und ersetzen Sie sie durch die 3.x-Installationsanweisungen. Ihre Apollo-Anwendung wird automatisch instrumentiert.

​
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 wird vom Paket AppSignal für Node.js automatisch instrumentiert. 3.x-GraphQL-Integrationsdokumentation lesen Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie das Apollo-AppSignal-Paket aus Ihrer Anwendung entfernen.

​
Express-Integration entfernen

Das 2.x-Paket @appsignal/express ist nicht mit der 3.x-Node.js-Integration kompatibel. Sie müssen die unten beschriebenen Migrationsschritte befolgen, wenn Sie Express mit unserer 3.x-Integration verwenden möchten.
Entfernen Sie die 2.x-Initialisierung des AppSignal-Express-Pakets und der Middleware aus Ihrer Anwendung und ersetzen Sie sie durch die 3.x-Installationsanweisungen.

​
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());
3.x-Express-Integrationsdokumentation lesen Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie das AppSignal-Express-Paket aus Ihrer Anwendung entfernen.

​
Koa.js-Integration entfernen

Das 2.x-Paket @appsignal/koa ist nicht mit der 3.x-Node.js-Integration kompatibel. Sie müssen die unten beschriebenen Migrationsschritte befolgen, wenn Sie Koa.js mit unserer 3.x-Integration verwenden möchten.
Entfernen Sie die 2.x-Initialisierung des AppSignal-Koa-Pakets und der Instrumentierung aus Ihrer Anwendung.

​
2.x

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

​
3.x

Koa.js wird vom Paket AppSignal für Node.js automatisch instrumentiert. 3.x-Koa.js-Integrationsdokumentation lesen Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie das Koa.js-Paket aus Ihrer Anwendung entfernen.

​
Next.js-Integration entfernen

Das 2.x-Paket @appsignal/nextjs ist nicht mit der 3.x-Node.js-Integration kompatibel. Sie müssen die unten beschriebenen Migrationsschritte befolgen, wenn Sie Next.js mit unserer 3.x-Integration verwenden möchten.
Die Funktion „Web Vitals Reporting“ wurde als veraltet markiert und ist in AppSignal für Node.js 3.x nicht mehr verfügbar.

​
2.x

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

​
3.x

Next.js wird vom Paket AppSignal für Node.js automatisch instrumentiert. 3.x-Next.js-Integrationsdokumentation lesen

​
Integrationspaket entfernen

Sobald die Imports und der von diesen Imports abhängige Code entfernt wurden, müssen Sie das Integrationspaket deinstallieren. Dies können Sie mit npm uninstall tun, wie im folgenden Beispiel.
Bash
npm uninstall @appsignal/express
Die npm uninstall-Befehle entfernen Paketabhängigkeiten und aktualisieren die package.json Ihrer Anwendung sowie die Datei package-lock.json von npm. Ersetzen Sie @appsignal/express im obigen Beispiel durch den Namen des Integrationspakets, das Sie entfernen.

​
Namen der AppSignal-Integrationspakete

IntegrationPaketname
Apollo Server@appsignal/apollo-server
Express@appsignal/express
Koa.js@appsignal/koa
Next.js@appsignal/nextjs

​
Das Tracer-Objekt

Es gibt kein eigenes AppSignal-Tracer-Objekt mehr. OpenTelemetry stellt einen Tracer-Provider bereit, mit dem Sie neue Spans erstellen können.

​
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");
Mehr über Tracer in der 3.x-Instrumentierungsdokumentation lesen.

​
Spans

Es gibt kein eigenes AppSignal-Span-Objekt mehr. Die Tracer-Funktionen von AppSignal wie rootSpan(), createSpan(), currentSpan() und withSpan() sind nicht mehr verfügbar. Spans müssen durch Aufrufen der Methode startActiveSpan auf einem Tracer-Objekt erstellt werden. Neue Spans sind automatisch Kinder des Spans, in dem sie erstellt wurden.

​
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();
});
Mehr über Spans in der 3.x-Instrumentierungsdokumentation lesen.

​
Hilfsfunktionen für Span-Attribute

Die Hilfsfunktionen zum Setzen von Span-Attributen haben sich ebenfalls geändert. setSQL wurde durch setBody ersetzt, set wurde in setTag umbenannt und es wurden zusätzliche Hilfsfunktionen hinzugefügt. setName wurde entfernt, da Spans bei ihrer Erstellung einen Namen erhalten müssen.

​
2.x

const span = tracer.currentSpan();

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

​
3.x

setCategory("query.sql");
setSQL("SELECT * FROM users");
Mehr über Hilfsfunktionen für Span-Attribute in der 3.x-Instrumentierungsdokumentation lesen.

​
Ausnahmebehandlung

Tracer- und Span-Objekte werden bei der Verwendung von setError() und sendError() nicht mehr benötigt.

​
2.x

tracer.setError(err);

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

​
3.x

In sendError() können Hilfsfunktionen verwendet werden, um dem Error-Span zusätzliche Daten hinzuzufügen. 
import { setError, sendError } from "@appsignal/nodejs";
// or: const { setError, sendError } = require("@appsignal/nodejs");

setError(err);

sendError(err, () => {
  setTag("user_id", user_id);
});
Mehr über die Ausnahmebehandlung in der 3.x-Dokumentation zur Ausnahmebehandlung lesen.