instrumentation.js (or .ts) sits at the project root, or in src/, not inside app/. It is the one place Next.js calls into at the server level rather than per route.
register() runs once when a server instance starts, and per the docs must finish before requests are handled. That's where OpenTelemetry (@vercel/otel or the Node SDK) or an error tracker is initialised. On Next.js 16.4.5, next start logged it at boot with no request made, and again after each restart; next build never called it. It runs per runtime: with an Edge middleware.js present, a second register logged edge on the first request that middleware handled. The file is bundled for both runtimes, so Node-only imports go behind process.env.NEXT_RUNTIME === 'nodejs' and a dynamic import().
onRequestError(error, request, context) (since 15.0) is called when the server catches an error while handling a request:
error: the thrown value; render and action errors carry adigest, the id the client gets instead of the message.request:{ path, method, headers }, wherepathincludes the query string.context:routerKind,routePath(the route file's path),routeType(render,route,actionorproxy),revalidateReason, and for rendersrenderSource. The docs also listrenderType; none of my errors carried it.
It is a reporting hook only: it can't change the response, and it runs on the server, so Client Component errors in the browser need a client-side reporter.
Two gaps I observed: errors thrown in a Node.js proxy.js never reached it (an Edge middleware.js error did, as routeType: "proxy"), and neither did a throwing after() callback. Both were only printed to the server log.