instrumentation.ts in Next.js

From the Next.js cheat sheet · Advanced Routing & Modern Features · verified Jul 2026

instrumentation.ts

Hook into the Node/edge runtime — register OTel, init clients, log errors

typescript

// instrumentation.ts  (project root, sibling to next.config.ts)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }
}

export async function onRequestError(
  err: unknown,
  request: { path: string; method: string },
  context: { routerKind: 'Pages Router' | 'App Router' }
) {
  await fetch('https://logs.example.com/ingest', {
    method: 'POST',
    body: JSON.stringify({ err: String(err), request, context }),
  })
}

💡 register() runs once per process — perfect for OTel/Sentry/DB warmup

📌 onRequestError catches unhandled errors across RSC, actions, handlers, middleware

⚡ Split Node vs Edge with NEXT_RUNTIME for runtime-specific deps

🎯 Pair with `@vercel/otel` for a one-line OpenTelemetry setup

observabilitymodern

More Next.js tasks

Back to the full Next.js cheat sheet