fix(node): Use context-scoped suppression for LangChain + AI provider span deduplication

dev-packages/node-integration-tests/suites/tracing/langchain/test.ts

@@ -313,49 +313,26 @@ describe('LangChain integration', () => {
     'scenario-openai-before-langchain.mjs',
     'instrument.mjs',
     (createRunner, test) => {
-      test('demonstrates timing issue with duplicate spans (ESM only)', async () => {
+      test('suppresses provider spans inside LangChain calls but keeps direct calls', async () => {
         await createRunner()
           .ignore('event')
           .expect({
             transaction: event => {
-              // This test highlights the limitation: if a user creates an Anthropic client
-              // before importing LangChain, that client will still be instrumented and
-              // could cause duplicate spans when used alongside LangChain.
-
               const spans = event.spans || [];
 
-              // First call: Direct Anthropic call made BEFORE LangChain import
-              // This should have Anthropic instrumentation (origin: 'auto.ai.anthropic')
-              const firstAnthropicSpan = spans.find(
+              const anthropicSpans = spans.filter(
                 span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.anthropic',
               );
-
-              // Second call: LangChain call
-              // This should have LangChain instrumentation (origin: 'auto.ai.langchain')
-              const langchainSpan = spans.find(
+              const langchainSpans = spans.filter(
                 span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.langchain',
               );
 
-              // Third call: Direct Anthropic call made AFTER LangChain import
-              // This should NOT have Anthropic instrumentation (skip works correctly)
-              // Count how many Anthropic spans we have - should be exactly 1
-              const anthropicSpans = spans.filter(
-                span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.anthropic',
-              );
-
-              // Verify the edge case limitation:
-              // - First Anthropic client (created before LangChain) IS instrumented
-              expect(firstAnthropicSpan).toBeDefined();
-              expect(firstAnthropicSpan?.origin).toBe('auto.ai.anthropic');
-
-              // - LangChain call IS instrumented by LangChain
-              expect(langchainSpan).toBeDefined();
-              expect(langchainSpan?.origin).toBe('auto.ai.langchain');
+              // Both direct Anthropic calls (before and after LangChain import) should produce spans
+              // Context-scoped suppression only suppresses spans inside LangChain calls, not globally
+              expect(anthropicSpans).toHaveLength(2);
 
-              // - Second Anthropic client (created after LangChain) is NOT instrumented
-              // This demonstrates that the skip mechanism works for NEW clients
-              // We should only have ONE Anthropic span (the first one), not two
-              expect(anthropicSpans).toHaveLength(1);
+              // LangChain call should produce exactly one LangChain span
+              expect(langchainSpans).toHaveLength(1);
             },
           })
           .start()

dev-packages/node-integration-tests/suites/tracing/langchain/v1/test.ts

@@ -347,49 +347,26 @@ conditionalTest({ min: 20 })('LangChain integration (v1)', () => {
     'scenario-openai-before-langchain.mjs',
     'instrument.mjs',
     (createRunner, test) => {
-      test('demonstrates timing issue with duplicate spans (ESM only)', async () => {
+      test('suppresses provider spans inside LangChain calls but keeps direct calls', async () => {
         await createRunner()
           .ignore('event')
           .expect({
             transaction: event => {
-              // This test highlights the limitation: if a user creates an Anthropic client
-              // before importing LangChain, that client will still be instrumented and
-              // could cause duplicate spans when used alongside LangChain.
-
               const spans = event.spans || [];
 
-              // First call: Direct Anthropic call made BEFORE LangChain import
-              // This should have Anthropic instrumentation (origin: 'auto.ai.anthropic')
-              const firstAnthropicSpan = spans.find(
+              const anthropicSpans = spans.filter(
                 span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.anthropic',
               );
-
-              // Second call: LangChain call
-              // This should have LangChain instrumentation (origin: 'auto.ai.langchain')
-              const langchainSpan = spans.find(
+              const langchainSpans = spans.filter(
                 span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.langchain',
               );
 
-              // Third call: Direct Anthropic call made AFTER LangChain import
-              // This should NOT have Anthropic instrumentation (skip works correctly)
-              // Count how many Anthropic spans we have - should be exactly 1
-              const anthropicSpans = spans.filter(
-                span => span.description === 'chat claude-3-5-sonnet-20241022' && span.origin === 'auto.ai.anthropic',
-              );
-
-              // Verify the edge case limitation:
-              // - First Anthropic client (created before LangChain) IS instrumented
-              expect(firstAnthropicSpan).toBeDefined();
-              expect(firstAnthropicSpan?.origin).toBe('auto.ai.anthropic');
-
-              // - LangChain call IS instrumented by LangChain
-              expect(langchainSpan).toBeDefined();
-              expect(langchainSpan?.origin).toBe('auto.ai.langchain');
+              // Both direct Anthropic calls (before and after LangChain import) should produce spans
+              // Context-scoped suppression only suppresses spans inside LangChain calls, not globally
+              expect(anthropicSpans).toHaveLength(2);
 
-              // - Second Anthropic client (created after LangChain) is NOT instrumented
-              // This demonstrates that the skip mechanism works for NEW clients
-              // We should only have ONE Anthropic span (the first one), not two
-              expect(anthropicSpans).toHaveLength(1);
+              // LangChain call should produce exactly one LangChain span
+              expect(langchainSpans).toHaveLength(1);
             },
           })
           .start()

packages/core/src/index.ts

@@ -58,10 +58,9 @@ export { makeOfflineTransport } from './transports/offline';
 export { makeMultiplexedTransport, MULTIPLEXED_TRANSPORT_EXTRA_KEY } from './transports/multiplexed';
 export { getIntegrationsToSetup, addIntegration, defineIntegration, installedIntegrations } from './integration';
 export {
-  _INTERNAL_skipAiProviderWrapping,
-  _INTERNAL_shouldSkipAiProviderWrapping,
-  _INTERNAL_clearAiProviderSkips,
-} from './utils/ai/providerSkip';
+  _INTERNAL_isAiProviderSpanSuppressed,
+  _INTERNAL_withSuppressedAiProviderSpans,
+} from './tracing/ai/suppression';
 export { envToBool } from './utils/envToBool';
 export { applyScopeDataToEvent, mergeScopeData, getCombinedScopeData } from './utils/scopeData';
 export { prepareEvent } from './utils/prepareEvent';

packages/core/src/tracing/ai/suppression.ts

@@ -0,0 +1,27 @@
+import { getCurrentScope, withScope } from '../../currentScopes';
+import type { Scope } from '../../scope';
+
+const SUPPRESS_AI_PROVIDER_SPANS_KEY = '__SENTRY_SUPPRESS_AI_PROVIDER_SPANS__';
+
+/**
+ * Check if AI provider spans should be suppressed in the current scope.
+ *
+ * @internal
+ */
+export function _INTERNAL_isAiProviderSpanSuppressed(): boolean {
+  return getCurrentScope().getScopeData().sdkProcessingMetadata[SUPPRESS_AI_PROVIDER_SPANS_KEY] === true;
+}
+
+/**
+ * Execute a callback with AI provider spans suppressed in the current scope.
+ * This is used by higher-level integrations (like LangChain) to prevent
+ * duplicate spans from underlying AI provider instrumentations.
+ *
+ * @internal
+ */
+export function _INTERNAL_withSuppressedAiProviderSpans<T>(callback: () => T): T {
+  return withScope((scope: Scope) => {
+    scope.setSDKProcessingMetadata({ [SUPPRESS_AI_PROVIDER_SPANS_KEY]: true });
+    return callback();
+  });
+}

packages/core/src/tracing/anthropic-ai/index.ts

@@ -2,6 +2,7 @@ import { getClient } from '../../currentScopes';
 import { captureException } from '../../exports';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
 import { SPAN_STATUS_ERROR } from '../../tracing';
+import { _INTERNAL_isAiProviderSpanSuppressed } from '../../tracing/ai/suppression';
 import { startSpan, startSpanManual } from '../../tracing/trace';
 import type { Span, SpanAttributeValue } from '../../types-hoist/span';
 import { handleCallbackErrors } from '../../utils/handleCallbackErrors';
@@ -256,6 +257,10 @@ function instrumentMethod<T extends unknown[], R>(
 ): (...args: T) => R | Promise<R> {
   return new Proxy(originalMethod, {
     apply(target, thisArg, args: T): R | Promise<R> {
+      if (_INTERNAL_isAiProviderSpanSuppressed()) {
+        return Reflect.apply(target, thisArg, args);
+      }
+
       const requestAttributes = extractRequestAttributes(args, methodPath);
       const model = requestAttributes[GEN_AI_REQUEST_MODEL_ATTRIBUTE] ?? 'unknown';
       const operationName = getFinalOperationName(methodPath);

packages/core/src/tracing/google-genai/index.ts

@@ -2,6 +2,7 @@ import { getClient } from '../../currentScopes';
 import { captureException } from '../../exports';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
 import { SPAN_STATUS_ERROR } from '../../tracing';
+import { _INTERNAL_isAiProviderSpanSuppressed } from '../../tracing/ai/suppression';
 import { startSpan, startSpanManual } from '../../tracing/trace';
 import type { Span, SpanAttributeValue } from '../../types-hoist/span';
 import { handleCallbackErrors } from '../../utils/handleCallbackErrors';
@@ -260,6 +261,10 @@ function instrumentMethod<T extends unknown[], R>(
 
   return new Proxy(originalMethod, {
     apply(target, _, args: T): R | Promise<R> {
+      if (_INTERNAL_isAiProviderSpanSuppressed()) {
+        return Reflect.apply(target, _, args);
+      }
+
       const params = args[0] as Record<string, unknown> | undefined;
       const requestAttributes = extractRequestAttributes(methodPath, params, context);
       const model = requestAttributes[GEN_AI_REQUEST_MODEL_ATTRIBUTE] ?? 'unknown';

packages/core/src/tracing/openai/index.ts

@@ -19,6 +19,7 @@ import {
   GEN_AI_SYSTEM_INSTRUCTIONS_ATTRIBUTE,
   OPENAI_OPERATIONS,
 } from '../ai/gen-ai-attributes';
+import { _INTERNAL_isAiProviderSpanSuppressed } from '../ai/suppression';
 import { extractSystemInstructions, getTruncatedJsonString } from '../ai/utils';
 import { instrumentStream } from './streaming';
 import type {
@@ -254,6 +255,10 @@ function instrumentMethod<T extends unknown[], R>(
   options: OpenAiOptions,
 ): (...args: T) => Promise<R> {
   return function instrumentedMethod(...args: T): Promise<R> {
+    if (_INTERNAL_isAiProviderSpanSuppressed()) {
+      return originalMethod.apply(context, args) as Promise<R>;
+    }
+
     const requestAttributes = extractRequestAttributes(args, methodPath);
     const model = (requestAttributes[GEN_AI_REQUEST_MODEL_ATTRIBUTE] as string) || 'unknown';
     const operationName = getOperationName(methodPath);

packages/core/src/tracing/vercel-ai/index.ts

@@ -1,4 +1,3 @@
-/* eslint-disable max-lines */
 import type { Client } from '../../client';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
 import type { Event } from '../../types-hoist/event';

packages/node-core/src/sdk/client.ts

@@ -4,14 +4,7 @@ import { trace } from '@opentelemetry/api';
 import { registerInstrumentations } from '@opentelemetry/instrumentation';
 import type { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 import type { DynamicSamplingContext, Scope, ServerRuntimeClientOptions, TraceContext } from '@sentry/core';
-import {
-  _INTERNAL_clearAiProviderSkips,
-  _INTERNAL_flushLogsBuffer,
-  applySdkMetadata,
-  debug,
-  SDK_VERSION,
-  ServerRuntimeClient,
-} from '@sentry/core';
+import { _INTERNAL_flushLogsBuffer, applySdkMetadata, debug, SDK_VERSION, ServerRuntimeClient } from '@sentry/core';
 import { type AsyncLocalStorageLookup, getTraceContextForScope } from '@sentry/opentelemetry';
 import { isMainThread, threadId } from 'worker_threads';
 import { DEBUG_BUILD } from '../debug-build';
@@ -157,10 +150,6 @@ export class NodeClient extends ServerRuntimeClient<NodeClientOptions> {
 
   /** @inheritDoc */
   protected _setupIntegrations(): void {
-    // Clear AI provider skip registrations before setting up integrations
-    // This ensures a clean state between different client initializations
-    // (e.g., when LangChain skips OpenAI in one client, but a subsequent client uses OpenAI standalone)
-    _INTERNAL_clearAiProviderSkips();
     super._setupIntegrations();
   }