Instrumentation

Wenn Sie eine Funktion namens register aus einer instrumentation.ts (oder .js)-Datei im Stammverzeichnis Ihres Projekts exportieren (oder im src-Ordner, falls verwendet), rufen wir diese Funktion auf, wenn eine neue Next.js-Serverinstanz initialisiert wird.

Gut zu wissen

• Dieses Feature ist experimentell. Um es zu verwenden, müssen Sie explizit zustimmen, indem Sie experimental.instrumentationHook = true; in Ihrer next.config.js definieren.
• Die instrumentation-Datei sollte im Stammverzeichnis Ihres Projekts und nicht im app- oder pages-Verzeichnis liegen. 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-Datei entsprechend anpassen.
• Wir haben ein grundlegendes with-opentelemetry-Beispiel erstellt, das Sie verwenden können.

Wenn Ihre register-Funktion bereitgestellt wird, wird sie bei jedem Kaltstart aufgerufen (aber genau einmal in jeder Umgebung).

Manchmal kann es nützlich sein, eine Datei in Ihren Code zu importieren, aufgrund der Seiteneffekte, die sie verursacht. Beispielsweise könnten Sie eine Datei importieren, die eine Reihe von globalen Variablen definiert, aber die importierte Datei nie explizit in Ihrem Code verwenden. Sie hätten trotzdem Zugriff auf die globalen Variablen, die das Paket deklariert hat.

Sie können Dateien mit Seiteneffekten in instrumentation.ts importieren, die Sie möglicherweise in Ihrer register-Funktion verwenden möchten, wie im folgenden Beispiel gezeigt:

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

Wir empfehlen jedoch, Dateien mit Seiteneffekten mit import 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')
}

Auf diese Weise können Sie alle Ihre Seiteneffekte an einer Stelle in Ihrem Code zusammenfassen und unbeabsichtigte Folgen durch das Importieren von Dateien vermeiden.

Wir rufen register in allen Umgebungen auf, daher ist es notwendig, Code, der nicht sowohl edge als auch nodejs unterstützt, bedingt zu importieren. Sie können die Umgebungsvariable NEXT_RUNTIME verwenden, um die aktuelle Umgebung abzurufen. Das Importieren eines umgebungsspezifischen Codes würde so aussehen:

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