Route your existing OpenTelemetry traces to Sentry with Next.js
Keep your vendor-neutral OpenTelemetry instrumentation and start seeing your Next.js traces in Sentry. No SDK migration required.
Before you start
SDKs & packages
- A Next.js app (v13.4+) with OpenTelemetry instrumentation already set up
- Node.js 18+
Accounts & access
- Sentry account with a project created
Knowledge
- Basic familiarity with Next.js
- Basic understanding of what OpenTelemetry traces are
1 Get your Sentry OTLP credentials
Sentry exposes a standard OTLP endpoint for each project. Open your project in Sentry, go to Settings > Client Keys (DSN) and switch to the OpenTelemetry tab. Copy both values below and paste them into your environment variables in Step 2:
- The Traces endpoint URL, which looks like
https://o{ORG_ID}.ingest.us.sentry.io/api/{PROJECT_ID}/integration/otlp/v1/traces - Your public key, the value after
sentry_key=in the DSN
2 Set your environment variables
Add these three variables to your .env.local. Substitute the endpoint URL and public key you copied in Step 1.
The OTEL_EXPORTER_OTLP_TRACES_HEADERS value is a full header string. The key is x-sentry-auth and the value is sentry sentry_key=. Most OTLP exporters parse this format automatically.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://o{ORG_ID}.ingest.us.sentry.io/api/{PROJECT_ID}/integration/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-sentry-auth=sentry sentry_key={YOUR_PUBLIC_KEY}
OTEL_SERVICE_NAME=my-nextjs-app
3 Enable the instrumentation hook
In Next.js 15+, the instrumentation.ts file is picked up automatically. If you're on Next.js 13 or 14, add the instrumentationHook experimental flag to your config to opt in.
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
instrumentationHook: true,
},
}
module.exports = nextConfig
4 Verify your traces in Sentry
Start your dev server and trigger a few requests (page loads, API routes, or server actions). Within 30–60 seconds, your traces should appear in Sentry.
Open the Trace Explorer and filter by your service name (my-nextjs-app or whatever you set in OTEL_SERVICE_NAME). You'll see a waterfall view of your spans: Next.js routes, fetch calls, database queries, and anything else your auto-instrumentation captures.
That's it.
Your traces are in Sentry.
Two environment variables is all it took. Your OpenTelemetry instrumentation is still vendor-neutral, and Sentry is now your observability backend.
- Located your Sentry OTLP credentials
- Pointed your existing OTel traces at Sentry using environment variables
- Verified spans flowing into the Sentry Trace Explorer
Pro tips
- 💡 Set
OTEL_SERVICE_NAMEto something distinct per service. It's how Sentry groups spans in the Trace Explorer and makes multi-service traces readable at a glance. - 💡 If you're using
@vercel/otel, addNEXT_OTEL_VERBOSE=1during development to log every span to the console and confirm your instrumentation is working before checking Sentry. - 💡 If you're already exporting to another observability backend, you can run a second exporter in parallel using the manual
NodeSDKsetup. No need to pick one or the other.
Common pitfalls
- ⚠️ If your
instrumentation.tsfile isn't being picked up, check that it's in the project root orsrc/folder. Next.js won't load it from insideapp/orpages/. - ⚠️ The
@opentelemetry/sdk-nodepackage (and@vercel/otel) doesn't run in the Edge Runtime. If your app uses edge routes, guard withif (process.env.NEXT_RUNTIME === 'nodejs')before registering the SDK. - ⚠️ A wrong authentication header format is the most common cause of 401 errors from the Sentry OTLP endpoint. The full header value must be
sentry sentry_key={YOUR_KEY}, not just the key alone.
Frequently asked questions
@sentry/* package. That said, pairing OTLP traces with the Sentry SDK gives you error monitoring, session replay, and richer context on your traces.instrumentation.ts and an OTLP exporter configured, all you need to do is update OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_HEADERS to point at Sentry. No code changes required.NodeSDK setup (instead of @vercel/otel), you can add multiple span processors with different exporters: one pointing at Sentry and one at your existing backend. This is a low-risk way to evaluate Sentry without committing to a full migration.instrumentation.ts file and OTLP configuration work with both routing strategies. Next.js auto-instruments server components, API routes, and server actions regardless of which router you use.What's next?
Fix it, don't observe it.
Get started with the only application monitoring platform that empowers developers to fix application problems without compromising on velocity.