Instrumentation

Instrumentation bezeichnet den Prozess der Integration von Monitoring- und Logging-Tools in Ihre Anwendung mithilfe von Code. Dies ermöglicht es Ihnen, die Leistung und das Verhalten Ihrer Anwendung zu verfolgen sowie Probleme in der Produktion zu debuggen.

Konvention

Um Instrumentation einzurichten, erstellen Sie eine instrumentation.ts|js-Datei im Stammverzeichnis Ihres Projekts (oder im src-Ordner, falls verwendet).

Exportieren Sie dann eine register-Funktion in der Datei. Diese Funktion wird einmalig aufgerufen, wenn eine neue Next.js-Serverinstanz gestartet wird.

Beispiel für die Verwendung von Next.js mit OpenTelemetry und @vercel/otel:

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

Ein vollständiges Implementierungsbeispiel finden Sie im Next.js mit OpenTelemetry Beispiel.

Wichtig zu wissen

• Diese Funktion ist experimentell. Um sie zu nutzen, müssen Sie explizit experimental.instrumentationHook = true; in Ihrer next.config.js definieren.
• Die instrumentation-Datei sollte sich im Stammverzeichnis Ihres Projekts befinden und nicht im app- oder pages-Ordner. Bei Verwendung des src-Ordners platzieren Sie die Datei dort neben pages und app.
• Wenn Sie die pageExtensions-Konfigurationsoption verwenden, um ein Suffix hinzuzufügen, müssen Sie auch den Dateinamen der instrumentation-Datei entsprechend anpassen.

Beispiele

Import von Dateien mit Seiteneffekten

Manchmal kann es nützlich sein, eine Datei aufgrund ihrer Seiteneffekte in Ihren Code zu importieren. Beispielsweise könnten Sie eine Datei importieren, die eine Reihe globaler Variablen definiert, ohne die importierte Datei explizit in Ihrem Code zu verwenden. Sie hätten dennoch Zugriff auf die globalen Variablen, die das Paket deklariert hat.

Wir empfehlen, Dateien mit der JavaScript-import-Syntax innerhalb Ihrer register-Funktion zu importieren. Das folgende Beispiel zeigt eine grundlegende Verwendung von import in einer register-Funktion:

export async function register() {
  await import('package-with-side-effect')
}

export async function register() {
  await import('package-with-side-effect')
}

Wichtig zu wissen:

Wir empfehlen, die Datei innerhalb der register-Funktion zu importieren, anstatt sie oben in der Datei zu importieren. Auf diese Weise können Sie alle Seiteneffekte an einer zentralen Stelle in Ihrem Code zusammenfassen und unbeabsichtigte Folgen durch globalen Import oben in der Datei vermeiden.

Import von runtime-spezifischem Code

Next.js ruft register in allen Umgebungen auf, daher ist es wichtig, Code, der bestimmte Laufzeitumgebungen nicht unterstützt (z.B. Edge oder Node.js), bedingt zu importieren. Sie können die Umgebungsvariable NEXT_RUNTIME verwenden, um die aktuelle Umgebung abzufragen:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}