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

## What

When the OTel API global registry
(`Symbol.for('opentelemetry.js.api.1')`) pre-exists with a different
`@opentelemetry/api` version, the SDK now replaces it and registers its
tracer provider instead of silently disabling tracing.

- Retry registration after replacing the registry, only when its `trace`
slot is empty
- Debug warning when the registry is replaced, pointing to
`skipOpenTelemetrySetup`
- Applies to both the default `SentryTracerProvider` and the
`BasicTracerProvider` path

## Why

Host runtimes like Neon Functions pre-create the registry with their own
api version. OTel's `registerGlobal` requires an exact version match, so
every registration is rejected and all spans (including
`Sentry.startSpan()`) are non-recording, with no signal outside debug
builds. Node flavor of the Deno issue fixed in #19723.

The empty-`trace`-slot condition keeps existing behavior when a real
provider is already registered (second `Sentry.init()`, user-managed
OTel): those still back off as before, so no working setup gets
clobbered.

Closes: #22338

---------

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,61 @@ 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.
+ *
+ * Slots Sentry does not claim itself (e.g. `diag`, `metrics`) are carried over into the recreated
+ * registry: reads resolve via a semver-compatibility check rather than the exact-match write gate,
+ * so they keep working for the copy that registered them. `propagation` and `context` are not
+ * carried over because Sentry registers its own right after this.
+ */
+function registerGlobalTracerProvider(provider: TracerProvider): boolean {
+  if (trace.setGlobalTracerProvider(provider)) {
+    return true;
+  }
+
+  // @opentelemetry/api stores the registry under a `Symbol.for` key that no public type
+  // describes, so `typeof globalThis` can only be narrowed to it by casting through `unknown`.
+  const otelGlobal = globalThis as unknown as Record<symbol, Record<string, 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;
+
+    if (!trace.setGlobalTracerProvider(provider)) {
+      return false;
+    }
+
+    // The cast is needed because TS still has the slot narrowed to `undefined` from the reset
+    // above and cannot know the registration call just recreated the registry.
+    const recreatedRegistry = otelGlobal[OTEL_API_GLOBAL_KEY] as Record<string, unknown> | undefined;
+    if (recreatedRegistry) {
+      const { propagation: _propagation, context: _context, ...carriedOverSlots } = registry;
+      otelGlobal[OTEL_API_GLOBAL_KEY] = { ...carriedOverSlots, ...recreatedRegistry };
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
 interface AdditionalOpenTelemetryOptions {
   /** Additional SpanProcessor instances that should be used. */
   spanProcessors?: SpanProcessor[];
@@ -118,7 +174,7 @@ export function setupOtel(
   });
 
   // Register as globals
-  trace.setGlobalTracerProvider(provider);
+  registerGlobalTracerProvider(provider);
   propagation.setGlobalPropagator(new SentryPropagator());
 
   const ctxManager = new SentryContextManager();
@@ -132,7 +188,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,73 @@ 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('carries non-Sentry slots of a version-mismatched OTel API registry over into the recreated one', () => {
+      // Must be a complete DiagLogger: once carried over, the SDK's api copy resolves it and
+      // calls it for its own diag output.
+      const diagLogger = { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn(), verbose: vi.fn() };
+      const meterProvider = { getMeter: vi.fn() };
+      const propagator = { inject: vi.fn() };
+      global[OTEL_API_GLOBAL_KEY] = {
+        version: '0.0.1',
+        diag: diagLogger,
+        metrics: meterProvider,
+        propagation: propagator,
+      };
+
+      init({ dsn: PUBLIC_DSN });
+
+      const registry = global[OTEL_API_GLOBAL_KEY];
+
+      expect(registry?.trace).toBeDefined();
+      expect(registry?.diag).toBe(diagLogger);
+      expect(registry?.metrics).toBe(meterProvider);
+      // propagation is claimed by Sentry's own propagator, not carried over
+      expect(registry?.propagation).not.toBe(propagator);
+    });
+
+    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);