instrumentation.js

Le fichier instrumentation.js|ts est utilisé pour intégrer des outils d'observabilité dans votre application, vous permettant de suivre les performances et le comportement, ainsi que de déboguer les problèmes en production.

Pour l'utiliser, placez le fichier à la racine de votre application ou dans un dossier src si vous en utilisez un.

Exports

register (optionnel)

Le fichier exporte une fonction register qui est appelée une fois lorsqu'une nouvelle instance du serveur Next.js est initialisée. register peut être une fonction asynchrone.

import { registerOTel } from '@vercel/otel'

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

onRequestError (optionnel)

Vous pouvez optionnellement exporter une fonction onRequestError pour suivre les erreurs serveur vers n'importe quel fournisseur d'observabilité personnalisé.

• Si vous exécutez des tâches asynchrones dans onRequestError, assurez-vous qu'elles sont attendues. onRequestError sera déclenchée lorsque le serveur Next.js capturera l'erreur.
• L'instance error pourrait ne pas être l'instance d'erreur originale levée, car elle peut être traitée par React si elle est rencontrée lors du rendu des Composants Serveur. Si cela se produit, vous pouvez utiliser la propriété digest sur une erreur pour identifier le type d'erreur réel.

import { type Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

Paramètres

La fonction accepte trois paramètres : error, request et context.

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // chemin de la ressource, ex. /blog?name=foo
    method: string // méthode de requête, ex. GET, POST, etc
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // type de routeur
    routePath: string // chemin du fichier de route, ex. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // contexte dans lequel l'erreur s'est produite
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined pour une requête normale sans revalidation
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' pour PPR
  }
): void | Promise<void>

• error : L'erreur capturée elle-même (le type est toujours Error), et une propriété digest qui est l'ID unique de l'erreur.
• request : Informations de requête en lecture seule associées à l'erreur.
• context : Le contexte dans lequel l'erreur s'est produite. Cela peut être le type de routeur (App ou Pages Router), et/ou (Composants Serveur ('render'), Gestionnaires de Route ('route'), Actions Serveur ('action'), ou Middleware ('middleware')).

Spécification du runtime

Le fichier instrumentation.js fonctionne à la fois dans le runtime Node.js et Edge, cependant, vous pouvez utiliser process.env.NEXT_RUNTIME pour cibler un runtime spécifique.

export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./register.edge')
  } else {
    return require('./register.node')
  }
}

export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./on-request-error.edge')
  } else {
    return require('./on-request-error.node')
  }
}

Historique des versions