Menu

instrumentation.js

Die Datei instrumentation.js|ts wird verwendet, um Observability-Tools in Ihre Anwendung zu integrieren und ermöglicht es Ihnen, Leistung und Verhalten zu verfolgen sowie Probleme in der Produktion zu debuggen.

Um sie zu verwenden, platzieren Sie die Datei im Stammverzeichnis Ihrer Anwendung oder innerhalb eines src-Ordners, falls Sie einen verwenden.

Exporte

register (optional)

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

instrumentation.ts
import { registerOTel } from '@vercel/otel'
 
export function register() {
  registerOTel('next-app')
}
instrumentation.js
import { registerOTel } from '@vercel/otel'
 
export function register() {
  registerOTel('next-app')
}

onRequestError (optional)

Sie können optional eine onRequestError-Funktion exportieren, um Server-Fehler an einen beliebigen benutzerdefinierten Observability-Anbieter zu verfolgen.

  • Wenn Sie asynchrone Aufgaben in onRequestError ausführen, stellen Sie sicher, dass diese abgewartet 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 sie während des Server-Komponenten-Renderings auftritt. In diesem Fall können Sie die digest-Eigenschaft eines Fehlers verwenden, um den tatsächlichen Fehlertyp zu identifizieren.
instrumentation.ts
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',
    },
  })
}
instrumentation.js
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.

Types
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 für eine normale Anfrage ohne Neuvalidierung
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' für PPR
  }
): void | Promise<void>
  • error: Der gefangene Fehler selbst (Typ ist immer Error), und eine digest-Eigenschaft, die die eindeutige ID des Fehlers darstellt.
  • request: Schreibgeschützte Anfrageinformationen, die mit dem Fehler verbunden sind.
  • context: Der Kontext, in dem der Fehler auftrat. Dies kann der Router-Typ (App oder Pages Router) und/oder (Server-Komponenten ('render'), Route-Handler ('route'), Server-Aktionen ('action') oder Middleware ('middleware')) sein.

Festlegen der Laufzeit

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

instrumentation.js
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

VersionÄnderungen
v15.0.0-RConRequestError eingeführt, instrumentation stabil
v14.0.4Turbopack-Unterstützung für instrumentation
v13.2.0instrumentation als experimentelle Funktion eingeführt