instrumentation.js

Die Datei instrumentation.js|ts wird verwendet, um Observability-Tools in Ihre Anwendung zu integrieren, wodurch Sie die Leistung und das Verhalten überwachen sowie Probleme in der Produktion debuggen können.

Um sie zu verwenden, platzieren Sie die Datei im Stammverzeichnis Ihrer Anwendung oder in einem src-Ordner, falls Sie einen verwenden.

Exporte

register (optional)

Die Datei exportiert eine register-Funktion, die einmal aufgerufen wird, wenn eine neue Next.js-Serverinstanz initialisiert wird. register kann eine asynchrone Funktion sein.

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

onRequestError (optional)

Sie können optional eine onRequestError-Funktion exportieren, um Server-Fehler bei einem beliebigen benutzerdefinierten Observability-Provider zu verfolgen.

• Wenn Sie asynchrone Aufgaben in onRequestError ausführen, stellen Sie sicher, dass sie mit await behandelt werden. onRequestError wird ausgelöst, wenn der Next.js-Server den Fehler erfasst.
• Die error-Instanz ist möglicherweise nicht die ursprüngliche Fehlerinstanz, da sie von React verarbeitet werden kann, wenn der Fehler während des Renderings von Server Components auftritt. In diesem Fall können Sie die Eigenschaft digest eines Fehlers verwenden, um den tatsächlichen Fehlertyp zu identifizieren.

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

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

Parameter

Die Funktion akzeptiert drei Parameter: error, request und context.

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // Ressourcenpfad, z.B. /blog?name=foo
    method: string // Anfragemethode, z.B. GET, POST usw.
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // der Router-Typ
    routePath: string // der Routendateipfad, z.B. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // der Kontext, in dem der Fehler auftrat
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined ist eine normale Anfrage ohne Revalidierung
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' für PPR
  }
): void | Promise<void>

• error: Der aufgetretene Fehler selbst (Typ ist immer Error) und eine Eigenschaft digest, die die eindeutige ID des Fehlers ist.
• request: Schreibgeschützte Anfrageinformationen, die mit dem Fehler verknüpft sind.
• context: Der Kontext, in dem der Fehler aufgetreten ist. Dies kann der Typ des Routers (App oder Pages Router) und/oder (Server Components ('render'), Route Handlers ('route'), Server Actions ('action') oder Middleware ('middleware')) sein.

Angabe der Laufzeitumgebung

Die Datei instrumentation.js funktioniert sowohl in der Node.js- als auch in der Edge-Laufzeitumgebung. Sie können jedoch process.env.NEXT_RUNTIME verwenden, um eine bestimmte Laufzeitumgebung anzusprechen.

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

Versionsverlauf