Next.js 16+ · Directive

instrumentation

Next.js instrumentation runs server-startup code for observability and logging. Export register from a root-level instrumentation.ts/js file, or from src when using that layout.

How it works

Next.js discovers an instrumentation.ts or instrumentation.js file at the project root, or alongside app and pages in src. It invokes the exported register function once when each server instance starts and waits for it to finish before accepting requests. Use this hook to initialize monitoring, logging, or other server-startup integrations; inspect NEXT_RUNTIME when setup differs between Node.js and Edge.

Syntax

export async function register(): Promise<void> { /* initialization */ }

Key points

Use the convention to connect observability libraries, logging systems, or monitoring services to the application.
The recognized file is named instrumentation.ts or instrumentation.js and normally lives at the project root.
With a src layout, put the file directly in src beside app and pages.
The file needs a named register export for startup initialization.
Each newly initiated server instance invokes register once.
The server waits for register to complete before it becomes ready for requests.

Common mistakes

Do not place the file inside app or pages; use the project root, or src alongside those directories.
Keep startup work deliberate: register must finish before the server handles requests.

Example: instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node')
  }
}

Create this file at the project root, or in src when that folder is used.

When to use it

Observability startup

Initialize tracing or metrics providers before requests are served.

Startup logging

Configure structured server logging during application boot.

Runtime-specific setup

Load different integrations for Node.js and Edge deployments.

Interview questions

QHow do you enable server-startup instrumentation in an App Router project?

Create instrumentation.ts or instrumentation.js in the project root, or in src when using that folder. Export register; Next.js calls it once as each server instance starts and waits for completion before serving requests.

Follow-up: How can startup code select a runtime? Check process.env.NEXT_RUNTIME and conditionally initialize Node.js- or Edge-specific integrations.

QWhat is the purpose of the register function?

The register hook is intended for integrating monitoring and logging tools. Initialization belongs in the hook so it runs during server startup rather than per request.

Follow-up: How would you add OpenTelemetry? Initialize the provider or SDK from instrumentation.ts, using the dedicated OpenTelemetry guidance for the integration details.

QWhere must the instrumentation file be placed?

The convention is instrumentation.ts or instrumentation.js at the root of the application, with src as the alternative location when that directory is used. It must not be nested under app or pages.

Follow-up: What should be checked if the hook is not discovered? Verify the filename, directory, and that register is exported from the file.

register
onRequestError
process.env.NEXT_RUNTIME
OpenTelemetry
instrumentation-client.js|ts

Source: Instrumentation. Checked 2026-10-15.