Instrumentation

Si vous exportez une fonction nommée register depuis un fichier instrumentation.ts (ou .js) dans le répertoire racine de votre projet (ou dans le dossier src si vous en utilisez un), nous appellerons cette fonction chaque fois qu'une nouvelle instance de serveur Next.js est initialisée.

Bon à savoir

• Cette fonctionnalité est expérimentale. Pour l'utiliser, vous devez explicitement l'activer en définissant experimental.instrumentationHook = true; dans votre next.config.js.
• Le fichier instrumentation doit être à la racine de votre projet et non dans les répertoires app ou pages. Si vous utilisez le dossier src, placez le fichier dans src à côté de pages et app.
• Si vous utilisez l'option de configuration pageExtensions pour ajouter un suffixe, vous devrez également mettre à jour le nom du fichier instrumentation pour correspondre.
• Nous avons créé un exemple basique with-opentelemetry que vous pouvez utiliser.

Lorsque votre fonction register est déployée, elle sera appelée à chaque démarrage à froid (mais exactement une fois dans chaque environnement).

Parfois, il peut être utile d'importer un fichier dans votre code en raison des effets secondaires qu'il provoquera. Par exemple, vous pourriez importer un fichier qui définit un ensemble de variables globales, mais n'utiliser jamais explicitement le fichier importé dans votre code. Vous auriez toujours accès aux variables globales déclarées par le package.

Vous pouvez importer des fichiers avec des effets secondaires dans instrumentation.ts, que vous pourriez vouloir utiliser dans votre fonction register comme démontré dans l'exemple suivant :

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

Cependant, nous recommandons d'importer les fichiers avec effets secondaires en utilisant import depuis votre fonction register à la place. L'exemple suivant démontre une utilisation basique de import dans une fonction register :

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

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

En faisant cela, vous pouvez colocaliser tous vos effets secondaires dans un seul endroit de votre code, et éviter toute conséquence non intentionnelle liée à l'importation de fichiers.

Nous appelons register dans tous les environnements, il est donc nécessaire d'importer conditionnellement tout code qui ne supporte pas à la fois edge et nodejs. Vous pouvez utiliser la variable d'environnement NEXT_RUNTIME pour obtenir l'environnement actuel. Importer un code spécifique à un environnement ressemblerait à ceci :

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