Instrumentierung

Instrumentierung ist der Prozess, Überwachungs- und Logging-Tools mithilfe von Code in Ihre Anwendung zu integrieren. Dadurch können Sie die Leistung und das Verhalten Ihrer Anwendung verfolgen und Probleme in der Produktivumgebung debuggen.

Konvention

Um die Instrumentierung einzurichten, erstellen Sie eine instrumentation.ts|js-Datei im Stammverzeichnis Ihres Projekts (oder innerhalb des src-Ordners, wenn Sie einen verwenden).

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

Beispielsweise zur 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')
}

Weitere Informationen finden Sie im Next.js mit OpenTelemetry-Beispiel.

Hinweis:

• Die instrumentation-Datei sollte sich im Stammverzeichnis Ihres Projekts befinden und nicht innerhalb des app- oder pages-Verzeichnisses. Wenn Sie den src-Ordner verwenden, platzieren Sie die Datei innerhalb von src neben pages und app.
• Wenn Sie die Konfigurationsoption pageExtensions verwenden, um ein Suffix hinzuzufügen, müssen Sie auch den instrumentation-Dateinamen entsprechend anpassen.

Beispiele

Importieren von Dateien mit Seitenwirkungen

Manchmal kann es nützlich sein, eine Datei in Ihrem Code zu importieren, aufgrund der Seitenwirkungen, die sie verursachen wird. Zum Beispiel könnten Sie eine Datei importieren, die eine Reihe von globalen Variablen definiert, ohne die importierte Datei explizit in Ihrem Code zu verwenden. Sie hätten trotzdem Zugriff auf die globalen Variablen, die das Paket deklariert hat.

Wir empfehlen, Dateien mithilfe 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')
}

Hinweis:

Wir empfehlen, die Datei innerhalb der register-Funktion zu importieren, anstatt am Anfang der Datei. Dadurch können Sie alle Seitenwirkungen an einem Ort in Ihrem Code zusammenfassen und unbeabsichtigte Folgen durch globales Importieren am Anfang der Datei vermeiden.

Importieren von laufzeitspezifischem Code

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

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')
  }
}