feat(core): Add deferred segment-span transaction capture#21839
Merged
andreiborza merged 9 commits intoJul 2, 2026
Merged
Conversation
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
size-limit report 📦
|
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
920659d to
1397906
Compare
andreiborza
changed the title
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
a1613c2 to
6bd79ac
Compare
andreiborza
requested review from
JPeer264 and
mydea
and removed request for
a team
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
29ce501 to
c741940
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
2 times, most recently
from
e005612 to
924ce11
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
c741940 to
4b3fc03
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
924ce11 to
630bb67
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
4b3fc03 to
14cb421
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
630bb67 to
15154ed
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
14cb421 to
6b8db6e
Compare
nicohrubec
reviewed
Jun 30, 2026
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
15154ed to
7837eb8
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
6b8db6e to
2df53ad
Compare
Member
Author
|
I'm going to rework this slightly so it has no impact on browser SDKs. |
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
51859a2 to
f25bf84
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
7837eb8 to
97e8266
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
c11b10c to
e7f6447
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
2 times, most recently
from
cfbfb8b to
1c93e34
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
6de76e6 to
f2439e8
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
3 times, most recently
from
220ade4 to
d93efba
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit d93efba. Configure here.
Add per-client deferral of the segment-span transaction capture. The transaction is otherwise assembled synchronously from the live span tree when the root span ends, dropping child spans whose instrumentation closes them after it - in the same tick (diagnostics-channel `asyncEnd`) or on a later tick (e.g. prisma engine spans). When a client opts in via `_INTERNAL_setDeferSegmentSpanCapture`, a debounced timer (the one the OpenTelemetry span exporter uses) delays the snapshot so those children land first, and drains on the client `flush` hook so `Sentry.flush()` / `close()` stays safe. The browser keeps its synchronous capture. The opt-in call is wired separately (the Node SDK enables it on the SentryTracerProvider path).
Extract the defer/orphan machinery (per-client queues, debounced drain, flush wiring, orphan detection, the CAPTURED_SPANS set) out of SentrySpan into a node-only deferSegmentSpanCapture module, registered through a carrier-based strategy seam that mirrors set/getAsyncContextStrategy. SentrySpan reads the seam and captures synchronously when none is registered, so browser bundles that never register the strategy tree-shake the machinery away.
…sion, flush draining Covers the three behaviors behind the strategy, driven through SentrySpan.end() with fake timers: a child ending before the debounce fires lands in the deferred transaction; a child ending after the snapshot is emitted as its own orphan transaction tagged sentry.parent_span_already_sent; and pending captures drain synchronously on the client's flush hook.
…pture Drops the CAPTURED_SPAN_CLIENTS routing map and the scope/client params threaded through the strategy. Each client gets one debounced queue (mirroring the OpenTelemetry span exporter's per-instance buffer); the capturing client is bound when the span ends and used at drain, so a deferred transaction always lands on the client that created the span. The strategy interface is now just the convert callback.
andreiborza
force-pushed
the
ab/sentry-trace-provider-otel
branch
from
98255e6 to
298b3a4
Compare
andreiborza
force-pushed
the
ab/sentry-trace-provider-core-capture
branch
from
d93efba to
22abc5c
Compare
JPeer264
approved these changes
Jul 2, 2026
JPeer264
left a comment
JPeer264
left a comment
Member
There was a problem hiding this comment.
LGTM. I tried it locally with the Cloudflare SDK and executed spans after the root span was finished and it works like a charm: https://sentry-sdks.sentry.io/explore/traces/trace/6ba87226f389461e94a30088900a5924/
andreiborza
added a commit
that referenced
this pull request
Jul 2, 2026
…ey end (#21842) ### What Seal spans created by the `SentryTracerProvider` once they end. After `SentrySpan.end()` finishes its end-of-span processing, every mutator no-ops, gated on the `spanIsTracerProviderSpan` brand: - `setAttribute` / `setAttributes` - `setStatus` - `updateName` - `updateStartTime` - `addLink` / `addLinks` - `addEvent` Spans created directly through core (e.g. the browser SDK) are never branded, so they stay mutable. ### Why OpenTelemetry SDK spans are immutable after `end()` (setters no-op). The `SentryTracerProvider` hands native `SentrySpan`s to OTel instrumentations as OTel spans, so they must honor that contract. Some instrumentations write to a span after `end()` (e.g. Next.js sets a status on a render error); without sealing, those late writes overwrite the finalized values. This matters most once segment-span capture is deferred (#21839): the transaction snapshot is then taken on a later tick, so any late post-`end()` write (status, attribute, name, start time, link, or event) would be serialized into it. Sealing the span on `end()` keeps the finalized values intact. ### Notes - The seal applies only to provider-branded spans. The brand is set exclusively by the OTel `SentryTracer`, never by the browser SDK, so browser spans (including web-vitals start-time adjustments via `updateStartTime`) are unaffected. - Tests in `sentrySpan.test.ts` cover both directions: a branded span where all mutators no-op after `end()`, and a non-branded span that stays mutable. Stacked on #21839 (deferred capture / orphan emission) and #21666 (which provides the `spanIsTracerProviderSpan` brand). Dormant until #21680 wires the provider; no provider-branded spans exist before then.
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
3 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
Adds the ability to defer the assembly of transactions to avoid dropping spans from transactions that end shortly after the segment span itself. Additionally, it also handles children that end after the debounce fired and transactions have already been sent. Spans that don't quite make it will end up as their own transaction in the same trace instead of being dropped .
This mimics what is already done today in the span exporter (a buffer + debounced flush).
Why
SentrySpan assembles a transaction synchronously from the span tree the instant the segment span ends. But some child spans are closed by their instrumentation after the root ends.
For example:
asyncEnd/response callback that runs after the root handler returns.@prisma/instrumentationemits its engine spans on a later tick once it receives the engine trace data.Without deferral those children aren't in the tree yet at root-end, so they're silently dropped from the transaction. With the OTel SDK, this never happened because the
SentrySpanExporteralready buffers finished spans and flushes on a debounced timer. The SentryTracerProvider has no exporter, so defer reinstates that buffering window so late-ending children land before the snapshot.This is used and tested in #21680's integration/e2e tests.