fix(node): Register tracer provider when OTel API global pre-exists with a different version

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: andreiborza

packages/node/src/sdk/initOtel.ts

@@ -1,3 +1,4 @@
+import type { TracerProvider } from '@opentelemetry/api';
 import { context, propagation, trace } from '@opentelemetry/api';
 import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
@@ -26,6 +27,41 @@ import { getOpenTelemetryInstrumentationToPreload } from '../integrations/tracin
 // About 277h - this must fit into new Array(len)!
 const MAX_MAX_SPAN_WAIT_DURATION = 1_000_000;
 
+// The global registry of @opentelemetry/api 1.x, shared across all copies of the package
+const OTEL_API_GLOBAL_KEY = Symbol.for('opentelemetry.js.api.1');
+
+/**
+ * Registers the given tracer provider as the global tracer provider, recreating the OpenTelemetry
+ * API registry when it pre-exists with a different `@opentelemetry/api` version.
+ *
+ * Some host runtimes (e.g. Neon Functions) pre-create the registry with their own API version.
+ * `registerGlobal` requires an exact version match, so every registration through the SDK's copy
+ * of `@opentelemetry/api` is rejected and tracing is silently disabled
+ * (https://github.com/getsentry/sentry-javascript/issues/22338). This case is identified by a
+ * failed registration with an empty `trace` slot: `registerGlobal` checks the slot before the
+ * version, so an empty slot means the version gate rejected us and recreating the registry
+ * clobbers no other tracer provider. If the slot is occupied (another provider registered first,
+ * e.g. a second `Sentry.init()` call), the registry is left untouched and registration fails.
+ */
+function registerGlobalTracerProvider(provider: TracerProvider): boolean {
+  if (trace.setGlobalTracerProvider(provider)) {
+    return true;
+  }
+
+  const otelGlobal = globalThis as unknown as Record<symbol, { trace?: unknown } | undefined>;
+  const registry = otelGlobal[OTEL_API_GLOBAL_KEY];
+  if (registry && !registry.trace) {
+    DEBUG_BUILD &&
+      coreDebug.warn(
+        'Replaced a pre-existing OpenTelemetry API registry that was created by a different @opentelemetry/api version and would have blocked tracing. If you want to manage OpenTelemetry yourself, set `skipOpenTelemetrySetup: true` in `Sentry.init()`.',
+      );
+    otelGlobal[OTEL_API_GLOBAL_KEY] = undefined;
+    return trace.setGlobalTracerProvider(provider);
+  }
+
+  return false;
+}
+
 interface AdditionalOpenTelemetryOptions {
   /** Additional SpanProcessor instances that should be used. */
   spanProcessors?: SpanProcessor[];
@@ -118,7 +154,7 @@ export function setupOtel(
   });
 
   // Register as globals
-  trace.setGlobalTracerProvider(provider);
+  registerGlobalTracerProvider(provider);
   propagation.setGlobalPropagator(new SentryPropagator());
 
   const ctxManager = new SentryContextManager();
@@ -132,7 +168,7 @@ function setupSentryTracerProvider(
 ): [SentryTracerProvider | undefined, AsyncLocalStorageLookup | undefined] {
   const provider = new SentryTracerProvider({ resource: getSentryResource('node') });
 
-  if (!trace.setGlobalTracerProvider(provider)) {
+  if (!registerGlobalTracerProvider(provider)) {
     DEBUG_BUILD &&
       coreDebug.warn(
         'Could not register SentryTracerProvider because another OpenTelemetry tracer provider is already registered.',

packages/node/test/sdk/init.test.ts

@@ -14,6 +14,8 @@ declare var global: any;
 
 const PUBLIC_DSN = 'https://username@domain/123';
 
+const OTEL_API_GLOBAL_KEY = Symbol.for('opentelemetry.js.api.1');
+
 class MockIntegration implements Integration {
   public name: string;
   public setupOnce: Mock = vi.fn();
@@ -231,6 +233,49 @@ describe('init()', () => {
       expect(client?.traceProvider).toBeInstanceOf(BasicTracerProvider);
     });
 
+    it('recreates the OTel API registry when it pre-exists with a different @opentelemetry/api version', () => {
+      // Simulate a host runtime (e.g. Neon Functions) pre-creating the registry with its own api version
+      global[OTEL_API_GLOBAL_KEY] = { version: '0.0.1' };
+
+      init({ dsn: PUBLIC_DSN });
+
+      const client = getClient<NodeClient>();
+      const registry = global[OTEL_API_GLOBAL_KEY];
+
+      expect(client?.traceProvider).toBeInstanceOf(SentryOpentelemetry.SentryTracerProvider);
+      expect(registry?.version).not.toBe('0.0.1');
+      expect(registry?.trace).toBeDefined();
+    });
+
+    it('recreates a version-mismatched OTel API registry also for the OpenTelemetry SDK tracer provider', () => {
+      global[OTEL_API_GLOBAL_KEY] = { version: '0.0.1' };
+
+      init({ dsn: PUBLIC_DSN, openTelemetryBasicTracerProvider: true });
+
+      const client = getClient<NodeClient>();
+      const registry = global[OTEL_API_GLOBAL_KEY];
+
+      expect(client?.traceProvider).toBeInstanceOf(BasicTracerProvider);
+      expect(registry?.version).not.toBe('0.0.1');
+      expect(registry?.trace).toBeDefined();
+    });
+
+    it('does not recreate the OTel API registry when another tracer provider is already registered', () => {
+      const existingProvider = { getTracer: vi.fn() };
+      const existingRegistry = { version: '0.0.1', trace: existingProvider };
+      global[OTEL_API_GLOBAL_KEY] = existingRegistry;
+
+      init({ dsn: PUBLIC_DSN });
+
+      const client = getClient<NodeClient>();
+
+      expect(client?.traceProvider).not.toBeDefined();
+      expect(global[OTEL_API_GLOBAL_KEY]).toBe(existingRegistry);
+      expect(existingRegistry.trace).toBe(existingProvider);
+
+      global[OTEL_API_GLOBAL_KEY] = undefined;
+    });
+
     it('does not mark SentryTracerProvider as set up when global registration fails', () => {
       // Simulate another OpenTelemetry tracer provider already being registered.
       const setGlobalSpy = vi.spyOn(trace, 'setGlobalTracerProvider').mockReturnValue(false);