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

# Migration Guide

<Note>
  🛟 Zögern Sie nicht, uns zu [kontaktieren](mailto:support@appsignal.com), falls
  beim Upgrade des AppSignal-für-Node.js-Pakets Ihrer Anwendung Probleme
  auftreten. Wir helfen Ihnen gerne!
</Note>

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](mailto:support@appsignal.com) 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

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

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

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

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

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

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

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

### 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](/metrics/custom#counter) tun.

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

## Integrationen

<Tip>
  Express und Next.js benötigen einen [Error
  Handler](/nodejs/3.x/integrations/express#error-handler).
</Tip>

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

<Warning>
  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.
</Warning>

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

<Tip>
  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.
</Tip>

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

**Vergessen Sie nicht, [das AppSignal-Integrationspaket zu entfernen/deinstallieren](#remove-integration-package).**

### Apollo-Server-Integration entfernen

<Warning>
  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.
</Warning>

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

<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 wird vom Paket AppSignal für Node.js automatisch instrumentiert.

[3.x-GraphQL-Integrationsdokumentation lesen](/nodejs/3.x/integrations/graphql)

Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie [das Apollo-AppSignal-Paket](#remove-apollo-server-integration) aus Ihrer Anwendung entfernen.

### Express-Integration entfernen

<Warning>
  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.
</Warning>

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

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

[3.x-Express-Integrationsdokumentation lesen](/nodejs/3.x/integrations/express)

Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie [das AppSignal-Express-Paket](#remove-express-integration) aus Ihrer Anwendung entfernen.

### Koa.js-Integration entfernen

<Warning>
  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.
</Warning>

Entfernen Sie die 2.x-Initialisierung des AppSignal-Koa-Pakets und der Instrumentierung aus Ihrer Anwendung.

#### 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 wird vom Paket AppSignal für Node.js automatisch instrumentiert.

[3.x-Koa.js-Integrationsdokumentation lesen](/nodejs/3.x/integrations/koajs)

Nachdem Sie Ihren Integrationscode geändert haben, müssen Sie [das Koa.js-Paket](#remove-koajs-integration) aus Ihrer Anwendung entfernen.

### Next.js-Integration entfernen

<Warning>
  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.
</Warning>

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

<CodeGroup>
  ```javascript Node.js theme={null}
  import { getRequestHandler } from "@appsignal/nextjs";
  // or: const { getRequestHandler } = require("@appsignal/nextjs");
  ```
</CodeGroup>

#### 3.x

Next.js wird vom Paket AppSignal für Node.js automatisch instrumentiert.

[3.x-Next.js-Integrationsdokumentation lesen](/nodejs/3.x/integrations/nextjs)

### 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 Bash theme={null}
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

| Integration   | Paketname                  |
| ------------- | -------------------------- |
| 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:

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

[Mehr über Tracer in der 3.x-Instrumentierungsdokumentation lesen.](/nodejs/3.x/instrumentation/instrumentation)

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

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

[Mehr über Spans in der 3.x-Instrumentierungsdokumentation lesen.](/nodejs/3.x/instrumentation/instrumentation)

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

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

[Mehr über Hilfsfunktionen für Span-Attribute in der 3.x-Instrumentierungsdokumentation lesen.](/nodejs/3.x/instrumentation/instrumentation#helpers)

## Ausnahmebehandlung

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

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

In `sendError()` können [Hilfsfunktionen](/nodejs/3.x/instrumentation/instrumentation#helpers) verwendet werden, um dem Error-Span zusätzliche Daten hinzuzufügen.

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

[Mehr über die Ausnahmebehandlung in der 3.x-Dokumentation zur Ausnahmebehandlung lesen.](/nodejs/3.x/instrumentation/exception-handling)