fix(core): Improve waiting for tracing channel bindings

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';

packages/core/src/asyncContext/index.ts

@@ -1,9 +1,7 @@
 import type { Carrier } from './../carrier';
 import { getMainCarrier, getSentryCarrier } from './../carrier';
-import type { Scope } from './../scope';
-import { _setSpanForScope } from './../utils/spanOnScope';
 import { getStackAsyncContextStrategy } from './stackStrategy';
-import type { AsyncContextStrategy, TracingChannelBinding } from './types';
+import type { AsyncContextStrategy } from './types';
 
 /**
  * @private Private API with no semver guarantees!
@@ -31,35 +29,3 @@ export function getAsyncContextStrategy(carrier: Carrier): AsyncContextStrategy
  // Otherwise, use the default one (stack)
  return getStackAsyncContextStrategy();
 }
-
-/**
- * Get the runtime binding needed to connect tracing channels to async context.
- */
-export function getTracingChannelBinding(): TracingChannelBinding | undefined {
- return getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
-}
-
-/**
- * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
- *
- * The ALS instance is supplied by the caller (kept as `unknown`).
- * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
- *
- * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
- * `{ scope, isolationScope }` pair.
- */
-export function _INTERNAL_createTracingChannelBinding(
- asyncLocalStorage: unknown,
- getScopes: () => { scope: Scope; isolationScope: Scope },
-): TracingChannelBinding {
- return {
- asyncLocalStorage,
- getStoreWithActiveSpan: span => {
- const { scope, isolationScope } = getScopes();
- const activeScope = scope.clone();
- _setSpanForScope(activeScope, span);
-
- return { scope: activeScope, isolationScope };
- },
- };
-}

packages/core/src/asyncContext/tracing-channel-binding.ts

@@ -0,0 +1,59 @@
+import { getMainCarrier } from '../carrier';
+import type { Scope } from '../scope';
+import { _setSpanForScope } from '../utils/spanOnScope';
+import { safeUnref } from '../utils/timer';
+import { getAsyncContextStrategy } from './index';
+import type { TracingChannelBinding } from './types';
+
+/**
+ * Execute a callback whenever the tracing channel binding is available.
+ * If it is not available after retry, the callback is not executed.
+ */
+export function waitForTracingChannelBinding(callback: () => void, retries = 1): void {
+ const binding = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.();
+
+ if (binding) {
+ callback();
+ return;
+ }
+
+ if (!retries) {
+ return;
+ }
+
+ // It is possible that the binding is not available yet when this is initially called
+ // This happens when users use a custom OTEL setup
+ // In this case, we wait for a tick and try again afterwards
+ // If it still fails, we bail and do nothing
+ // `safeUnref` so this retry timer never keeps the process alive on its own (Node server runtimes).
+ safeUnref(
+ setTimeout(() => {
+ waitForTracingChannelBinding(callback, retries - 1);
+ }, 1),
+ );
+}
+
+/**
+ * Build the default {@link TracingChannelBinding} shared by AsyncLocalStorage-based strategies.
+ *
+ * The ALS instance is supplied by the caller (kept as `unknown`).
+ * The binding clones the current scope, plants the span on it, and reuses the existing isolation scope.
+ *
+ * The OpenTelemetry strategy does not use this: its store value is an OTel context, not a
+ * `{ scope, isolationScope }` pair.
+ */
+export function _INTERNAL_createTracingChannelBinding(
+ asyncLocalStorage: NonNullable<unknown>,
+ getScopes: () => { scope: Scope; isolationScope: Scope },
+): TracingChannelBinding {
+ return {
+ asyncLocalStorage,
+ getStoreWithActiveSpan: span => {
+ const { scope, isolationScope } = getScopes();
+ const activeScope = scope.clone();
+ _setSpanForScope(activeScope, span);
+
+ return { scope: activeScope, isolationScope };
+ },
+ };
+}

packages/core/src/asyncContext/types.ts

@@ -21,7 +21,7 @@ export interface TracingChannelBinding {
  /**
  * The ALS instance that will be bound to the channel.
  */
- asyncLocalStorage: unknown;
+ asyncLocalStorage: NonNullable<unknown>;
 
  /**
  * Activates a span for the tracing channels nested invocations, the return value must be the same type as the `asyncLocalStorage` inner value.

packages/core/src/shared-exports.ts

@@ -49,11 +49,11 @@ export {
  hasExternalPropagationContext,
 } from './currentScopes';
 export { getDefaultCurrentScope, getDefaultIsolationScope } from './defaultScopes';
+export { setAsyncContextStrategy, getAsyncContextStrategy } from './asyncContext';
 export {
- setAsyncContextStrategy,
- getTracingChannelBinding as _INTERNAL_getTracingChannelBinding,
+ waitForTracingChannelBinding,
  _INTERNAL_createTracingChannelBinding,
-} from './asyncContext';
+} from './asyncContext/tracing-channel-binding';
 export { getGlobalSingleton, getMainCarrier } from './carrier';
 export { makeSession, closeSession, updateSession } from './session';
 export { Scope } from './scope';

packages/core/test/lib/asyncContext/tracing-channel-binding.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getAsyncContextStrategy, setAsyncContextStrategy } from '../../../src/asyncContext';
+import { waitForTracingChannelBinding } from '../../../src/asyncContext/tracing-channel-binding';
+import type { TracingChannelBinding } from '../../../src/asyncContext/types';
+import { getMainCarrier } from '../../../src/carrier';
+
+const FAKE_BINDING: TracingChannelBinding = {
+ asyncLocalStorage: {},
+ getStoreWithActiveSpan: () => ({}),
+};
+
+/** Install an async context strategy whose `getTracingChannelBinding` is driven by `provider`. */
+function setBindingProvider(provider: (() => TracingChannelBinding | undefined) | undefined): void {
+ setAsyncContextStrategy({
+ ...getAsyncContextStrategy(getMainCarrier()),
+ getTracingChannelBinding: provider,
+ });
+}
+
+describe('waitForTracingChannelBinding', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setAsyncContextStrategy(undefined);
+ });
+
+ afterEach(() => {
+ setAsyncContextStrategy(undefined);
+ vi.useRealTimers();
+ });
+
+ it('runs the callback synchronously when the binding is already available', () => {
+ const getBinding = vi.fn(() => FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ // Resolved on the first attempt, so no retry should be scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries on the next tick and runs the callback once the binding becomes available', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ // Not available on the first (synchronous) attempt.
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not run the callback if the binding never becomes available (default single retry)', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback);
+
+ expect(callback).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled();
+
+ // The single retry is exhausted — no further attempts are scheduled.
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(2);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('does not retry when retries is 0', () => {
+ const getBinding = vi.fn(() => undefined);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+
+ // No retry is scheduled when no retries remain.
+ vi.runAllTimers();
+ expect(getBinding).toHaveBeenCalledTimes(1);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it('honors a custom retry count', () => {
+ const getBinding = vi.fn<[], TracingChannelBinding | undefined>(() => FAKE_BINDING);
+ getBinding.mockReturnValueOnce(undefined).mockReturnValueOnce(undefined).mockReturnValue(FAKE_BINDING);
+ setBindingProvider(getBinding);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 2);
+
+ expect(callback).not.toHaveBeenCalled(); // attempt 1 (sync): undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).not.toHaveBeenCalled(); // attempt 2: undefined
+
+ vi.advanceTimersByTime(1);
+ expect(callback).toHaveBeenCalledTimes(1); // attempt 3: available
+ });
+
+ it('does nothing when the strategy exposes no `getTracingChannelBinding`', () => {
+ // The default (stack) strategy has no tracing-channel binding support.
+ setAsyncContextStrategy(undefined);
+
+ const callback = vi.fn();
+ waitForTracingChannelBinding(callback, 0);
+
+ expect(callback).not.toHaveBeenCalled();
+ });
+});

packages/node-core/src/sdk/index.ts

@@ -114,7 +114,7 @@ function _init(
  initializeEsmLoader();
  }
 
- setOpenTelemetryContextAsyncContextStrategy();
+ setOpenTelemetryContextAsyncContextStrategy(options);
 
  const scope = getCurrentScope();
  scope.update(options.initialScope);

packages/node/src/integrations/tracing/redis/index.ts

@@ -7,6 +7,7 @@ import {
  SEMANTIC_ATTRIBUTE_SENTRY_OP,
  spanToJSON,
  truncate,
+ waitForTracingChannelBinding,
 } from '@sentry/core';
 import * as dc from 'node:diagnostics_channel';
 import { subscribeRedisDiagnosticChannels, type RedisTracingChannelFactory } from '@sentry/server-utils';
@@ -128,9 +129,9 @@ export const instrumentRedis = Object.assign(
  // so defer to the next tick.
  // Check this here to ensure this does not fail at runtime for Node <= 18.18.0
  if (dc.tracingChannel) {
-void Promise.resolve().then(() =>
- subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook),
- );
+waitForTracingChannelBinding(() => {
+ subscribeRedisDiagnosticChannels(dc.tracingChannel as RedisTracingChannelFactory, cacheResponseHook);
+});
  }
 
  // todo: implement them gradually

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,5 +1,5 @@
 import * as api from '@opentelemetry/api';
-import type { Scope, Span, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
+import type { Scope, TracingChannelBinding, withActiveSpan as defaultWithActiveSpan } from '@sentry/core';
 import { getDefaultCurrentScope, getDefaultIsolationScope, setAsyncContextStrategy } from '@sentry/core';
 import {
  SENTRY_FORK_ISOLATION_SCOPE_CONTEXT_KEY,
@@ -13,19 +13,13 @@ import { getActiveSpan } from './utils/getActiveSpan';
 import { getTraceData } from './utils/getTraceData';
 import { suppressTracing } from './utils/suppressTracing';
 
-interface ContextApi {
- _getContextManager(): {
- getAsyncLocalStorageLookup(): {
- asyncLocalStorage: unknown;
- };
- };
-}
-
 /**
  * Sets the async context strategy to use follow the OTEL context under the hood.
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
-export function setOpenTelemetryContextAsyncContextStrategy(): void {
+export function setOpenTelemetryContextAsyncContextStrategy(options?: {
+ getTracingChannelBinding?: () => TracingChannelBinding | undefined;
+}): void {
  function getScopes(): CurrentScopes {
  const ctx = api.context.active();
  const scopes = getScopesFromContext(ctx);
@@ -116,18 +110,6 @@ export function setOpenTelemetryContextAsyncContextStrategy(): void {
  // The types here don't fully align, because our own `Span` type is narrower
  // than the OTEL one - but this is OK for here, as we now we'll only have OTEL spans passed around
  withActiveSpan: withActiveSpan as typeof defaultWithActiveSpan,
- getTracingChannelBinding: () => {
- try {
- const contextManager = (api.context as unknown as ContextApi)._getContextManager();
- const lookup = contextManager.getAsyncLocalStorageLookup();
-
- return {
- asyncLocalStorage: lookup.asyncLocalStorage,
- getStoreWithActiveSpan: (span: Span) => api.trace.setSpan(api.context.active(), span as api.Span),
- };
- } catch {
- return undefined;
- }
- },
+ getTracingChannelBinding: options?.getTracingChannelBinding,
  });
 }

packages/opentelemetry/src/asyncLocalStorageContextManager.ts

@@ -25,10 +25,11 @@ import type { Context, ContextManager } from '@opentelemetry/api';
 import { ROOT_CONTEXT } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
-import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import type { AsyncLocalStorageLookup } from './contextManager';
+import { SENTRY_SCOPES_CONTEXT_KEY } from './constants';
 import { buildContextWithSentryScopes } from './utils/buildContextWithSentryScopes';
 import { setIsSetup } from './utils/setupCheck';
+import { getAsyncContextStrategy, getMainCarrier } from '@sentry/core';
 
 type ListenerFn = (...args: unknown[]) => unknown;
 
@@ -44,13 +45,18 @@ const ADD_LISTENER_METHODS = ['addListener', 'on', 'once', 'prependListener', 'p
  * Semantics match `@opentelemetry/context-async-hooks` (function `bind` + `EventEmitter` patching).
  */
 export class SentryAsyncLocalStorageContextManager implements ContextManager {
- protected readonly _asyncLocalStorage = new AsyncLocalStorage<Context>();
+ protected readonly _asyncLocalStorage: AsyncLocalStorage<Context>;
 
  private readonly _kOtListeners = Symbol('OtListeners');
  private _wrapped = false;
 
  public constructor() {
  setIsSetup('SentryContextManager');
+ // Pick the instance from the async context strategy
+ // this should normally always be there, but if it is not for whatever reason, we fall back to a new instance
+ this._asyncLocalStorage =
+ (getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+ ?.asyncLocalStorage as AsyncLocalStorage<Context>) ?? new AsyncLocalStorage<Context>();
  }
 
  public active(): Context {

packages/opentelemetry/src/exports.ts

@@ -39,7 +39,6 @@ export { suppressTracing } from './utils/suppressTracing';
 
 export { setupEventContextTrace } from './setupEventContextTrace';
 
-export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
 // eslint-disable-next-line typescript/no-deprecated
 export { wrapContextManagerClass } from './contextManager';
 

packages/opentelemetry/src/index.browser.ts

@@ -12,6 +12,9 @@ export class SentryAsyncLocalStorageContextManager {
  }
 }
 
+// This is the generic, non-node specific async context strategy
+export { setOpenTelemetryContextAsyncContextStrategy } from './asyncContextStrategy';
+
 export type AsyncLocalStorageLookup = {
  asyncLocalStorage: unknown;
  contextSymbol: symbol;

packages/opentelemetry/src/index.ts

@@ -3,3 +3,6 @@ export * from './exports';
 // Node-specific exports
 export { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContextManager';
 export type { AsyncLocalStorageLookup } from './contextManager';
+
+// We export the node-specific variant here that uses async local storage
+export { setNodeOpenTelemetryContextAsyncContextStrategy as setOpenTelemetryContextAsyncContextStrategy } from './nodeAsyncContextStrategy';