Route deferred captures through the span's captured scope

Author: andreiborza

packages/core/src/tracing/deferSegmentSpanCapture.ts

@@ -1,5 +1,5 @@
 import type { Client } from '../client';
-import { getClient } from '../currentScopes';
+import type { Scope } from '../scope';
 import type { Span } from '../types/span';
 import { debounce } from '../utils/debounce';
 import { getSegmentSpanCaptureStrategy, setSegmentSpanCaptureStrategy } from './segmentSpanCaptureStrategy';
@@ -15,8 +15,9 @@ const markSpanCaptured = (span: Span): void => {
 
 // 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 bound when the span ends (not re-resolved at drain time), so a deferred capture
-// lands on the client that created the span even if a different client became current in the meantime.
+// 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>();
 
 /**
@@ -64,11 +65,11 @@ export function _INTERNAL_setDeferSegmentSpanCapture(client: Client): void {
 }
 
 const deferredSegmentSpanCaptureStrategy = {
-  onSegmentSpanEnded(convert: SegmentSpanConverter): void {
-    const client = getClient();
+  onSegmentSpanEnded(convert: SegmentSpanConverter, scope: Scope): void {
+    const client = scope.getClient();
     const enqueue = client && CLIENT_QUEUES.get(client);
     if (!enqueue) {
-      // The current client didn't enable deferral: capture synchronously.
+      // The capturing client didn't enable deferral: capture synchronously.
       const transactionEvent = convert();
       if (transactionEvent) {
         client?.captureEvent(transactionEvent);
@@ -84,28 +85,32 @@ const deferredSegmentSpanCaptureStrategy = {
     });
   },
 
-  onChildSpanEnded(span: Span, rootSpan: Span, convert: SegmentSpanConverter): void {
+  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 = getClient();
+    const client = scope.getClient();
     const enqueue = client && CLIENT_QUEUES.get(client);
-    if (!enqueue) {
-      return;
-    }
 
-    enqueue(() => {
+    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);
+        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/segmentSpanCaptureStrategy.ts

@@ -1,4 +1,5 @@
 import { getMainCarrier, getSentryCarrier } from '../carrier';
+import type { Scope } from '../scope';
 import type { TransactionEvent } from '../types/event';
 import type { Span } from '../types/span';
 
@@ -21,10 +22,10 @@ export type SegmentSpanConverter = (options?: SegmentSpanCaptureConvertOptions)
  * 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. */
-  onSegmentSpanEnded(convert: SegmentSpanConverter): void;
+  /** 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): void;
+  onChildSpanEnded(span: Span, rootSpan: Span, convert: SegmentSpanConverter, scope: Scope): void;
 }
 
 /**

packages/core/src/tracing/sentrySpan.ts

@@ -364,9 +364,11 @@ export class SentrySpan implements Span {
     // 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) {
-      getSegmentSpanCaptureStrategy()?.onChildSpanEnded(this, rootSpan, options =>
-        this._convertSpanToTransaction(options),
-      );
+      const strategy = getSegmentSpanCaptureStrategy();
+      if (strategy) {
+        const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
+        strategy.onChildSpanEnded(this, rootSpan, options => this._convertSpanToTransaction(options), scope);
+      }
       return;
     }
 
@@ -378,13 +380,13 @@ export class SentrySpan implements Span {
 
     // 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));
+      strategy.onSegmentSpanEnded(options => this._convertSpanToTransaction(options), scope);
     } else {
       const transactionEvent = this._convertSpanToTransaction();
       if (transactionEvent) {
-        const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
         scope.captureEvent(transactionEvent);
       }
     }

packages/core/test/lib/tracing/deferSegmentSpanCapture.test.ts

@@ -6,6 +6,7 @@ import {
   setCurrentClient,
   startInactiveSpan,
   withActiveSpan,
+  withScope,
 } from '../../../src';
 import { _INTERNAL_setDeferSegmentSpanCapture } from '../../../src/tracing/deferSegmentSpanCapture';
 import {
@@ -119,4 +120,97 @@ describe('deferred segment-span capture', () => {
 
     expect(transactions).toHaveLength(1);
   });
+
+  it("routes a deferred segment to the span's own client, not whichever client is current at end", () => {
+    const otherTransactions: Event[] = [];
+    const otherClient = new TestClient(
+      getDefaultTestClientOptions({
+        dsn,
+        tracesSampleRate: 1,
+        beforeSendTransaction: event => {
+          otherTransactions.push(event);
+          return null;
+        },
+      }),
+    );
+    otherClient.init();
+    _INTERNAL_setDeferSegmentSpanCapture(otherClient);
+
+    // Created while `client` is current, so its captured scope belongs to `client`.
+    const root = startInactiveSpan({ name: 'root' });
+
+    // A different client becomes current before the span ends.
+    withScope(scope => {
+      scope.setClient(otherClient);
+      root.end();
+    });
+
+    vi.advanceTimersByTime(100);
+
+    expect(transactions).toHaveLength(1);
+    expect(otherTransactions).toHaveLength(0);
+  });
+
+  it('emits a late orphan synchronously when its client has no defer queue', () => {
+    const orphanTransactions: Event[] = [];
+    const noQueueClient = new TestClient(
+      getDefaultTestClientOptions({
+        dsn,
+        tracesSampleRate: 1,
+        beforeSendTransaction: event => {
+          orphanTransactions.push(event);
+          return null;
+        },
+      }),
+    );
+    noQueueClient.init();
+    // Deliberately not enabling deferral on `noQueueClient`, so it has no queue.
+
+    // Root is captured via `client` (which defers), so it lands in `CAPTURED_SPANS`.
+    const root = startInactiveSpan({ name: 'root' });
+    // The child's captured scope belongs to the queue-less client.
+    const child = withScope(scope => {
+      scope.setClient(noQueueClient);
+      return withActiveSpan(root, () => startInactiveSpan({ name: 'child' }));
+    });
+
+    root.end();
+    vi.advanceTimersByTime(100);
+    expect(transactions).toHaveLength(1);
+    expect(orphanTransactions).toHaveLength(0);
+
+    // Late child on a queue-less client: emitted right away instead of dropped.
+    child.end();
+
+    expect(orphanTransactions).toHaveLength(1);
+    expect(orphanTransactions[0]!.transaction).toBe('child');
+    expect(orphanTransactions[0]!.contexts?.trace?.data?.['sentry.parent_span_already_sent']).toBe(true);
+  });
+
+  it('binds the capturing client at span end, ignoring later reassignment of the scope client', () => {
+    const laterTransactions: Event[] = [];
+    const laterClient = new TestClient(
+      getDefaultTestClientOptions({
+        dsn,
+        tracesSampleRate: 1,
+        beforeSendTransaction: event => {
+          laterTransactions.push(event);
+          return null;
+        },
+      }),
+    );
+    laterClient.init();
+    _INTERNAL_setDeferSegmentSpanCapture(laterClient);
+
+    const root = startInactiveSpan({ name: 'root' });
+    root.end(); // enqueued and bound to `client` (the captured scope's client at span end)
+
+    // The captured scope's own client is reassigned before the debounce fires.
+    getCurrentScope().setClient(laterClient);
+
+    vi.advanceTimersByTime(100);
+
+    expect(transactions).toHaveLength(1);
+    expect(laterTransactions).toHaveLength(0);
+  });
 });