OpenTelemetry Tracing with instrumentation.ts
Register OpenTelemetry via the instrumentation hook to trace server requests and spans.
What Is OpenTelemetry and Why Next.js Needs It
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.
Enabling the Instrumentation Hook in next.config.ts
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).
// next.config.ts
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
experimental: {
// Required in Next.js 14; stable & default-true in Next.js 15
// but explicit opt-in avoids version ambiguity
instrumentationHook: true,
},
};
export default nextConfig;All lessons in this course
- OpenTelemetry Tracing with instrumentation.ts
- Granular error.tsx and global-error Boundaries
- Structured Logging Across Server and Edge
- Capturing Server Action Failures and Telemetry