Skip to content

Commit daca0a0

Browse files
andreiborzaclaude
andreiborza
and
claude
authored
feat!: Replace skipOpenTelemetrySetup with enableOpenTelemetrySetup (#23199)
## What Replace the `skipOpenTelemetrySetup` option with `enableOpenTelemetrySetup: boolean` (inverted meaning, per-package behavior unchanged). * `@sentry/node`, `@sentry/cloudflare`: defaults to `false` (no Sentry tracer provider)exit * `@sentry/nextjs`, `@sentry/sveltekit`: pass `true` since they own OTel spans by default * `@sentry/deno`, `@sentry/vercel-edge`: keep OTel setup on by default, so the flag defaults to `true` there * Migration docs updated to document the rename; historical v8/v9 docs and changelog left untouched ## Why Since v11 most server SDKs no longer set up OpenTelemetry by default, so the option is now an opt-in and a positive `enable` flag reads clearer than the double negative `skip: false`. The nextjs tunnel-drop check only bails on an explicit `false` so edge clients without the merged node default keep processing spans as before. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 1439ed3 commit daca0a0

30 files changed

Lines changed: 81 additions & 76 deletions

File tree

‎MIGRATION.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ If you only use the Sentry SDK, day-to-day tracing remains **unchanged**.
8484

8585
#### Choosing an OpenTelemetry setup
8686

87-
There are three ways to run the Sentry and OpenTelemetry SDKs together, and which one you want depends on who should own spans. This is controlled by the existing `skipOpenTelemetrySetup` option, whose default was flipped in v11: it is now `true` for most server SDKs (including `@sentry/node`, `@sentry/bun`, the serverless SDKs and `@sentry/cloudflare`) and `false` for `@sentry/nextjs` and `@sentry/sveltekit`.
87+
There are three ways to run the Sentry and OpenTelemetry SDKs together, and which one you want depends on who should own spans. This is controlled by the new `enableOpenTelemetrySetup` option, which replaces v10's `skipOpenTelemetrySetup` with inverted meaning (`skipOpenTelemetrySetup: true` becomes `enableOpenTelemetrySetup: false`). It defaults to `false` for most server SDKs (including `@sentry/node`, `@sentry/bun`, the serverless SDKs and `@sentry/cloudflare`) and `true` for `@sentry/nextjs` and `@sentry/sveltekit`.
8888

8989
##### 1. Sentry only
9090

@@ -101,13 +101,13 @@ If a library you depend on emits its own OpenTelemetry spans and you want those
101101

102102
##### 2. OpenTelemetry-compatible mode, everything goes to Sentry
103103

104-
Set `skipOpenTelemetrySetup: false`:
104+
Set `enableOpenTelemetrySetup: true`:
105105

106106
```js
107107
Sentry.init({
108108
dsn: '__DSN__',
109109
tracesSampleRate: 1.0,
110-
skipOpenTelemetrySetup: false,
110+
enableOpenTelemetrySetup: true,
111111
});
112112
```
113113

@@ -117,7 +117,7 @@ Spans go to Sentry. This is not a general OpenTelemetry pipeline: there is no ex
117117

118118
##### 3. Your own OpenTelemetry, Sentry linked to it
119119

120-
Leave `skipOpenTelemetrySetup` unset or set it to `true`, turn Sentry tracing off, use your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`:
120+
Leave `enableOpenTelemetrySetup` unset or set it to `false`, turn Sentry tracing off, use your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`:
121121

122122
```js
123123
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
@@ -138,7 +138,7 @@ Sentry.init({
138138
});
139139
```
140140

141-
`skipOpenTelemetrySetup` already defaults to `true` on most server SDKs, so there is nothing to set. On `@sentry/nextjs` and `@sentry/sveltekit` it defaults to `false`, so you have to set it explicitly. Otherwise Sentry registers its own tracer provider and you end up in setup 2 rather than this one.
141+
`enableOpenTelemetrySetup` already defaults to `false` on most server SDKs, so there is nothing to set. On `@sentry/nextjs` and `@sentry/sveltekit` it defaults to `true`, so you have to set it to `false` explicitly. Otherwise Sentry registers its own tracer provider and you end up in setup 2 rather than this one.
142142

143143
OpenTelemetry owns spans end to end. Sentry captures errors and logs, and the Sentry `otlpIntegration()` attaches them to the active OpenTelemetry span so all your telemetry is connected in one trace. `getOtlpTracesEndpoint()` turns your DSN into the URL and auth headers for Sentry's OTLP endpoint, so you can point your own exporter at Sentry, at your own collector, or at both.
144144

@@ -148,7 +148,7 @@ Sentry does not touch your pipeline: no exporter, no span processor, no tracer p
148148

149149
Sentry instruments many of the same libraries OpenTelemetry does (Express, Postgres, Redis, Prisma, Kafka and so on), so enabling Sentry tracing on top of your own instrumentation gives you two spans for every operation. Leave `tracesSampleRate` in your `Sentry.init` unset to avoid duplicate spans. With tracing off, Sentry's instrumentation stays installed and keeps isolating requests, but emits no spans.
150150

151-
Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `skipOpenTelemetrySetup`.
151+
Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `enableOpenTelemetrySetup`.
152152

153153
If you do want Sentry spans alongside your own, keep `tracesSampleRate` set and drop the integrations that overlap. HTTP and fetch are the exception: turn off only their spans, because `httpIntegration` also provides request isolation, request data and session tracking:
154154

‎dev-packages/cloudflare-integration-tests/suites/tracing/vercelai/v6/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export default Sentry.withSentry(
1313
tracesSampleRate: 1,
1414
// The Vercel AI SDK emits its spans through `@opentelemetry/api`, so they are only picked up when
1515
// the Cloudflare OpenTelemetry tracer provider is set up.
16-
skipOpenTelemetrySetup: false,
16+
enableOpenTelemetrySetup: true,
1717
}),
1818
{
1919
async fetch(_request, _env, _ctx) {

‎dev-packages/e2e-tests/test-applications/nestjs-basic/src/instrument.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,5 @@ Sentry.init({
1212
},
1313
// Opt into the Sentry OpenTelemetry tracer provider in the "(tracer provider)" e2e variant.
1414
// Leaving it `undefined` otherwise keeps the SDK's default (no provider).
15-
skipOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? false : undefined,
15+
enableOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? true : undefined,
1616
});

‎dev-packages/e2e-tests/test-applications/node-express/src/app.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Sentry.init({
1616
tracesSampleRate: 1,
1717
// Opt into the Sentry OpenTelemetry tracer provider in the "(tracer provider)" e2e variant.
1818
// Leaving it `undefined` otherwise keeps the SDK's default (no provider).
19-
skipOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? false : undefined,
19+
enableOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? true : undefined,
2020
integrations: [
2121
Sentry.nativeNodeFetchIntegration({
2222
headersToSpanAttributes: {

‎dev-packages/e2e-tests/test-applications/node-fastify-5/src/app.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Sentry.init({
4040
tracePropagationTargets: ['http://localhost:3030', '/external-allowed'],
4141
// Opt into the Sentry OpenTelemetry tracer provider in the "(tracer provider)" e2e variant.
4242
// Leaving it `undefined` otherwise keeps the SDK's default (no provider).
43-
skipOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? false : undefined,
43+
enableOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? true : undefined,
4444
});
4545

4646
import type * as H from 'http';

‎dev-packages/e2e-tests/test-applications/nuxt-4/sentry.server.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ Sentry.init({
77
tunnel: 'http://localhost:3031/', // proxy server
88
// Opt into the Sentry OpenTelemetry tracer provider in the "(tracer provider)" e2e variant.
99
// Leaving it `undefined` otherwise keeps the SDK's default (no provider).
10-
skipOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? false : undefined,
10+
enableOpenTelemetrySetup: process.env.E2E_TEST_OTEL_SETUP === 'true' ? true : undefined,
1111
});

‎dev-packages/node-integration-tests/suites/tracing/tracer-start-active-span-error/instrument.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,5 @@ Sentry.init({
88
transport: loggingTransport,
99
// This suite drives the raw OpenTelemetry tracer (`client.tracer.startActiveSpan`), which only
1010
// produces spans when Sentry owns the tracer provider.
11-
skipOpenTelemetrySetup: false,
11+
enableOpenTelemetrySetup: true,
1212
});

‎docs/migration/v11-end-state.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ If you only use the Sentry SDK, day-to-day tracing remains **unchanged**.
8888

8989
#### Choosing an OpenTelemetry setup
9090

91-
There are three ways to run the Sentry and OpenTelemetry SDKs together, and which one you want depends on who should own spans. This is controlled by the existing `skipOpenTelemetrySetup` option, whose default was flipped in v11: it is now `true` for most server SDKs (including `@sentry/node`, `@sentry/bun`, the serverless SDKs and `@sentry/cloudflare`) and `false` for `@sentry/nextjs` and `@sentry/sveltekit`.
91+
There are three ways to run the Sentry and OpenTelemetry SDKs together, and which one you want depends on who should own spans. This is controlled by the new `enableOpenTelemetrySetup` option, which replaces v10's `skipOpenTelemetrySetup` with inverted meaning (`skipOpenTelemetrySetup: true` becomes `enableOpenTelemetrySetup: false`). It defaults to `false` for most server SDKs (including `@sentry/node`, `@sentry/bun`, the serverless SDKs and `@sentry/cloudflare`) and `true` for `@sentry/nextjs` and `@sentry/sveltekit`.
9292

9393
##### 1. Sentry only
9494

@@ -105,13 +105,13 @@ If a library you depend on emits its own OpenTelemetry spans and you want those
105105

106106
##### 2. OpenTelemetry-compatible mode, everything goes to Sentry
107107

108-
Set `skipOpenTelemetrySetup: false`:
108+
Set `enableOpenTelemetrySetup: true`:
109109

110110
```js
111111
Sentry.init({
112112
dsn: '__DSN__',
113113
tracesSampleRate: 1.0,
114-
skipOpenTelemetrySetup: false,
114+
enableOpenTelemetrySetup: true,
115115
});
116116
```
117117

@@ -121,7 +121,7 @@ Spans go to Sentry. This is not a general OpenTelemetry pipeline: there is no ex
121121

122122
##### 3. Your own OpenTelemetry, Sentry linked to it
123123

124-
Leave `skipOpenTelemetrySetup` unset or set it to `true`, turn Sentry tracing off, use your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`:
124+
Leave `enableOpenTelemetrySetup` unset or set it to `false`, turn Sentry tracing off, use your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`:
125125

126126
```js
127127
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
@@ -142,7 +142,7 @@ Sentry.init({
142142
});
143143
```
144144

145-
`skipOpenTelemetrySetup` already defaults to `true` on most server SDKs, so there is nothing to set. On `@sentry/nextjs` and `@sentry/sveltekit` it defaults to `false`, so you have to set it explicitly. Otherwise Sentry registers its own tracer provider and you end up in setup 2 rather than this one.
145+
`enableOpenTelemetrySetup` already defaults to `false` on most server SDKs, so there is nothing to set. On `@sentry/nextjs` and `@sentry/sveltekit` it defaults to `true`, so you have to set it to `false` explicitly. Otherwise Sentry registers its own tracer provider and you end up in setup 2 rather than this one.
146146

147147
OpenTelemetry owns spans end to end. Sentry captures errors and logs, and the Sentry `otlpIntegration()` attaches them to the active OpenTelemetry span so all your telemetry is connected in one trace. `getOtlpTracesEndpoint()` turns your DSN into the URL and auth headers for Sentry's OTLP endpoint, so you can point your own exporter at Sentry, at your own collector, or at both.
148148

@@ -152,7 +152,7 @@ Sentry does not touch your pipeline: no exporter, no span processor, no tracer p
152152

153153
Sentry instruments many of the same libraries OpenTelemetry does (Express, Postgres, Redis, Prisma, Kafka and so on), so enabling Sentry tracing on top of your own instrumentation gives you two spans for every operation. Leave `tracesSampleRate` in your `Sentry.init` unset to avoid duplicate spans. With tracing off, Sentry's instrumentation stays installed and keeps isolating requests, but emits no spans.
154154

155-
Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `skipOpenTelemetrySetup`.
155+
Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `enableOpenTelemetrySetup`.
156156

157157
If you do want Sentry spans alongside your own, keep `tracesSampleRate` set and drop the integrations that overlap. HTTP and fetch are the exception: turn off only their spans, because `httpIntegration` also provides request isolation, request data and session tracking:
158158

‎packages/cloudflare/src/baseSdk.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ export function initWithDefaultIntegrations(
9696
transport: options.transport || makeCloudflareTransport,
9797
// Like most Node-based SDKs, Cloudflare defaults to running without a Sentry OpenTelemetry tracer
9898
// provider. Scope isolation is handled by the entrypoint wrappers' AsyncLocalStorage strategy.
99-
skipOpenTelemetrySetup: options.skipOpenTelemetrySetup ?? true,
99+
enableOpenTelemetrySetup: options.enableOpenTelemetrySetup ?? false,
100100
flushLock,
101101
};
102102

@@ -110,9 +110,9 @@ export function initWithDefaultIntegrations(
110110
}
111111
/*! rollup-include-development-only-end */
112112

113-
// Opt-in only: when `skipOpenTelemetrySetup` is `false`, set up a custom trace provider so spans
113+
// Opt-in only: when `enableOpenTelemetrySetup` is `true`, set up a custom trace provider so spans
114114
// emitted via `@opentelemetry/api` are captured by Sentry. See the option's docs for the caveats.
115-
if (!clientOptions.skipOpenTelemetrySetup) {
115+
if (clientOptions.enableOpenTelemetrySetup) {
116116
setupOpenTelemetryTracer();
117117
}
118118

‎packages/cloudflare/src/client.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -175,17 +175,17 @@ interface BaseCloudflareOptions {
175175
enableDedupe?: boolean;
176176

177177
/**
178-
* The Cloudflare SDK is not OpenTelemetry native. By default (`true`) it does not set up a tracer
178+
* The Cloudflare SDK is not OpenTelemetry native. By default (`false`) it does not set up a tracer
179179
* provider; spans are emitted via the SDK's own instrumentation and scopes are isolated with
180180
* AsyncLocalStorage.
181181
*
182-
* Set this to `false` to opt into the OpenTelemetry compatibility tracer, which captures spans
182+
* Set this to `true` to opt into the OpenTelemetry compatibility tracer, which captures spans
183183
* emitted via `@opentelemetry/api`. Big caveat: it does not handle custom context, always working
184184
* off the current scope. This is good enough for many, but not all, integrations.
185185
*
186-
* @default true
186+
* @default false
187187
*/
188-
skipOpenTelemetrySetup?: boolean;
188+
enableOpenTelemetrySetup?: boolean;
189189

190190
/**
191191
* Enable trace propagation for RPC calls between Workers, Durable Objects, and Service Bindings.

0 commit comments

Comments
 (0)