How do you handle instrumentation and observability in Next.js (instrumentation.ts)?

Q: How do you handle instrumentation and observability in Next.js (instrumentation.ts)?

**Target Audience:** Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. **Difficulty:** Hard > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the **Verified** section, against real output from a build or a running server; each Verified block says which version it ran on. ## 1. Why This Even Matters — A Story First Observability is the flight recorder of an aircraft. register() switches the recorder on before takeoff, once. onRequestError is the incident log: every time something fails, it records what, where and when, with a reference number that matches the note the passengers were given (the digest shown in the browser). ## 2. The Core Idea 📌 **Interview term: register()** — the instrumentation.ts export Next.js calls once pe

The problem

Question presented to candidate: "How would you add tracing and error reporting to a Next.js app, and which hooks does Next.js give you for that?"

What a strong answer should cover:

instrumentation.ts at the project root exports register(), called once when a server instance starts, before it handles requests; use it to set up OpenTelemetry or an error SDK.
It also exports onRequestError(error, request, context), called for errors during rendering, Route Handlers, Server Actions and Proxy, with the path and route type.
The error digest matches the one sent to the browser, so client reports and server logs can be joined.
instrumentation-client.ts runs in the browser before the app becomes interactive; only its synchronous top-level code is guaranteed to run before hydration.
Next.js emits OpenTelemetry spans for rendering and fetch; @vercel/otel or the OpenTelemetry SDK exports them.

Clarifying questions expected:

"Which vendor or collector?" — OpenTelemetry keeps you vendor-neutral.
"Do you need to correlate browser errors with server logs?" — use the digest.

Code / implementation expected: Yes — both hooks, and client instrumentation.

nextjs
instrumentation
observability
opentelemetry

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. Difficulty: Hard

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the Verified section, against real output from a build or a running server; each Verified block says which version it ran on.

1. Why This Even Matters — A Story First

Observability is the flight recorder of an aircraft. register() switches the recorder on before takeoff, once. onRequestError is the incident log: every time something fails, it records what, where and when, with a reference number that matches the note the passengers were given (the digest shown in the browser).

2. Th

The solution is hidden so you can try first

4 min read · 8 sections

Read the code

OpenTelemetry setup and error reporting

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerOTel } = await import("@vercel/otel");
    registerOTel({ serviceName: "shop-web" });
  }
}

export async function onRequestError(
  err: unknown,
  request: { path: string; method: string },
  context: { routePath: string; routeType: string },
) {
  const e = err as Error & { digest?: string };
  await fetch("https://errors.example.com/ingest", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ message: e.message, digest: e.digest, path: request.path, route: context.routePath, type: context.routeType }),
  });
}

// instrumentation-client.ts (browser)
performance.mark("app-init");
window.addEventListener("error", (event) => navigator.sendBeacon("/api/client-errors", String(event.message)));

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.