feat(node-core): Add integration disabling mechanism to prevent instrumentation conflicts

RulaKhaled · RulaKhaled · commit fd717866ec47 · 2025-10-20T13:58:35.000+02:00
diff --git a/dev-packages/node-integration-tests/suites/tracing/langchain/instrument-with-pii.mjs b/dev-packages/node-integration-tests/suites/tracing/langchain/instrument-with-pii.mjs
@@ -7,8 +7,6 @@ Sentry.init({
   tracesSampleRate: 1.0,
   sendDefaultPii: true,
   transport: loggingTransport,
-  // Filter out Anthropic integration to avoid duplicate spans with LangChain
-  integrations: integrations => integrations.filter(integration => integration.name !== 'Anthropic_AI'),
   beforeSendTransaction: event => {
     // Filter out mock express server transactions
     if (event.transaction.includes('/v1/messages')) {
diff --git a/dev-packages/node-integration-tests/suites/tracing/langchain/instrument.mjs b/dev-packages/node-integration-tests/suites/tracing/langchain/instrument.mjs
@@ -7,8 +7,6 @@ Sentry.init({
   tracesSampleRate: 1.0,
   sendDefaultPii: false,
   transport: loggingTransport,
-  // Filter out Anthropic integration to avoid duplicate spans with LangChain
-  integrations: integrations => integrations.filter(integration => integration.name !== 'Anthropic_AI'),
   beforeSendTransaction: event => {
     // Filter out mock express server transactions
     if (event.transaction.includes('/v1/messages')) {
diff --git a/packages/node-core/src/index.ts b/packages/node-core/src/index.ts
@@ -32,6 +32,7 @@ export { pinoIntegration } from './integrations/pino';
 export { SentryContextManager } from './otel/contextManager';
 export { setupOpenTelemetryLogger } from './otel/logger';
 export { generateInstrumentOnce, instrumentWhenWrapped, INSTRUMENTED } from './otel/instrument';
+export { disableIntegration, isIntegrationDisabled, enableIntegration } from './otel/disabledIntegrations';
 
 export { init, getDefaultIntegrations, initWithoutDefaultIntegrations, validateOpenTelemetrySetup } from './sdk';
 export { setIsolationScope } from './sdk/scope';
diff --git a/packages/node-core/src/otel/disabledIntegrations.ts b/packages/node-core/src/otel/disabledIntegrations.ts
@@ -0,0 +1,37 @@
+/**
+ * Registry to track disabled integrations.
+ * This is used to prevent duplicate instrumentation when higher-level integrations
+ * (like LangChain) already instrument the underlying libraries (like OpenAI, Anthropic, etc.)
+ */
+
+const DISABLED_INTEGRATIONS = new Set<string>();
+
+/**
+ * Mark an integration as disabled to prevent its instrumentation from being set up.
+ * @param integrationName The name of the integration to disable
+ */
+export function disableIntegration(integrationName: string): void {
+  DISABLED_INTEGRATIONS.add(integrationName);
+}
+
+/**
+ * Check if an integration has been disabled.
+ * @param integrationName The name of the integration to check
+ * @returns true if the integration is disabled
+ */
+export function isIntegrationDisabled(integrationName: string): boolean {
+  return DISABLED_INTEGRATIONS.has(integrationName);
+}
+
+/**
+ * Remove an integration from the disabled list.
+ * @param integrationName The name of the integration to enable
+ */
+export function enableIntegration(integrationName: string): void {
+  DISABLED_INTEGRATIONS.delete(integrationName);
+}
+
+/** Exported only for tests. */
+export function clearDisabledIntegrations(): void {
+  DISABLED_INTEGRATIONS.clear();
+}
diff --git a/packages/node-core/test/otel/disabledIntegrations.test.ts b/packages/node-core/test/otel/disabledIntegrations.test.ts
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  clearDisabledIntegrations,
+  disableIntegration,
+  enableIntegration,
+  isIntegrationDisabled,
+} from '../../src/otel/disabledIntegrations';
+
+describe('disabledIntegrations', () => {
+  beforeEach(() => {
+    clearDisabledIntegrations();
+  });
+
+  it('should mark an integration as disabled', () => {
+    expect(isIntegrationDisabled('TestIntegration')).toBe(false);
+    disableIntegration('TestIntegration');
+    expect(isIntegrationDisabled('TestIntegration')).toBe(true);
+  });
+
+  it('should enable a disabled integration', () => {
+    disableIntegration('TestIntegration');
+    expect(isIntegrationDisabled('TestIntegration')).toBe(true);
+    enableIntegration('TestIntegration');
+    expect(isIntegrationDisabled('TestIntegration')).toBe(false);
+  });
+
+  it('should handle multiple integrations', () => {
+    disableIntegration('Integration1');
+    disableIntegration('Integration2');
+
+    expect(isIntegrationDisabled('Integration1')).toBe(true);
+    expect(isIntegrationDisabled('Integration2')).toBe(true);
+    expect(isIntegrationDisabled('Integration3')).toBe(false);
+  });
+
+  it('should clear all disabled integrations', () => {
+    disableIntegration('Integration1');
+    disableIntegration('Integration2');
+
+    expect(isIntegrationDisabled('Integration1')).toBe(true);
+    expect(isIntegrationDisabled('Integration2')).toBe(true);
+
+    clearDisabledIntegrations();
+
+    expect(isIntegrationDisabled('Integration1')).toBe(false);
+    expect(isIntegrationDisabled('Integration2')).toBe(false);
+  });
+});
diff --git a/packages/node/src/integrations/tracing/anthropic-ai/index.ts b/packages/node/src/integrations/tracing/anthropic-ai/index.ts
@@ -1,6 +1,6 @@
 import type { AnthropicAiOptions, IntegrationFn } from '@sentry/core';
 import { ANTHROPIC_AI_INTEGRATION_NAME, defineIntegration } from '@sentry/core';
-import { generateInstrumentOnce } from '@sentry/node-core';
+import { generateInstrumentOnce, isIntegrationDisabled } from '@sentry/node-core';
 import { SentryAnthropicAiInstrumentation } from './instrumentation';
 
 export const instrumentAnthropicAi = generateInstrumentOnce<AnthropicAiOptions>(
@@ -13,6 +13,10 @@ const _anthropicAIIntegration = ((options: AnthropicAiOptions = {}) => {
     name: ANTHROPIC_AI_INTEGRATION_NAME,
     options,
     setupOnce() {
+      // Skip instrumentation if disabled (e.g., when LangChain integration is active)
+      if (isIntegrationDisabled(ANTHROPIC_AI_INTEGRATION_NAME)) {
+        return;
+      }
       instrumentAnthropicAi(options);
     },
   };
diff --git a/packages/node/src/integrations/tracing/anthropic-ai/instrumentation.ts b/packages/node/src/integrations/tracing/anthropic-ai/instrumentation.ts
@@ -5,7 +5,8 @@ import {
   InstrumentationNodeModuleDefinition,
 } from '@opentelemetry/instrumentation';
 import type { AnthropicAiClient, AnthropicAiOptions } from '@sentry/core';
-import { getClient, instrumentAnthropicAiClient, SDK_VERSION } from '@sentry/core';
+import { ANTHROPIC_AI_INTEGRATION_NAME, getClient, instrumentAnthropicAiClient, SDK_VERSION } from '@sentry/core';
+import { isIntegrationDisabled } from '@sentry/node-core';
 
 const supportedVersions = ['>=0.19.2 <1.0.0'];
 
@@ -43,6 +44,11 @@ export class SentryAnthropicAiInstrumentation extends InstrumentationBase<Anthro
    * Core patch logic applying instrumentation to the Anthropic AI client constructor.
    */
   private _patch(exports: PatchedModuleExports): PatchedModuleExports | void {
+    // Skip patching if this integration has been disabled (e.g., by LangChain integration)
+    if (isIntegrationDisabled(ANTHROPIC_AI_INTEGRATION_NAME)) {
+      return exports;
+    }
+
     const Original = exports.Anthropic;
 
     const config = this.getConfig();
diff --git a/packages/node/src/integrations/tracing/google-genai/index.ts b/packages/node/src/integrations/tracing/google-genai/index.ts
@@ -1,6 +1,6 @@
 import type { GoogleGenAIOptions, IntegrationFn } from '@sentry/core';
 import { defineIntegration, GOOGLE_GENAI_INTEGRATION_NAME } from '@sentry/core';
-import { generateInstrumentOnce } from '@sentry/node-core';
+import { generateInstrumentOnce, isIntegrationDisabled } from '@sentry/node-core';
 import { SentryGoogleGenAiInstrumentation } from './instrumentation';
 
 export const instrumentGoogleGenAI = generateInstrumentOnce<GoogleGenAIOptions>(
@@ -12,6 +12,10 @@ const _googleGenAIIntegration = ((options: GoogleGenAIOptions = {}) => {
   return {
     name: GOOGLE_GENAI_INTEGRATION_NAME,
     setupOnce() {
+      // Skip instrumentation if disabled (e.g., when LangChain integration is active)
+      if (isIntegrationDisabled(GOOGLE_GENAI_INTEGRATION_NAME)) {
+        return;
+      }
       instrumentGoogleGenAI(options);
     },
   };
diff --git a/packages/node/src/integrations/tracing/google-genai/instrumentation.ts b/packages/node/src/integrations/tracing/google-genai/instrumentation.ts
@@ -6,7 +6,14 @@ import {
   InstrumentationNodeModuleFile,
 } from '@opentelemetry/instrumentation';
 import type { GoogleGenAIClient, GoogleGenAIOptions } from '@sentry/core';
-import { getClient, instrumentGoogleGenAIClient, replaceExports, SDK_VERSION } from '@sentry/core';
+import {
+  getClient,
+  GOOGLE_GENAI_INTEGRATION_NAME,
+  instrumentGoogleGenAIClient,
+  replaceExports,
+  SDK_VERSION,
+} from '@sentry/core';
+import { isIntegrationDisabled } from '@sentry/node-core';
 
 const supportedVersions = ['>=0.10.0 <2'];
 
@@ -57,6 +64,11 @@ export class SentryGoogleGenAiInstrumentation extends InstrumentationBase<Google
    * Core patch logic applying instrumentation to the Google GenAI client constructor.
    */
   private _patch(exports: PatchedModuleExports): PatchedModuleExports | void {
+    // Skip patching if this integration has been disabled (e.g., by LangChain integration)
+    if (isIntegrationDisabled(GOOGLE_GENAI_INTEGRATION_NAME)) {
+      return exports;
+    }
+
     const Original = exports.GoogleGenAI;
     const config = this.getConfig();
 
diff --git a/packages/node/src/integrations/tracing/index.ts b/packages/node/src/integrations/tracing/index.ts
@@ -32,6 +32,8 @@ import { instrumentVercelAi, vercelAIIntegration } from './vercelai';
  */
 export function getAutoPerformanceIntegrations(): Integration[] {
   return [
+    // LangChain must come first to disable AI provider integrations before they instrument
+    langChainIntegration(),
     expressIntegration(),
     fastifyIntegration(),
     graphqlIntegration(),
@@ -57,7 +59,6 @@ export function getAutoPerformanceIntegrations(): Integration[] {
     firebaseIntegration(),
     anthropicAIIntegration(),
     googleGenAIIntegration(),
-    langChainIntegration(),
   ];
 }
 
diff --git a/packages/node/src/integrations/tracing/langchain/index.ts b/packages/node/src/integrations/tracing/langchain/index.ts
@@ -1,6 +1,12 @@
 import type { IntegrationFn, LangChainOptions } from '@sentry/core';
-import { defineIntegration, LANGCHAIN_INTEGRATION_NAME } from '@sentry/core';
-import { generateInstrumentOnce } from '@sentry/node-core';
+import {
+  ANTHROPIC_AI_INTEGRATION_NAME,
+  defineIntegration,
+  GOOGLE_GENAI_INTEGRATION_NAME,
+  LANGCHAIN_INTEGRATION_NAME,
+  OPENAI_INTEGRATION_NAME,
+} from '@sentry/core';
+import { disableIntegration, generateInstrumentOnce } from '@sentry/node-core';
 import { SentryLangChainInstrumentation } from './instrumentation';
 
 export const instrumentLangChain = generateInstrumentOnce<LangChainOptions>(
@@ -12,6 +18,12 @@ const _langChainIntegration = ((options: LangChainOptions = {}) => {
   return {
     name: LANGCHAIN_INTEGRATION_NAME,
     setupOnce() {
+      // Disable AI provider integrations to prevent duplicate spans
+      // LangChain integration handles instrumentation for all underlying AI providers
+      disableIntegration(OPENAI_INTEGRATION_NAME);
+      disableIntegration(ANTHROPIC_AI_INTEGRATION_NAME);
+      disableIntegration(GOOGLE_GENAI_INTEGRATION_NAME);
+
       instrumentLangChain(options);
     },
   };
@@ -25,6 +37,10 @@ const _langChainIntegration = ((options: LangChainOptions = {}) => {
  * When configured, this integration automatically instruments LangChain runnable instances
  * to capture telemetry data by injecting Sentry callback handlers into all LangChain calls.
  *
+ * **Important:** This integration automatically disables the OpenAI, Anthropic, and Google GenAI
+ * integrations to prevent duplicate spans when using LangChain with these providers. LangChain
+ * handles the instrumentation for all underlying AI providers.
+ *
  * @example
  * ```javascript
  * import * as Sentry from '@sentry/node';
diff --git a/packages/node/src/integrations/tracing/openai/index.ts b/packages/node/src/integrations/tracing/openai/index.ts
@@ -1,6 +1,6 @@
 import type { IntegrationFn, OpenAiOptions } from '@sentry/core';
 import { defineIntegration, OPENAI_INTEGRATION_NAME } from '@sentry/core';
-import { generateInstrumentOnce } from '@sentry/node-core';
+import { generateInstrumentOnce, isIntegrationDisabled } from '@sentry/node-core';
 import { SentryOpenAiInstrumentation } from './instrumentation';
 
 export const instrumentOpenAi = generateInstrumentOnce(
@@ -13,6 +13,10 @@ const _openAiIntegration = ((options: OpenAiOptions = {}) => {
     name: OPENAI_INTEGRATION_NAME,
     options,
     setupOnce() {
+      // Skip instrumentation if disabled (e.g., when LangChain integration is active)
+      if (isIntegrationDisabled(OPENAI_INTEGRATION_NAME)) {
+        return;
+      }
       instrumentOpenAi();
     },
   };
diff --git a/packages/node/src/integrations/tracing/openai/instrumentation.ts b/packages/node/src/integrations/tracing/openai/instrumentation.ts
@@ -6,6 +6,7 @@ import {
 } from '@opentelemetry/instrumentation';
 import type { Integration, OpenAiClient, OpenAiOptions } from '@sentry/core';
 import { getClient, instrumentOpenAiClient, OPENAI_INTEGRATION_NAME, SDK_VERSION } from '@sentry/core';
+import { isIntegrationDisabled } from '@sentry/node-core';
 
 const supportedVersions = ['>=4.0.0 <6'];
 
@@ -53,6 +54,11 @@ export class SentryOpenAiInstrumentation extends InstrumentationBase<Instrumenta
    * Core patch logic applying instrumentation to the OpenAI client constructor.
    */
   private _patch(exports: PatchedModuleExports): PatchedModuleExports | void {
+    // Skip patching if this integration has been disabled (e.g., by LangChain integration)
+    if (isIntegrationDisabled(OPENAI_INTEGRATION_NAME)) {
+      return exports;
+    }
+
     const Original = exports.OpenAI;
 
     const WrappedOpenAI = function (this: unknown, ...args: unknown[]) {
