Preserve NODE_VERSION gating for OTEL data-loader span creation

Author: onurtemizkan

packages/react-router/src/server/instrumentation/reactRouter.ts

@@ -16,7 +16,7 @@ import {
 import type * as reactRouter from 'react-router';
 import { DEBUG_BUILD } from '../../common/debug-build';
 import { isServerBuildLike, setServerBuild } from '../serverBuild';
-import { isInstrumentationApiUsed } from '../serverGlobals';
+import { isInstrumentationApiUsed, isOtelDataLoaderSpanCreationEnabled } from '../serverGlobals';
 import { getOpName, getSpanName, isDataRequest } from './util';
 
 type ReactRouterModuleExports = typeof reactRouter;
@@ -81,12 +81,13 @@ export class ReactRouterInstrumentation extends InstrumentationBase<Instrumentat
 
             const originalRequestHandler = original.apply(this, args);
 
-            // Skip per-request wrapping when instrumentation API is active
-            if (isInstrumentationApiUsed()) {
-              return originalRequestHandler;
-            }
-
             return async function sentryWrappedRequestHandler(request: Request, initialContext?: unknown) {
+              // Skip OTEL span creation when instrumentation API is active or when span creation is not enabled.
+              // Checked per-request (not at handler-creation time) because in dev, createRequestHandler runs before entry.server.tsx.
+              if (isInstrumentationApiUsed() || !isOtelDataLoaderSpanCreationEnabled()) {
+                return originalRequestHandler(request, initialContext);
+              }
+
               let url: URL;
               try {
                 url = new URL(request.url);

packages/react-router/src/server/integration/reactRouterServer.ts

@@ -1,8 +1,9 @@
 import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
 import { defineIntegration } from '@sentry/core';
-import { generateInstrumentOnce } from '@sentry/node';
+import { generateInstrumentOnce, NODE_VERSION } from '@sentry/node';
 import { ReactRouterInstrumentation } from '../instrumentation/reactRouter';
 import { registerServerBuildGlobal } from '../serverBuild';
+import { enableOtelDataLoaderSpanCreation } from '../serverGlobals';
 
 const INTEGRATION_NAME = 'ReactRouterServer';
 
@@ -26,8 +27,16 @@ export const reactRouterServerIntegration = defineIntegration(() => {
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
+      // Enable OTEL data-loader spans only on Node versions without the diagnostics_channel-based instrumentation API.
+      if (
+        (NODE_VERSION.major === 20 && NODE_VERSION.minor < 19) ||
+        (NODE_VERSION.major === 22 && NODE_VERSION.minor < 12)
+      ) {
+        enableOtelDataLoaderSpanCreation();
+      }
+
       // Always install to capture ServerBuild for middleware names.
-      // Skips per-request wrapping when instrumentation API is active.
+      // Skips per-request wrapping when instrumentation API is active or OTEL span creation is disabled.
       instrumentReactRouterServer();
     },
     processEvent(event) {

packages/react-router/src/server/serverGlobals.ts

@@ -1,9 +1,11 @@
 import { GLOBAL_OBJ } from '@sentry/core';
 
 const SENTRY_SERVER_INSTRUMENTATION_FLAG = '__sentryReactRouterServerInstrumentationUsed';
+const SENTRY_OTEL_SPAN_CREATION_FLAG = '__sentryReactRouterOtelSpanCreationEnabled';
 
 type GlobalObjWithFlag = typeof GLOBAL_OBJ & {
   [SENTRY_SERVER_INSTRUMENTATION_FLAG]?: boolean;
+  [SENTRY_OTEL_SPAN_CREATION_FLAG]?: boolean;
 };
 
 /**
@@ -21,3 +23,19 @@ export function markInstrumentationApiUsed(): void {
 export function isInstrumentationApiUsed(): boolean {
   return !!(GLOBAL_OBJ as GlobalObjWithFlag)[SENTRY_SERVER_INSTRUMENTATION_FLAG];
 }
+
+/**
+ * Enable OTEL data-loader span creation for React Router server.
+ * @internal
+ */
+export function enableOtelDataLoaderSpanCreation(): void {
+  (GLOBAL_OBJ as GlobalObjWithFlag)[SENTRY_OTEL_SPAN_CREATION_FLAG] = true;
+}
+
+/**
+ * Check if OTEL data-loader span creation is enabled for React Router server.
+ * @internal
+ */
+export function isOtelDataLoaderSpanCreationEnabled(): boolean {
+  return !!(GLOBAL_OBJ as GlobalObjWithFlag)[SENTRY_OTEL_SPAN_CREATION_FLAG];
+}

packages/react-router/test/server/instrumentation/reactRouterServer.test.ts

@@ -65,6 +65,7 @@ describe('ReactRouterInstrumentation', () => {
   });
 
   it('should call original handler for non-data requests', async () => {
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(true);
     vi.spyOn(Util, 'isDataRequest').mockReturnValue(false);
 
     const proxy = (instrumentation as any)._createPatchedModuleProxy(mockModule);
@@ -77,6 +78,7 @@ describe('ReactRouterInstrumentation', () => {
   });
 
   it('should call original handler if no active root span', async () => {
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(true);
     vi.spyOn(Util, 'isDataRequest').mockReturnValue(true);
     vi.spyOn(SentryCore, 'getActiveSpan').mockReturnValue(undefined);
 
@@ -90,6 +92,7 @@ describe('ReactRouterInstrumentation', () => {
   });
 
   it('should start a span for data requests with active root span', async () => {
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(true);
     vi.spyOn(Util, 'isDataRequest').mockReturnValue(true);
     // @ts-expect-error MockSpan just for testing
     vi.spyOn(SentryCore, 'getActiveSpan').mockReturnValue(mockSpan as Span);
@@ -112,6 +115,7 @@ describe('ReactRouterInstrumentation', () => {
   });
 
   it('should handle invalid URLs gracefully', async () => {
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(true);
     const proxy = (instrumentation as any)._createPatchedModuleProxy(mockModule);
     const wrappedHandler = proxy.createRequestHandler();
     const req = { url: 'not a url', method: 'GET' } as any;
@@ -147,12 +151,40 @@ describe('ReactRouterInstrumentation', () => {
     expect(spy).toHaveBeenCalledWith(resolvedBuild);
   });
 
-  it('should return original handler without wrapping when instrumentation API is active', () => {
+  it('should bypass instrumentation when instrumentation API is active', async () => {
     vi.spyOn(ServerGlobals, 'isInstrumentationApiUsed').mockReturnValue(true);
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(true);
+    vi.spyOn(Util, 'isDataRequest').mockReturnValue(true);
+    const startSpanSpy = vi.spyOn(SentryCore, 'startSpan');
 
     const proxy = (instrumentation as any)._createPatchedModuleProxy(mockModule);
     const handler = proxy.createRequestHandler();
 
-    expect(handler).toBe(originalHandler);
+    // Handler is always wrapped; the instrumentation API check happens per-request
+    expect(handler).not.toBe(originalHandler);
+
+    const req = createRequest('https://test.com/data', 'GET');
+    await handler(req);
+
+    // Should delegate to original handler without creating spans
+    expect(originalHandler).toHaveBeenCalledWith(req, undefined);
+    expect(startSpanSpy).not.toHaveBeenCalled();
+  });
+
+  it('should skip span creation when OTEL data-loader span creation is disabled', async () => {
+    vi.spyOn(ServerGlobals, 'isInstrumentationApiUsed').mockReturnValue(false);
+    vi.spyOn(ServerGlobals, 'isOtelDataLoaderSpanCreationEnabled').mockReturnValue(false);
+    vi.spyOn(Util, 'isDataRequest').mockReturnValue(true);
+    const startSpanSpy = vi.spyOn(SentryCore, 'startSpan');
+
+    const proxy = (instrumentation as any)._createPatchedModuleProxy(mockModule);
+    const handler = proxy.createRequestHandler();
+
+    const req = createRequest('https://test.com/data', 'GET');
+    await handler(req);
+
+    // Should delegate to original handler without creating spans
+    expect(originalHandler).toHaveBeenCalledWith(req, undefined);
+    expect(startSpanSpy).not.toHaveBeenCalled();
   });
 });

packages/react-router/test/server/integration/reactRouterServer.test.ts

@@ -2,27 +2,35 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ReactRouterInstrumentation } from '../../../src/server/instrumentation/reactRouter';
 import { reactRouterServerIntegration } from '../../../src/server/integration/reactRouterServer';
 import * as serverBuild from '../../../src/server/serverBuild';
+import * as serverGlobals from '../../../src/server/serverGlobals';
 
 vi.mock('../../../src/server/instrumentation/reactRouter', () => {
   return {
     ReactRouterInstrumentation: vi.fn(),
   };
 });
 
+const mockNodeVersion = { major: 20, minor: 18, patch: 0 };
+
 vi.mock('@sentry/node', () => {
   return {
     generateInstrumentOnce: vi.fn((_name: string, callback: () => any) => {
       return Object.assign(callback, { id: 'test' });
     }),
+    get NODE_VERSION() {
+      return mockNodeVersion;
+    },
   };
 });
 
 describe('reactRouterServerIntegration', () => {
   let registerServerBuildGlobalSpy: ReturnType<typeof vi.spyOn>;
+  let enableOtelDataLoaderSpanCreationSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
     vi.clearAllMocks();
     registerServerBuildGlobalSpy = vi.spyOn(serverBuild, 'registerServerBuildGlobal');
+    enableOtelDataLoaderSpanCreationSpy = vi.spyOn(serverGlobals, 'enableOtelDataLoaderSpanCreation');
   });
 
   afterEach(() => {
@@ -42,4 +50,52 @@ describe('reactRouterServerIntegration', () => {
 
     expect(registerServerBuildGlobalSpy).toHaveBeenCalledTimes(1);
   });
+
+  it('enables OTEL data-loader span creation on Node 20.18', () => {
+    mockNodeVersion.major = 20;
+    mockNodeVersion.minor = 18;
+
+    const integration = reactRouterServerIntegration();
+    integration.setupOnce!();
+
+    expect(enableOtelDataLoaderSpanCreationSpy).toHaveBeenCalledTimes(1);
+    expect(ReactRouterInstrumentation).toHaveBeenCalledTimes(1);
+    expect(registerServerBuildGlobalSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('enables OTEL data-loader span creation on Node 22.11', () => {
+    mockNodeVersion.major = 22;
+    mockNodeVersion.minor = 11;
+
+    const integration = reactRouterServerIntegration();
+    integration.setupOnce!();
+
+    expect(enableOtelDataLoaderSpanCreationSpy).toHaveBeenCalledTimes(1);
+    expect(ReactRouterInstrumentation).toHaveBeenCalledTimes(1);
+    expect(registerServerBuildGlobalSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not enable OTEL data-loader span creation on Node 20.19', () => {
+    mockNodeVersion.major = 20;
+    mockNodeVersion.minor = 19;
+
+    const integration = reactRouterServerIntegration();
+    integration.setupOnce!();
+
+    expect(enableOtelDataLoaderSpanCreationSpy).not.toHaveBeenCalled();
+    expect(ReactRouterInstrumentation).toHaveBeenCalledTimes(1);
+    expect(registerServerBuildGlobalSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not enable OTEL data-loader span creation on Node 22.12', () => {
+    mockNodeVersion.major = 22;
+    mockNodeVersion.minor = 12;
+
+    const integration = reactRouterServerIntegration();
+    integration.setupOnce!();
+
+    expect(enableOtelDataLoaderSpanCreationSpy).not.toHaveBeenCalled();
+    expect(ReactRouterInstrumentation).toHaveBeenCalledTimes(1);
+    expect(registerServerBuildGlobalSpy).toHaveBeenCalledTimes(1);
+  });
 });