instrumentation.ts is stable in Next.js 16, but it became stable in Next.js 15.0.0. Put the file at the project root or in src, export an asynchronous-capable register() function, and initialize telemetry there before the server handles requests. Use @vercel/otel for the documented quick start and Edge support; manual NodeSDK setup is for Node.js runtime deployments. You can create custom spans directly in application code—there is no need to wrap every function.
Is instrumentation.ts stable in Next.js 16?
Yes. The convention is stable in Next.js 16, but it was not introduced as stable in that release: the Next.js instrumentation API reference says it was introduced experimentally in 13.2.0 and became stable in 15.0.0. Next.js 16 inherits that stable convention.
As an Amazon Associate I earn from qualifying purchases.
Where does instrumentation.ts go?
Create it at the project root, or inside src alongside your app and pages directories. Do not put it inside app or pages. If your project changes the default pageExtensions suffix convention, name the instrumentation file to match it. The API reference also defines the registration lifecycle: Next.js calls the exported register() once when a new server instance starts, and waits for it to finish before handling requests. It may be asynchronous.
How do I set up OpenTelemetry in Next.js?
Next.js recommends OpenTelemetry and documents @vercel/otel as the quick-start option. The lifecycle is: place the file, export register(), check the runtime, lazily import the matching setup, initialize the provider, then add spans in the application where useful.
#1 Best Overall
Quick start with @vercel/otel
The Next.js OpenTelemetry guide lists @vercel/otel, @opentelemetry/sdk-logs, @opentelemetry/api-logs, and @opentelemetry/instrumentation as dependencies for its documented setup. Its registration pattern is:
// instrumentation.ts (or src/instrumentation.ts)
export async function register() {
const { registerOTel } = await import('@vercel/otel')
registerOTel({ serviceName: 'next-app' })
}Because Next.js invokes registration in all environments, keep runtime-specific imports inside register() and use process.env.NEXT_RUNTIME when setup differs. This avoids loading a Node-only SDK in an Edge environment and keeps side effects out of module-level initialization. The instrumentation API reference explicitly documents using this runtime variable to target a specific runtime.
Manual NodeSDK setup
Choose manual configuration when you need more control over the provider and exporters than the common @vercel/otel path offers. The Next.js guide demonstrates a NodeSDK with an OTLP HTTP trace exporter, a service-name resource, and a span processor. Keep that initialization in a Node-only module and load it conditionally:
// instrumentation.ts
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation.node')
}
}Initialize the SDK in instrumentation.node using the exporter endpoint and resource settings appropriate to your telemetry backend; the exact values depend on that backend. The Next.js guide states that NodeSDK is not Edge compatible. If your deployment needs Edge runtime support, use the documented @vercel/otel route instead. See the OpenTelemetry guide for the manual configuration pattern and runtime caveat.
| Approach | Configuration | Customization | Runtime support |
|---|---|---|---|
@vercel/otel |
Quick-start route for common use cases | Less low-level setup than configuring the SDK directly | The Next.js guide points to it when Edge support is needed |
Manual NodeSDK |
Configure SDK, exporter, resource, and span processor | Allows additional customization | Node.js only; the Next.js guide says it is not Edge compatible |
How do I add a custom OpenTelemetry span?
Next.js creates framework spans when OpenTelemetry is enabled. Add application spans around operations whose timing or context is meaningful, using @opentelemetry/api and an active span. Always end the span in finally, so it is closed whether the operation succeeds or throws.
import { trace } from '@opentelemetry/api'
const tracer = trace.getTracer('my-app')
export async function loadAccount(accountId: string) {
return tracer.startActiveSpan('load-account', async (span) => {
try {
span.setAttribute('account.id', accountId)
return await fetchAccount(accountId)
} catch (error) {
span.recordException(error as Error)
throw error
} finally {
span.end()
}
})
}Use attributes that help explain the operation without exposing secrets or sensitive personal data. The Next.js guide says spans created after registration should be included in exported traces. There is no requirement to add a wrapper around every application function: instrument the operations where a distinct timing or trace context helps diagnose behavior.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Can I use Sentry spans with Next.js?
Sentry provides its own Sentry.startSpan(...) API for creating dedicated spans and supports adding attributes to an active span. Its custom instrumentation guidance warns that dedicated spans can add noise to a trace waterfall, so reserve them for work that benefits from a separate trace segment.
Recommended Free Tools
That guidance is generic Sentry documentation, not a verified Next.js 16 initialization recipe. The current Next.js-specific Sentry setup is not established here, so use Sentry’s current Next.js documentation for its SDK initialization rather than copying an assumed setup into register(). OpenTelemetry initialization and Sentry initialization are distinct choices; do not assume configuring one automatically configures the other.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
