chore: Document the three OpenTelemetry setups in the migration guide - #23149
Merged
Conversation
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
andreiborza
force-pushed
the
ab/document-otel-setups
branch
from
August 7, 2026 12:31
e0e630c to
d28ed78
Compare
andreiborza
marked this pull request as ready for review
August 7, 2026 12:45
nicohrubec
reviewed
Aug 7, 2026
nicohrubec
left a comment
nicohrubec
left a comment
Member
There was a problem hiding this comment.
thanks for doing this, got a few comments but mostly suggestions
Co-authored-by: Nicolas Hrubec <nicolas.hrubec@outlook.com>
chargome
approved these changes
Aug 7, 2026
chargome
left a comment
chargome
left a comment
Member
There was a problem hiding this comment.
I'd trim this down generally a bit more, but LGTM otherwise
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Lms24
approved these changes
Aug 7, 2026
Lms24
left a comment
Lms24
left a comment
Member
There was a problem hiding this comment.
Nice, this reads very clearly. I think my main points from the review are:
- we should make it clear at the beginning if a user needs to care about this section or not
- we should be consistent with "you" and "users"
Otherwise LGTM
|
|
||
| ### Better OpenTelemetry interoperability | ||
|
|
||
| Affected SDKs: Server-side SDKs (`@sentry/node` and all dependents). |
Member
There was a problem hiding this comment.
l: Should we add this so that users/agents can quickly spot if this concerns them?
Suggested change
| Affected SDKs: Server-side SDKs (`@sentry/node` and all dependents). **If Sentry is used with a custom OpenTelemetry SDK Setup** |
Member
Author
There was a problem hiding this comment.
No this affects v11 as a whole, not just user's with custom otel setups.
|
|
||
| #### Choosing an OpenTelemetry setup | ||
|
|
||
| There are three ways to run the two 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`. |
Member
There was a problem hiding this comment.
Suggested change
| There are three ways to run the two 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`. | |
| There are three ways to run the Sentry and OTel 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`. |
| This is what `@sentry/nextjs` and `@sentry/sveltekit` do by default, because those frameworks emit OpenTelemetry spans that would otherwise be lost. | ||
|
|
||
| #### Connecting Sentry to your OpenTelemetry traces | ||
| Everything goes to Sentry and only to Sentry. This is not a general OpenTelemetry pipeline: there is no exporter, no OTLP output, and no way to fan spans out to another backend. Sentry also refuses to register its provider if you already registered one of your own, logging a warning instead. If you want a real OpenTelemetry pipeline, use setup 3. |
Member
There was a problem hiding this comment.
very technically, and probably fine to omit here, users could still roll their own transport and fan out to other tracing backends. But I think we discussed this already so probably not worth mentioning here.
Drops the Next.js/SvelteKit note from setup 2, since setup 1 already points readers there when a library emits its own OpenTelemetry spans, and reword setup 3's opening.
Co-authored-by: Nicolas Hrubec <nicolas.hrubec@outlook.com>
Co-authored-by: Charly Gomez <charly.gomez1310@gmail.com>
Co-authored-by: Nicolas Hrubec <nicolas.hrubec@outlook.com>
Co-authored-by: Nicolas Hrubec <nicolas.hrubec@outlook.com>
The option is `tracesSampleRate`.
Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>
Name both SDKs in the intro, and drop the claim that spans cannot be fanned out to another backend, since a custom transport can still do that.
JPeer264
approved these changes
Aug 7, 2026
Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>
nicohrubec
added a commit
that referenced
this pull request
Aug 7, 2026
Merge develop's restructured "Better OpenTelemetry interoperability" section (three named setups, from #23149), remove the trailing TODO(v11) OpenTelemetry guide link for the user-facing alpha, and refresh the end-state copy. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Restructures the "Better OpenTelemetry interoperability" section of the v11 migration guide around the three setups users can actually run, so people can find the one that matches them instead of piecing it together from prose.
@opentelemetry/apispans ignored.skipOpenTelemetrySetup: false): a minimal tracer provider picks up@opentelemetry/apispans and turns them into Sentry spans. Everything goes to Sentry and only to Sentry.otlpIntegration()for trace linking,getOtlpTracesEndpoint()to point your exporter at Sentry.Also adds an "Avoiding duplicate spans" subsection covering what happens when Sentry's instrumentation overlaps with your own, and spells out that the v10 bridge built from
SentryContextManager,SentrySamplerandSentrySpanProcessoris gone.This replaces the prose that previously covered
skipOpenTelemetrySetup, the removed bridge and the HTTP/fetch example, rather than adding alongside it. Everything unique from that block is preserved: the flipped default and per-SDK lists, and the v10 change whereskipOpenTelemetrySetup: trueno longer disables HTTP and fetch spans.Why
The old section explained the mechanism but never said which configuration a given user wants, so the common questions (does Sentry pick up my OpenTelemetry spans, do I get duplicates, where did
SentrySpanProcessorgo) had to be inferred. Naming the three setups makes that a lookup.Note this touches the same region as #23099, which adds its own OTLP integration section, so one of the two will need a rebase.