Instrumentation

L'instrumentation est le processus d'utilisation de code pour intégrer des outils de surveillance et de journalisation dans votre application. Cela vous permet de suivre les performances et le comportement de votre application, et de déboguer des problèmes en production.

Convention

Pour configurer l'instrumentation, créez un fichier instrumentation.ts|js dans le répertoire racine de votre projet (ou dans le dossier src si vous en utilisez un).

Ensuite, exportez une fonction register dans le fichier. Cette fonction sera appelée une fois lorsqu'une nouvelle instance du serveur Next.js sera initialisée.

Par exemple, pour utiliser Next.js avec OpenTelemetry et @vercel/otel :

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

Consultez l'exemple Next.js avec OpenTelemetry pour une implémentation complète.

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.

Exemples

Importer des fichiers avec effets secondaires

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 ne jamais utiliser explicitement le fichier importé dans votre code. Vous auriez tout de même accès aux variables globales déclarées par le package.

Nous recommandons d'importer les fichiers en utilisant la syntaxe JavaScript import dans votre fonction register. 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')
}

Bon à savoir :

Nous recommandons d'importer le fichier depuis la fonction register, plutôt qu'en haut du fichier. En procédant ainsi, vous pouvez regrouper tous vos effets secondaires en un seul endroit dans votre code, et éviter toute conséquence involontaire due à une importation globale en haut du fichier.

Importer du code spécifique à l'environnement d'exécution

Next.js appelle register dans tous les environnements, il est donc important d'importer conditionnellement tout code qui ne prend pas en charge des environnements d'exécution spécifiques (par exemple Edge ou Node.js). Vous pouvez utiliser la variable d'environnement NEXT_RUNTIME pour obtenir l'environnement actuel :

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