feat(core): Add deferred segment-span transaction capture

packages/core/src/carrier.ts

@@ -2,6 +2,7 @@ import type { AsyncContextStack } from './asyncContext/stackStrategy';
 import type { AsyncContextStrategy } from './asyncContext/types';
 import type { Client } from './client';
 import type { Scope } from './scope';
+import type { SegmentSpanCaptureStrategy } from './tracing/segmentSpanCaptureStrategy';
 import type { SerializedLog } from './types/log';
 import type { SerializedMetric } from './types/metric';
 import { SDK_VERSION } from './utils/version';
@@ -39,6 +40,9 @@ export interface SentryCarrier {
    */
   clientToMetricBufferMap?: WeakMap<Client, Array<SerializedMetric>>;
 
+  /** Strategy for assembling segment spans into transactions; set by SDKs that defer capture. */
+  segmentSpanCaptureStrategy?: SegmentSpanCaptureStrategy;
+
   /** Overwrites TextEncoder used in `@sentry/core`, need for `react-native@0.73` and older */
   encodePolyfill?: (input: string) => Uint8Array;
   /** Overwrites TextDecoder used in `@sentry/core`, need for `react-native@0.73` and older */

packages/core/src/tracing/deferSegmentSpanCapture.ts

@@ -0,0 +1,116 @@
+import type { Client } from '../client';
+import type { Scope } from '../scope';
+import type { Span } from '../types/span';
+import { debounce } from '../utils/debounce';
+import { getSegmentSpanCaptureStrategy, setSegmentSpanCaptureStrategy } from './segmentSpanCaptureStrategy';
+import type { SegmentSpanConverter } from './segmentSpanCaptureStrategy';
+
+// Spans already sent in a transaction, so a child ending after its segment can be emitted as its own
+// orphan transaction instead of being dropped or sent twice.
+const CAPTURED_SPANS = new WeakSet<Span>();
+const isSpanAlreadyCaptured = (span: Span): boolean => CAPTURED_SPANS.has(span);
+const markSpanCaptured = (span: Span): void => {
+  CAPTURED_SPANS.add(span);
+};
+
+// One debounced queue per client, drained on the client's `flush`/`close`. Mirrors the OpenTelemetry
+// span exporter, which holds one such buffer per instance, and the debounce window matches it. The
+// capturing client is resolved from the span's captured scope and bound when the span ends, not
+// re-resolved at drain time, so a deferred transaction lands on the client that created the span even if
+// the current client (or the captured scope's own client) is reassigned before the debounce fires.
+const CLIENT_QUEUES = new WeakMap<Client, (capture: () => void) => void>();
+
+/**
+ * @private Private API with no semver guarantees!
+ *
+ * Enable deferred segment-span transaction capture for a client: create its debounced queue and
+ * register the strategy (idempotent).
+ *
+ * `SentrySpan` otherwise assembles the transaction synchronously the instant a segment span ends, which
+ * drops children whose async instrumentation closes them later (a diagnostics-channel `asyncEnd`
+ * callback in the same tick, or engine spans replayed on a later tick). The debounced snapshot delays
+ * capture just enough for those later span ends to land first; a child that still ends after it is
+ * emitted as its own orphan transaction. Pending captures drain on the client's `flush` hook, so
+ * `Sentry.flush()` / `client.close()` cannot resolve before they run.
+ */
+export function _INTERNAL_setDeferSegmentSpanCapture(client: Client): void {
+  if (!getSegmentSpanCaptureStrategy()) {
+    setSegmentSpanCaptureStrategy(deferredSegmentSpanCaptureStrategy);
+  }
+  if (CLIENT_QUEUES.has(client)) {
+    return;
+  }
+
+  const pendingCaptures = new Set<() => void>();
+  const debouncedDrain = debounce(
+    () => {
+      const captures = [...pendingCaptures];
+      pendingCaptures.clear();
+      for (const capture of captures) {
+        capture();
+      }
+    },
+    1,
+    { maxWait: 100 },
+  );
+
+  client.on('flush', () => {
+    debouncedDrain.flush();
+  });
+
+  CLIENT_QUEUES.set(client, capture => {
+    pendingCaptures.add(capture);
+    debouncedDrain();
+  });
+}
+
+const deferredSegmentSpanCaptureStrategy = {
+  onSegmentSpanEnded(convert: SegmentSpanConverter, scope: Scope): void {
+    const client = scope.getClient();
+    const enqueue = client && CLIENT_QUEUES.get(client);
+    if (!enqueue) {
+      // The capturing client didn't enable deferral: capture synchronously.
+      const transactionEvent = convert();
+      if (transactionEvent) {
+        client?.captureEvent(transactionEvent);
+      }
+      return;
+    }
+
+    enqueue(() => {
+      const transactionEvent = convert({ isSpanAlreadyCaptured, onSpanCaptured: markSpanCaptured });
+      if (transactionEvent) {
+        client.captureEvent(transactionEvent);
+      }
+    });
+  },
+
+  onChildSpanEnded(span: Span, rootSpan: Span, convert: SegmentSpanConverter, scope: Scope): void {
+    // Only a late child of an already-captured segment is an orphan. Inert under span streaming, where
+    // `CAPTURED_SPANS` is never populated.
+    if (CAPTURED_SPANS.has(span) || !CAPTURED_SPANS.has(rootSpan)) {
+      return;
+    }
+
+    const client = scope.getClient();
+    const enqueue = client && CLIENT_QUEUES.get(client);
+
+    const captureOrphan = (): void => {
+      const transactionEvent = convert({ isSpanAlreadyCaptured, onSpanCaptured: markSpanCaptured });
+      if (transactionEvent?.contexts?.trace?.data) {
+        // Tag orphans so they're distinguishable downstream (mirrors the OTel span exporter).
+        transactionEvent.contexts.trace.data['sentry.parent_span_already_sent'] = true;
+      }
+      if (transactionEvent) {
+        client?.captureEvent(transactionEvent);
+      }
+    };
+
+    // Defer when the capturing client batches; otherwise emit now so the orphan isn't dropped.
+    if (enqueue) {
+      enqueue(captureOrphan);
+    } else {
+      captureOrphan();
+    }
+  },
+};

packages/core/src/tracing/index.ts

@@ -11,6 +11,7 @@ export {
 } from './utils';
 export { startIdleSpan, TRACING_DEFAULTS } from './idleSpan';
 export { SentrySpan } from './sentrySpan';
+export { _INTERNAL_setDeferSegmentSpanCapture } from './deferSegmentSpanCapture';
 export { SentryNonRecordingSpan } from './sentryNonRecordingSpan';
 export { setHttpStatus, getSpanStatusFromHttpCode } from './spanstatus';
 export { SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET } from './spanstatus';

packages/core/src/tracing/segmentSpanCaptureStrategy.ts

@@ -0,0 +1,43 @@
+import { getMainCarrier, getSentryCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import type { TransactionEvent } from '../types/event';
+import type { Span } from '../types/span';
+
+/**
+ * Callbacks the deferred-capture strategy hands to `_convertSpanToTransaction` when assembling a
+ * transaction. The synchronous (browser) path calls the converter with no options, so neither runs.
+ */
+export interface SegmentSpanCaptureConvertOptions {
+  /** Skip a descendant already sent in an earlier transaction, so it isn't sent twice. */
+  isSpanAlreadyCaptured?: (span: Span) => boolean;
+  /** Record each span included here, so a child that ends after the snapshot can be emitted as an orphan. */
+  onSpanCaptured?: (span: Span) => void;
+}
+
+export type SegmentSpanConverter = (options?: SegmentSpanCaptureConvertOptions) => TransactionEvent | undefined;
+
+/**
+ * Assembles segment spans into transactions. Registered by SDKs that defer capture (see
+ * `_INTERNAL_setDeferSegmentSpanCapture`); when unset, `SentrySpan` captures synchronously. Living
+ * behind this seam tree-shakes the deferral machinery out of SDKs that never register one (e.g. browser).
+ */
+export interface SegmentSpanCaptureStrategy {
+  /** Assemble and capture a segment (root or standalone-root) span's transaction through its captured scope. */
+  onSegmentSpanEnded(convert: SegmentSpanConverter, scope: Scope): void;
+  /** Consider a child that ended after its segment for emission as its own orphan transaction. */
+  onChildSpanEnded(span: Span, rootSpan: Span, convert: SegmentSpanConverter, scope: Scope): void;
+}
+
+/**
+ * @private Private API with no semver guarantees!
+ *
+ * Set the global segment-span capture strategy (or clear it with `undefined`).
+ */
+export function setSegmentSpanCaptureStrategy(strategy: SegmentSpanCaptureStrategy | undefined): void {
+  getSentryCarrier(getMainCarrier()).segmentSpanCaptureStrategy = strategy;
+}
+
+/** Get the global segment-span capture strategy, or `undefined` when none is registered. */
+export function getSegmentSpanCaptureStrategy(): SegmentSpanCaptureStrategy | undefined {
+  return getSentryCarrier(getMainCarrier()).segmentSpanCaptureStrategy;
+}

packages/core/src/tracing/sentrySpan.ts

@@ -46,6 +46,7 @@ import { timestampInSeconds } from '../utils/time';
 import { getDynamicSamplingContextFromSpan } from './dynamicSamplingContext';
 import { logSpanEnd } from './logSpans';
 import { timedEventsToMeasurements } from './measurement';
+import { getSegmentSpanCaptureStrategy, type SegmentSpanCaptureConvertOptions } from './segmentSpanCaptureStrategy';
 import { hasSpanStreamingEnabled } from './spans/hasSpanStreamingEnabled';
 import { getCapturedScopesOnSpan, markSpanSourceAsExplicit, spanShouldInferOtelSource } from './utils';
 
@@ -343,11 +344,8 @@ export class SentrySpan implements Span {
     // A segment span is basically the root span of a local span tree.
     // So for now, this is either what we previously refer to as the root span,
     // or a standalone span.
-    const isSegmentSpan = this._isStandaloneSpan || this === getRootSpan(this);
-
-    if (!isSegmentSpan) {
-      return;
-    }
+    const rootSpan = getRootSpan(this);
+    const isSegmentSpan = this._isStandaloneSpan || this === rootSpan;
 
     // if this is a standalone span, we send it immediately
     if (this._isStandaloneSpan) {
@@ -361,23 +359,43 @@ export class SentrySpan implements Span {
         }
       }
       return;
-    } else if (client && hasSpanStreamingEnabled(client)) {
+    }
+
+    // Non-segment children aren't captured on their own. A registered strategy may re-emit a late child
+    // as its own orphan transaction; without one, it's dropped.
+    if (!isSegmentSpan) {
+      const strategy = getSegmentSpanCaptureStrategy();
+      if (strategy) {
+        const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
+        strategy.onChildSpanEnded(this, rootSpan, options => this._convertSpanToTransaction(options), scope);
+      }
+      return;
+    }
+
+    if (client && hasSpanStreamingEnabled(client)) {
       // TODO (spans): Remove standalone span custom logic in favor of sending simple v2 web vital spans
       client.emit('afterSegmentSpanEnd', this);
       return;
     }
 
-    const transactionEvent = this._convertSpanToTransaction();
-    if (transactionEvent) {
-      const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
-      scope.captureEvent(transactionEvent);
+    // A registered strategy defers the snapshot so children closing just after the segment still land
+    // (and late ones can orphan); without one, assemble synchronously from the live tree.
+    const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
+    const strategy = getSegmentSpanCaptureStrategy();
+    if (strategy) {
+      strategy.onSegmentSpanEnded(options => this._convertSpanToTransaction(options), scope);
+    } else {
+      const transactionEvent = this._convertSpanToTransaction();
+      if (transactionEvent) {
+        scope.captureEvent(transactionEvent);
+      }
     }
   }
 
   /**
    * Finish the transaction & prepare the event to send to Sentry.
    */
-  private _convertSpanToTransaction(): TransactionEvent | undefined {
+  private _convertSpanToTransaction(options: SegmentSpanCaptureConvertOptions = {}): TransactionEvent | undefined {
     // We can only convert finished spans
     if (!isFullFinishedSpan(spanToJSON(this))) {
       return undefined;
@@ -396,10 +414,21 @@ export class SentrySpan implements Span {
       return undefined;
     }
 
-    // The transaction span itself as well as any potential standalone spans should be filtered out
-    const finishedSpans = getSpanDescendants(this).filter(span => span !== this && !isStandaloneSpan(span));
-
-    const spans = finishedSpans.map(span => spanToJSON(span)).filter(isFullFinishedSpan);
+    // Skip the span itself, standalone spans, and (when a strategy tracks it) spans already sent. The
+    // synchronous default passes no hooks, so this bookkeeping stays out of SDKs that don't defer.
+    options.onSpanCaptured?.(this);
+    const spans: SpanJSON[] = [];
+    for (const descendant of getSpanDescendants(this)) {
+      if (descendant === this || isStandaloneSpan(descendant) || options.isSpanAlreadyCaptured?.(descendant)) {
+        continue;
+      }
+      const spanJSON = spanToJSON(descendant);
+      if (!isFullFinishedSpan(spanJSON)) {
+        continue;
+      }
+      options.onSpanCaptured?.(descendant);
+      spans.push(spanJSON);
+    }
 
     const source = this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];