Einrichtung von Instrumentation

Instrumentation ist der Prozess der Verwendung von Code, um Monitoring- und Logging-Tools in Ihre Anwendung zu integrieren. 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 Datei instrumentation.ts|js im Stammverzeichnis Ihres Projekts (oder im Ordner src, falls Sie einen verwenden.

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

Beispielsweise, um Next.js mit OpenTelemetry und @vercel/otel zu verwenden:

import { registerOTel } from '@vercel/otel'

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

Siehe das Next.js mit OpenTelemetry Beispiel für eine vollständige Implementierung.

Wissenswert:

• 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 in src neben pages und app.
• Wenn Sie die pageExtensions-Konfigurationsoption verwenden, um ein Suffix hinzuzufügen, müssen Sie auch den Dateinamen der instrumentation entsprechend anpassen.

Beispiele

Importieren von Dateien mit Nebeneffekten

Manchmal kann es nützlich sein, eine Datei in Ihren Code zu importieren, aufgrund der Nebeneffekte, die sie verursacht. Beispielsweise könnten Sie eine Datei importieren, die eine Reihe globaler Variablen definiert, aber nie explizit die importierte Datei in Ihrem Code 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 demonstriert eine grundlegende Verwendung von import in einer register-Funktion:

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

Wissenswert:

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

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