ref(opentelemetry): Remove startSpan overrides from async context strategy (#23198)

## What

There is now only one implementation of `startSpan`, `startSpanManual`
and `startInactiveSpan`: the one in core. The separate OpenTelemetry
copies and the ACS overrides for them are removed.

- Core asks the async context strategy for the current active span and
for making the new span active, so Node answers from the OTel context
and the browser keeps using the scope
- Core continues incoming (remote) traces itself when the resolved
parent is a remote span
- Removes `_INTERNAL_startInactiveSpan`, the `SentryTracer` now uses the
public `startInactiveSpan`

Behavior change: a `scope` passed to the startSpan APIs now resolves the
parent from that scope. In Node, a scope without a bound context starts
a root span instead of falling back to the ambient active span
(consistent with browser behavior and the design of #23222).

## Why

The OpenTelemetry copies created spans through core anyway and only
added context bookkeeping around it. One shared code path removes the
double indirection and a lot of duplicated code.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: andreiborza

packages/core/src/asyncContext/types.ts

@@ -3,10 +3,7 @@ import type { getTraceData } from '../utils/traceData';
 import type {
   continueTrace,
   isTracingSuppressed,
-  startInactiveSpan,
   startNewTrace,
-  startSpan,
-  startSpanManual,
   suppressTracing,
   withActiveSpan,
 } from './../tracing/trace';
@@ -63,15 +60,6 @@ export interface AsyncContextStrategy {
   // OPTIONAL: Custom tracing methods
   // These are used so that we can provide OTEL-based implementations
 
-  /** Start an active span. */
-  startSpan?: typeof startSpan;
-
-  /** Start an inactive span. */
-  startInactiveSpan?: typeof startInactiveSpan;
-
-  /** Start an active manual span. */
-  startSpanManual?: typeof startSpanManual;
-
   /** Get the currently active span. */
   getActiveSpan?: typeof getActiveSpan;
 

packages/core/src/client.ts

@@ -648,6 +648,17 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public on(hook: 'spanStart', callback: (span: Span) => void): () => void;
 
+  /**
+   * Register a callback that can adjust the scope and the parent span right before a span is
+   * created. Listeners mutate the passed `spanScope` object. The Node SDK uses this to continue
+   * the trace of a remote (incoming) parent through the propagation context of a forked scope.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(
+    hook: 'prepareSpanScope',
+    callback: (spanScope: { scope: Scope; parentSpan: Span | undefined }) => void,
+  ): () => void;
+
   /**
    * Register a callback before span sampling runs. Receives a `samplingDecision` object argument with a `decision`
    * property that can be used to make a sampling decision that will be enforced, before any span sampling runs.
@@ -986,6 +997,9 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
   /** Fire a hook whenever a span starts. */
   public emit(hook: 'spanStart', span: Span): void;
 
+  /** A hook that is called right before a span is created; listeners mutate the passed object. */
+  public emit(hook: 'prepareSpanScope', spanScope: { scope: Scope; parentSpan: Span | undefined }): void;
+
   /** A hook that is called every time before a span is sampled. */
   public emit(
     hook: 'beforeSampling',

packages/core/src/tracing/index.ts

@@ -20,7 +20,6 @@ export {
 export {
   startSpan,
   startInactiveSpan,
-  _INTERNAL_startInactiveSpan,
   startSpanManual,
   continueTrace,
   withActiveSpan,

packages/core/src/tracing/trace.ts

@@ -39,7 +39,7 @@ import { sampleSpan } from './sampling';
 import { SentryNonRecordingSpan, spanIsNonRecordingSpan } from './sentryNonRecordingSpan';
 import { SentrySpan } from './sentrySpan';
 import { SPAN_STATUS_ERROR } from './spanstatus';
-import { setCapturedScopesOnSpan } from './utils';
+import { getCapturedScopesOnSpan, setCapturedScopesOnSpan } from './utils';
 import type { Client } from '../client';
 import { SUPPRESS_TRACING_KEY } from './constants';
 
@@ -54,11 +54,6 @@ import { SUPPRESS_TRACING_KEY } from './constants';
  * it may just be a non-recording span if the span is not sampled or if tracing is disabled.
  */
 export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T {
-  const acs = getAcs();
-  if (acs.startSpan) {
-    return acs.startSpan(options, callback);
-  }
-
   const spanArguments = parseSentrySpanArguments(options);
   const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
@@ -72,7 +67,7 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
 
     return wrapper(() => {
       const scope = getCurrentScope();
-      const parentSpan = getParentSpan(scope, customParentSpan);
+      const parentSpan = getParentSpan(customScope ?? scope, customParentSpan);
       const client = getClient();
 
       const missingRequiredParent = options.onlyIfParent && !parentSpan;
@@ -111,11 +106,6 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
  * it may just be a non-recording span if the span is not sampled or if tracing is disabled.
  */
 export function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span, finish: () => void) => T): T {
-  const acs = getAcs();
-  if (acs.startSpanManual) {
-    return acs.startSpanManual(options, callback);
-  }
-
   const spanArguments = parseSentrySpanArguments(options);
   const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
@@ -127,7 +117,7 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
 
     return wrapper(() => {
       const scope = getCurrentScope();
-      const parentSpan = getParentSpan(scope, customParentSpan);
+      const parentSpan = getParentSpan(customScope ?? scope, customParentSpan);
 
       const missingRequiredParent = options.onlyIfParent && !parentSpan;
       const activeSpan = missingRequiredParent
@@ -162,39 +152,20 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
  * it may just be a non-recording span if the span is not sampled or if tracing is disabled.
  */
 export function startInactiveSpan(options: StartSpanOptions): Span {
-  const acs = getAcs();
-  if (acs.startInactiveSpan) {
-    return acs.startInactiveSpan(options);
-  }
-
-  return _startInactiveSpanImpl(options);
-}
-
-/**
- * Internal version of startInactiveSpan that bypasses the ACS check.
- * Used by SentryTracerProvider to create spans without triggering recursion
- * through ACS overrides.
- * @hidden
- */
-export function _INTERNAL_startInactiveSpan(options: StartSpanOptions): Span {
-  return _startInactiveSpanImpl(options);
-}
-
-function _startInactiveSpanImpl(options: StartSpanOptions): Span {
   const spanArguments = parseSentrySpanArguments(options);
-  const { forceTransaction, parentSpan: customParentSpan } = options;
+  const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
   // If `options.scope` is defined, we use this as as a wrapper,
   // If `options.parentSpan` is defined, we want to wrap the callback in `withActiveSpan`
-  const wrapper = options.scope
-    ? (callback: () => Span) => withScope(options.scope, callback)
+  const wrapper = customScope
+    ? (callback: () => Span) => withScope(customScope, callback)
     : customParentSpan !== undefined
       ? (callback: () => Span) => withActiveSpan(customParentSpan, callback)
       : (callback: () => Span) => callback();
 
   return wrapper(() => {
     const scope = getCurrentScope();
-    const parentSpan = getParentSpan(scope, customParentSpan);
+    const parentSpan = getParentSpan(customScope ?? scope, customParentSpan);
     const client = getClient();
 
     const missingRequiredParent = options.onlyIfParent && !parentSpan;
@@ -342,10 +313,10 @@ function startMissingRequiredParentSpan(scope: Scope, client: Client | undefined
 }
 
 function createChildOrRootSpan({
-  parentSpan,
+  parentSpan: resolvedParentSpan,
   spanArguments,
   forceTransaction,
-  scope,
+  scope: currentScope,
 }: {
   parentSpan: Span | undefined;
   spanArguments: SentrySpanArguments;
@@ -354,6 +325,16 @@ function createChildOrRootSpan({
 }): Span {
   const isolationScope = getIsolationScope();
 
+  // Listeners can adjust the scope and the parent right before span creation. The Node SDK uses
+  // this to turn a remote parent (an incoming trace on the ambient OTel context) into a propagation
+  // context on a forked scope, so the span continues the incoming trace as a root span.
+  const spanScope: { scope: Scope; parentSpan: Span | undefined } = {
+    scope: currentScope,
+    parentSpan: resolvedParentSpan,
+  };
+  getClient()?.emit('prepareSpanScope', spanScope);
+  const { scope, parentSpan } = spanScope;
+
   if (!hasSpansEnabled()) {
     const scopePropagationContext = scope.getPropagationContext();
     const traceId = parentSpan ? parentSpan.spanContext().traceId : scopePropagationContext.traceId;
@@ -486,6 +467,11 @@ function getAcs(): AsyncContextStrategy {
   return getAsyncContextStrategy(carrier);
 }
 
+/**
+ * Runs the callback with the span active. When the async context strategy bridges to an ambient
+ * context (OTel), activation must go through it so the span lands on that context and
+ * instrumentation-created child spans nest under it; the scope alone is not consulted there.
+ */
 function _startRootSpan(
   spanArguments: SentrySpanArguments,
   scope: Scope,
@@ -666,8 +652,16 @@ function runCallback<T>(span: Span, makeSpanActive: boolean, callback: () => T,
   const wrapper = makeSpanActive
     ? (callback: () => T) => {
         return withActiveSpan(span, () => {
+          const scope = getCurrentScope();
+          // The fork made by withActiveSpan is based on the ambient scope. Carry over the
+          // propagation context captured at span creation, which can continue a remote parent's
+          // trace the ambient scope knows nothing about. For local parents this is a no-op.
+          const creationScope = getCapturedScopesOnSpan(span).scope;
+          if (creationScope) {
+            scope.setPropagationContext(creationScope.getPropagationContext());
+          }
           // Make sure the correct scope is captured on the span, since withActiveSpan forks the scope
-          setCapturedScopesOnSpan(span, getCurrentScope(), getIsolationScope());
+          setCapturedScopesOnSpan(span, scope, getIsolationScope());
           return callback();
         });
       }

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

@@ -31,7 +31,6 @@ import { SentryNonRecordingSpan } from '../../../src/tracing/sentryNonRecordingS
 import { startNewTrace } from '../../../src/tracing/trace';
 import type { Event } from '../../../src/types/event';
 import type { Span } from '../../../src/types/span';
-import type { StartSpanOptions } from '../../../src/types/startSpanOptions';
 import { _setSpanForScope } from '../../../src/utils/spanOnScope';
 import { getActiveSpan, getRootSpan, getSpanDescendants, spanIsSampled } from '../../../src/utils/spanUtils';
 import { getDefaultTestClientOptions, TestClient } from '../../mocks/client';
@@ -888,30 +887,6 @@ describe('startSpan', () => {
       });
     });
   });
-
-  it('uses implementation from ACS, if it exists', () => {
-    const staticSpan = new SentrySpan({ spanId: 'aha', sampled: true });
-
-    const carrier = getMainCarrier();
-
-    const customFn = vi.fn((_options: StartSpanOptions, callback: (span: Span) => string) => {
-      callback(staticSpan);
-      return 'aha';
-    }) as typeof startSpan;
-
-    const acs = {
-      ...getAsyncContextStrategy(carrier),
-      startSpan: customFn,
-    };
-    setAsyncContextStrategy(acs);
-
-    const result = startSpan({ name: 'GET users/[id]' }, span => {
-      expect(span).toEqual(staticSpan);
-      return 'oho?';
-    });
-
-    expect(result).toBe('aha');
-  });
 });
 
 describe('startSpanManual', () => {
@@ -1406,30 +1381,6 @@ describe('startSpanManual', () => {
       });
     });
   });
-
-  it('uses implementation from ACS, if it exists', () => {
-    const staticSpan = new SentrySpan({ spanId: 'aha', sampled: true });
-
-    const carrier = getMainCarrier();
-
-    const customFn = vi.fn((_options: StartSpanOptions, callback: (span: Span) => string) => {
-      callback(staticSpan);
-      return 'aha';
-    }) as unknown as typeof startSpanManual;
-
-    const acs = {
-      ...getAsyncContextStrategy(carrier),
-      startSpanManual: customFn,
-    };
-    setAsyncContextStrategy(acs);
-
-    const result = startSpanManual({ name: 'GET users/[id]' }, span => {
-      expect(span).toEqual(staticSpan);
-      return 'oho?';
-    });
-
-    expect(result).toBe('aha');
-  });
 });
 
 describe('startInactiveSpan', () => {
@@ -1446,6 +1397,42 @@ describe('startInactiveSpan', () => {
     client.init();
   });
 
+  it('includes the scope the span was started on when finished', async () => {
+    const beforeSendTransaction = vi.fn(event => event);
+
+    const options = getDefaultTestClientOptions({ tracesSampleRate: 1, beforeSendTransaction });
+    client = new TestClient(options);
+    setCurrentClient(client);
+    client.init();
+
+    let span: Span | undefined;
+
+    withScope(scope => {
+      scope.setTag('scope', 1);
+      span = startInactiveSpan({ name: 'my-span' });
+      // The span captures the scope it was started on, so later mutations of that scope
+      // are reflected on the transaction.
+      scope.setTag('scope_after_span', 2);
+    });
+
+    withScope(scope => {
+      scope.setTag('scope', 2);
+      span?.end();
+    });
+
+    await client.flush();
+
+    expect(beforeSendTransaction).toHaveBeenCalledTimes(1);
+    expect(beforeSendTransaction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        // The span-start scope is captured, including `scope_after_span` (set on the same scope
+        // after span start), but not `scope: 2` (a different scope active at `end()`).
+        tags: { scope: 1, scope_after_span: 2 },
+      }),
+      expect.anything(),
+    );
+  });
+
   it('returns a non recording span if tracing is disabled', () => {
     const options = getDefaultTestClientOptions({});
     client = new TestClient(options);
@@ -1897,25 +1884,6 @@ describe('startInactiveSpan', () => {
       expect(childSpans).toContain(innerSpan);
     });
   });
-
-  it('uses implementation from ACS, if it exists', () => {
-    const staticSpan = new SentrySpan({ spanId: 'aha', sampled: true });
-
-    const carrier = getMainCarrier();
-
-    const customFn = vi.fn((_options: StartSpanOptions) => {
-      return staticSpan;
-    }) as unknown as typeof startInactiveSpan;
-
-    const acs = {
-      ...getAsyncContextStrategy(carrier),
-      startInactiveSpan: customFn,
-    };
-    setAsyncContextStrategy(acs);
-
-    const result = startInactiveSpan({ name: 'GET users/[id]' });
-    expect(result).toBe(staticSpan);
-  });
 });
 
 describe('continueTrace', () => {
@@ -2378,6 +2346,8 @@ describe('span hooks', () => {
   beforeEach(() => {
     resetGlobals();
 
+    setAsyncContextStrategy(undefined);
+
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1.0 });
     client = new TestClient(options);
     setCurrentClient(client);

packages/node/src/sdk/client.ts

@@ -11,7 +11,11 @@ import {
   SDK_VERSION,
   ServerRuntimeClient,
 } from '@sentry/core';
-import { type AsyncLocalStorageLookup, type SentryTracerProvider } from '@sentry/opentelemetry';
+import {
+  type AsyncLocalStorageLookup,
+  registerPrepareSpanScope,
+  type SentryTracerProvider,
+} from '@sentry/opentelemetry';
 import { isMainThread, threadId } from 'worker_threads';
 import { DEBUG_BUILD } from '../debug-build';
 import type { NodeClientOptions } from '../types';
@@ -72,6 +76,10 @@ export class NodeClient extends ServerRuntimeClient<NodeClientOptions> {
     // provider path produce OTel spans that never reach `SentrySpan`, so the strategy is simply never
     // consulted for them.
     _INTERNAL_setDeferSegmentSpanCapture(this);
+
+    // Same constructor anchoring as above: every client must continue incoming (remote) traces,
+    // also manually constructed ones that never run `initOtel`.
+    registerPrepareSpanScope(this);
   }
 
   /** Get the OTEL tracer. */