feat(server-utils): Implement setAsyncLocalStorageAsyncContextStrategy

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -13,6 +13,7 @@ const flushMarkerMatcher = (envelope: Envelope): void => {
 
 it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
   const runner = createRunner(__dirname)
+    .unordered()
     .expect(envelope => {
       const transactionEvent = envelope[1]?.[0]?.[1] as TransactionEvent | undefined;
       const spans = transactionEvent?.spans ?? [];

packages/cloudflare/.oxlintrc.json

@@ -34,7 +34,7 @@
                 "message": "Do not import from `@sentry/node` in the Cloudflare SDK. It relies on Node.js APIs that are only available when the `nodejs_compat` flag is set. The only allowed importers are files in `src/nodejs_compat/`, which are exposed via the `@sentry/cloudflare/nodejs_compat/*` entry points."
               },
               {
-                "group": ["@sentry/server-utils/**"],
+                "group": ["@sentry/server-utils/**", "!@sentry/server-utils/no-diagnostic-channels"],
                 "message": "Do not import from `@sentry/server-utils` in the Cloudflare SDK. It relies on Node.js APIs that are only available when the `nodejs_compat` flag is set. The only allowed importers are files in `src/nodejs_compat/`, which are exposed via the `@sentry/cloudflare/nodejs_compat/*` entry points."
               }
             ]

packages/cloudflare/src/durableobject.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/unbound-method */
 import { captureException } from '@sentry/core';
 import type { DurableObject } from 'cloudflare:workers';
-import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from './client';
 import { ensureInstrumented } from './instrument';
 import { instrumentEnv } from './instrumentations/worker/instrumentEnv';

packages/cloudflare/src/index.ts

@@ -134,4 +134,4 @@ export { instrumentD1WithSentry } from './instrumentations/worker/instrumentD1';
 
 export { instrumentWorkflowWithSentry } from './workflows';
 
-export { setAsyncLocalStorageAsyncContextStrategy } from './async';
+export { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';

packages/cloudflare/src/instrumentations/instrumentWorkerEntrypoint.ts

@@ -1,5 +1,5 @@
 import type { RpcStub, WorkerEntrypoint } from 'cloudflare:workers';
-import { setAsyncLocalStorageAsyncContextStrategy } from '../async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from '../client';
 import { getFinalOptions } from '../options';
 import { instrumentContext } from '../utils/instrumentContext';

packages/cloudflare/src/pages-plugin.ts

@@ -1,4 +1,4 @@
-import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from './client';
 import type { ExecutionContextCompat } from './executionContext';
 import { wrapRequestHandler } from './request';

packages/cloudflare/src/withSentry.ts

@@ -1,5 +1,5 @@
 import type { env as cloudflareEnv } from 'cloudflare:workers';
-import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from './client';
 import { instrumentExportedHandlerEmail } from './instrumentations/worker/instrumentEmail';
 import { instrumentExportedHandlerFetch } from './instrumentations/worker/instrumentFetch';

packages/cloudflare/src/workflows.ts

@@ -23,7 +23,7 @@ import type {
   WorkflowStepRollbackOptions,
   WorkflowTimeoutDuration,
 } from 'cloudflare:workers';
-import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from './client';
 import { flushAndDispose } from './flush';
 import { instrumentEnv } from './instrumentations/worker/instrumentEnv';

packages/cloudflare/test/client.test.ts

@@ -1,5 +1,5 @@
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
-import { setAsyncLocalStorageAsyncContextStrategy } from '../src/async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import { CloudflareClient, type CloudflareClientOptions } from '../src/client';
 import { makeFlushLock } from '../src/flush';
 

packages/cloudflare/test/instrumentCloudflareAgent.test.ts

@@ -1,7 +1,7 @@
 import type { Event } from '@sentry/core';
 import { getCurrentScope, setCurrentClient } from '@sentry/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { setAsyncLocalStorageAsyncContextStrategy } from '../src/async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import { CloudflareClient, type CloudflareClientOptions } from '../src/client';
 import { instrumentCloudflareAgent } from '../src/instrumentations/agents';
 import { resetSdk } from './testUtils';

packages/cloudflare/test/instrumentations/instrumentWorkerEntrypoint.test.ts

@@ -176,7 +176,7 @@ describe('instrumentWorkerEntrypoint', () => {
   });
 
   it('Calls setAsyncLocalStorageAsyncContextStrategy outside Proxy (at instrumentation time), not inside construct', async () => {
-    const asyncModule = await import('../../src/async');
+    const asyncModule = await import('@sentry/server-utils/no-diagnostic-channels');
     const setStrategy = vi.spyOn(asyncModule, 'setAsyncLocalStorageAsyncContextStrategy');
     const mockContext = createMockExecutionContext();
     const TestClass = class extends WorkerEntrypoint {
@@ -216,6 +216,9 @@ describe('instrumentWorkerEntrypoint', () => {
     const waitUntil = vi.fn();
     const TestClass = vi.fn((context: ExecutionContext) => ({
       fetch: () => {
+        // The client is created per request, on the scope forked for that request, so it is only
+        // reachable from inside the handler.
+        testClient = SentryCore.getClient();
         context.waitUntil(deferred);
         return new Response('test');
       },
@@ -225,7 +228,6 @@ describe('instrumentWorkerEntrypoint', () => {
     const worker = Reflect.construct(instrumented, [context, {}]);
 
     const responsePromise = worker.fetch(new Request('https://example.com'));
-    testClient = SentryCore.getClient();
 
     const response = await responsePromise;
     await response.text();

packages/cloudflare/test/request.test.ts

@@ -5,7 +5,7 @@ import type { ExecutionContext } from '@cloudflare/workers-types';
 import type { Event } from '@sentry/core';
 import * as SentryCore from '@sentry/core';
 import { beforeAll, beforeEach, describe, expect, onTestFinished, test, vi } from 'vitest';
-import { setAsyncLocalStorageAsyncContextStrategy } from '../src/async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils/no-diagnostic-channels';
 import type { CloudflareOptions } from '../src/client';
 import { CloudflareClient } from '../src/client';
 import { wrapRequestHandler } from '../src/request';

packages/deno/src/client.ts

@@ -1,6 +1,6 @@
 import type { ServerRuntimeClientOptions } from '@sentry/core';
 import { _INTERNAL_flushLogsBuffer, SDK_VERSION, ServerRuntimeClient } from '@sentry/core';
-import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import { setAsyncLocalStorageAsyncContextStrategy } from '@sentry/server-utils';
 import type { DenoClientOptions } from './types';
 
 function getHostName(): string | undefined {

packages/opentelemetry/src/asyncContextStrategy.ts

@@ -1,8 +1,10 @@
 import * as api from '@opentelemetry/api';
 import type { Scope, TracingChannelBinding } from '@sentry/core';
 import {
+  getAsyncContextStrategy,
   getDefaultCurrentScope,
   getDefaultIsolationScope,
+  getMainCarrier,
   getRootSpan,
   setAsyncContextStrategy,
   spanIsIgnored,
@@ -27,7 +29,14 @@ import { SentryAsyncLocalStorageContextManager } from './asyncLocalStorageContex
  * We handle forking a hub inside of our custom OTEL Context Manager (./otelContextManager.ts)
  */
 export function setOpenTelemetryContextAsyncContextStrategy(): AsyncLocalStorageLookup {
-  const asyncLocalStorage = new AsyncLocalStorage<api.Context>();
+  // Re-use the AsyncLocalStorage of an already-installed strategy, if any. Otherwise a repeated
+  // setup would swap in a new store while integrations that captured the previous one (via
+  // `getTracingChannelBinding().asyncLocalStorage`) keep reading the old one, breaking scope
+  // propagation across async boundaries.
+  const existingAsyncLocalStorage = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+    ?.asyncLocalStorage as AsyncLocalStorage<api.Context> | undefined;
+
+  const asyncLocalStorage = existingAsyncLocalStorage ?? new AsyncLocalStorage<api.Context>();
 
   function getScopes(): CurrentScopes {
     const ctx = api.context.active();

packages/opentelemetry/test/asyncContextStrategy.test.ts

@@ -362,6 +362,31 @@ describe('asyncContextStrategy', () => {
     });
   });
 
+  describe('AsyncLocalStorage re-use', () => {
+    it('re-uses the AsyncLocalStorage of an already-installed strategy on repeated setup', () => {
+      setOpenTelemetryContextAsyncContextStrategy();
+      const firstStorage = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()?.asyncLocalStorage;
+      expect(firstStorage).toBeDefined();
+
+      setOpenTelemetryContextAsyncContextStrategy();
+      const secondStorage = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()?.asyncLocalStorage;
+
+      expect(secondStorage).toBe(firstStorage);
+    });
+
+    it('returns a context manager backed by the re-used AsyncLocalStorage', () => {
+      const firstLookup = setOpenTelemetryContextAsyncContextStrategy();
+      const secondLookup = setOpenTelemetryContextAsyncContextStrategy();
+
+      // The context manager returned on the second setup wraps the same AsyncLocalStorage instance,
+      // so consumers that captured the lookup from the first setup keep observing the active context.
+      expect(secondLookup.asyncLocalStorage).toBe(firstLookup.asyncLocalStorage);
+      expect(getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()?.asyncLocalStorage).toBe(
+        firstLookup.asyncLocalStorage,
+      );
+    });
+  });
+
   describe('withScope()', () => {
     it('will make the passed scope the active scope within the callback', () =>
       new Promise<void>(done => {

packages/server-utils/package.json

@@ -22,6 +22,11 @@
       "import": "./build/esm/index.js",
       "require": "./build/cjs/index.js"
     },
+    "./no-diagnostic-channels": {
+      "types": "./build/types/index.no-diagnostic-channels.d.ts",
+      "import": "./build/esm/index.no-diagnostic-channels.js",
+      "require": "./build/cjs/index.no-diagnostic-channels.js"
+    },
     "./orchestrion": {
       "types": "./build/types/orchestrion/index.d.ts",
       "import": "./build/esm/orchestrion/index.js",

packages/server-utils/rollup.npm.config.mjs

@@ -104,6 +104,7 @@ export default [
       // subpath export.
       entrypoints: [
         'src/index.ts',
+        'src/index.no-diagnostic-channels.ts',
         'src/orchestrion/index.ts',
         'src/orchestrion/config/index.ts',
         // `src/orchestrion/runtime/register.ts` backs the `./orchestrion/register`

packages/deno/src/async.ts → packages/server-utils/src/async-context.ts

@@ -1,36 +1,28 @@
-// Need to use node: prefix for deno compatibility
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { Scope } from '@sentry/core';
 import {
   _INTERNAL_createTracingChannelBinding,
+  getAsyncContextStrategy,
   getDefaultCurrentScope,
   getDefaultIsolationScope,
+  getMainCarrier,
   setAsyncContextStrategy,
 } from '@sentry/core';
 
-let installed = false;
+type ScopeStore = { scope: Scope; isolationScope: Scope };
 
 /**
  * Sets the async context strategy to use AsyncLocalStorage.
- *
- * Idempotent: multiple integrations each call this from their `setupOnce`,
- * but they must all share a single `AsyncLocalStorage` so context propagates
- * between them. The first call wins, later calls are no-ops. This prevents
- * orphaning an in-flight context if an integration is set up asynchronously.
- *
- * @internal Only exported to be used in higher-level Sentry packages
- * @hidden Only exported to be used in higher-level Sentry packages
  */
 export function setAsyncLocalStorageAsyncContextStrategy(): void {
-  if (installed) {
-    return;
-  }
-  installed = true;
+  // Re-use the AsyncLocalStorage of an already-installed strategy, if any. Otherwise a repeated
+  // setup (e.g. a second `Sentry.init()`) would swap in a new store while integrations that captured
+  // the previous one (via `getTracingChannelBinding().asyncLocalStorage`) keep reading the old one,
+  // breaking scope propagation across async boundaries.
+  const existingAsyncStorage = getAsyncContextStrategy(getMainCarrier()).getTracingChannelBinding?.()
+    ?.asyncLocalStorage as AsyncLocalStorage<ScopeStore> | undefined;
 
-  const asyncStorage = new AsyncLocalStorage<{
-    scope: Scope;
-    isolationScope: Scope;
-  }>();
+  const asyncStorage = existingAsyncStorage ?? new AsyncLocalStorage<ScopeStore>();
 
   function getScopes(): { scope: Scope; isolationScope: Scope } {
     const scopes = asyncStorage.getStore();
@@ -55,23 +47,30 @@ export function setAsyncLocalStorageAsyncContextStrategy(): void {
     });
   }
 
+  // The isolation scope is shared, not forked, matching `withScope` above and the OpenTelemetry
+  // strategy. Forking it would silently discard `setUser`/`setTag`/`setContext` calls made inside
+  // the callback, as those write to the isolation scope.
   function withSetScope<T>(scope: Scope, callback: (scope: Scope) => T): T {
-    const isolationScope = getScopes().isolationScope.clone();
+    const isolationScope = getScopes().isolationScope;
     return asyncStorage.run({ scope, isolationScope }, () => {
       return callback(scope);
     });
   }
 
+  // The current scope is forked alongside the isolation scope, matching the OpenTelemetry strategy
+  // (`buildContextWithSentryScopes` clones it on every fork). Sharing it by reference would let
+  // current-scope mutations inside the callback leak back out to the caller.
   function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
-    const scope = getScopes().scope;
+    const scope = getScopes().scope.clone();
     const isolationScope = getScopes().isolationScope.clone();
+
     return asyncStorage.run({ scope, isolationScope }, () => {
       return callback(isolationScope);
     });
   }
 
   function withSetIsolationScope<T>(isolationScope: Scope, callback: (isolationScope: Scope) => T): T {
-    const scope = getScopes().scope;
+    const scope = getScopes().scope.clone();
     return asyncStorage.run({ scope, isolationScope }, () => {
       return callback(isolationScope);
     });

packages/server-utils/src/exports.ts

@@ -0,0 +1,3 @@
+// Shared exports not using diagnostics channels
+export { setHttpServerSpanRouteAttribute } from './utils/setHttpServerSpanRouteAttribute';
+export { setAsyncLocalStorageAsyncContextStrategy } from './async-context';

packages/server-utils/src/index.no-diagnostic-channels.ts

@@ -0,0 +1 @@
+export * from './exports';

packages/server-utils/src/index.ts

@@ -1,9 +1,6 @@
-/**
- * Server-only utilities shared across Sentry server SDKs.
- *
- * @module
- */
+export * from './exports';
 
+// Exports using diagnostics channels
 export { graphqlIntegration } from './graphql';
 export { mongooseIntegration, startMongooseLegacySpan } from './mongoose';
 export type { MongooseLegacyCollection, StartMongooseLegacySpanOptions } from './mongoose';
@@ -36,4 +33,3 @@ export {
   // oxlint-disable-next-line typescript/no-deprecated
   instrumentFastify,
 } from './integrations/tracing-channel/fastify';
-export { setHttpServerSpanRouteAttribute } from './utils/setHttpServerSpanRouteAttribute';