instrumentation.tsによるOpenTelemetryトレーシング

OpenTelemetry (OTel) is a vendor-neutral observability framework that produces traces, metrics, and logs from your application. A trace records the full journey of a single request — from the edge, through Server Components, Server Actions, and database calls — as a tree of spans.

Next.js 15 has built-in, first-class support for OTel via the instrumentation.ts hook. This means you get automatic span creation for:

• App Router page and layout renders
• Route Handler HTTP requests
• Server Actions invocations
• Fetch calls made inside server code

Without tracing you can only guess where latency hides. With tracing you see the exact span — and its duration — that is slow.

Before instrumentation.ts is picked up, you must opt in. In Next.js 15 the flag is stable, but the config key is still required for older 14-compat setups. Add it to your config:

The file next.config.ts is the TypeScript-native config introduced in Next.js 15. The experimental.instrumentationHook key tells the framework to import instrumentation.ts once when the Node.js server boots — before any request is handled.

After adding this flag, create instrumentation.ts in the project root (same level as app/, not inside it).

The OTel ecosystem is split into many small packages. For a Next.js setup you need:

• @opentelemetry/sdk-node — the Node.js SDK that wires everything together
• @opentelemetry/auto-instrumentations-node — auto-instruments http, fetch, dns, and popular libraries without manual code
• @opentelemetry/exporter-trace-otlp-http — exports spans over OTLP/HTTP to a collector (Jaeger, Grafana Tempo, Honeycomb, Datadog, etc.)
• @opentelemetry/resources and @opentelemetry/semantic-conventions — describe your service with standard attribute names

Install them all as production dependencies:

instrumentation.ts must export a named async function called register(). Next.js calls it exactly once when the server process starts.

Key rules:

• The file runs in the Node.js runtime only — not in the Edge runtime or the browser.
• Use process.env.NEXT_RUNTIME === 'nodejs' to guard Node-only imports, because Next.js may import the file in other runtimes during analysis.
• SDK initialisation must complete synchronously or before the first request — register() is awaited by the framework.

By convention, the heavy setup lives in a separate file instrumentation.node.ts that is only ever imported inside the Node runtime guard. This keeps your bundle clean.

The NodeSDK class from @opentelemetry/sdk-node is the main entry point. You pass it:

• A resource — metadata about your service (name, version, environment)
• A trace exporter — where spans are sent
• Optional instrumentations — auto-instrument libraries automatically

Call sdk.start() to activate. Register a SIGTERM handler to flush in-flight spans before the process exits.

Once the SDK is running, Next.js 15 emits spans automatically for every server-side operation. You do not write any tracing code in your components. The built-in spans include:

• BaseServer.handleRequest — top-level span for every HTTP request
• NextNodeServer.findPageComponents — span for resolving which page/layout to render
• AppRender.getBodyResult — span covering React server rendering
• AppRouteRouteHandler.runHandler — span wrapping a Route Handler
• Nested fetch spans — each fetch() call in server code becomes a child span with URL, method, and status

These spans are automatically linked as a parent-child tree so you can see the full call graph in your tracing UI (Jaeger, Grafana Tempo, Honeycomb, etc.).

Auto-instrumentation covers HTTP and fetch. For your own business logic — such as a slow database query helper or a complex computation — you create custom spans using @opentelemetry/api.

The pattern is always:

1. Get the global tracer: trace.getTracer('your-scope-name')
2. Call tracer.startActiveSpan('span-name', async (span) => { ... })
3. Set attributes on the span for searchable metadata
4. Always call span.end() in a finally block

Custom spans automatically become children of the currently active span, so they nest correctly in the trace tree.

Server Actions run on the server and are wrapped by Next.js in their own HTTP lifecycle. You can add custom spans inside a Server Action just as you would in any server function — the active span context is propagated automatically.

This example creates a span around the database write so you can see separately how long validation took versus the actual INSERT:

When your Next.js server calls an external microservice with fetch(), OTel should inject W3C Trace Context headers (traceparent, tracestate) so the downstream service's spans appear as children in the same trace.

With getNodeAutoInstrumentations() enabled, the @opentelemetry/instrumentation-undici or @opentelemetry/instrumentation-http package handles this automatically for fetch and http calls. You do not need to manually add headers.

To verify propagation is working, inspect the outgoing request headers — you should see:

• traceparent: 00-<traceId>-<spanId>-01
• The receiving service must also run OTel and read these headers (W3C standard).

The OTel SDK respects the standard OTel environment variables, which means you rarely need to hard-code endpoints in code. Set these in .env.local (development) and your hosting platform's env config (production):

• OTEL_SERVICE_NAME — identifies your service in the tracing UI
• OTEL_EXPORTER_OTLP_ENDPOINT — the collector URL (e.g. http://localhost:4318 for a local Jaeger all-in-one)
• OTEL_TRACES_SAMPLER — e.g. parentbased_traceidratio to sample only a fraction of traces in production
• OTEL_TRACES_SAMPLER_ARG — e.g. 0.1 to sample 10% of traces

For Vercel, install the Vercel OTel integration or use @vercel/otel which wraps the SDK and reads these same env vars from the Vercel dashboard.

Vercel provides @vercel/otel, a thin wrapper around the OTel SDK optimised for Next.js deployments. It reduces boilerplate to a single registerOTel() call and handles Edge runtime compatibility automatically.

When deploying to Vercel, this is the recommended approach. For self-hosted or Docker deployments, the manual NodeSDK setup from earlier scenes gives you more control.

Both approaches produce identical spans — the difference is only in setup complexity and Edge support.

In this lesson you learned how to bring production-grade distributed tracing to a Next.js 15 App Router application:

• Enable the hook — set experimental.instrumentationHook: true in next.config.ts (stable default in Next.js 15).
• Create instrumentation.ts — export a register() function at the project root; use it as the single entry point for all server-side initialisation.
• Guard the runtime — wrap Node.js-only imports with process.env.NEXT_RUNTIME === 'nodejs' and use dynamic import() to prevent Edge bundling.
• Initialise NodeSDK in a separate instrumentation.node.ts — provide a Resource, an OTLPTraceExporter, and auto-instrumentations; call sdk.start() once.
• Automatic spans — Next.js emits spans for page renders, Route Handlers, Server Actions, and fetch calls with no extra code.
• Custom spans — use trace.getTracer() and startActiveSpan() from @opentelemetry/api to instrument your own business logic.
• Context propagation — W3C traceparent headers are injected automatically into outgoing fetch calls by auto-instrumentation.
• Configuration — standard OTEL_* env vars drive the SDK; no need to hard-code collector URLs in source code.