Refactor to proposed wrapping helpers

Author: andreiborza

dev-packages/node-integration-tests/suites/tracing/langchain/scenario-openai-before-langchain.mjs

@@ -0,0 +1,95 @@
+import * as Sentry from '@sentry/node';
+import express from 'express';
+
+function startMockAnthropicServer() {
+  const app = express();
+  app.use(express.json());
+
+  app.post('/v1/messages', (req, res) => {
+    res.json({
+      id: 'msg_test123',
+      type: 'message',
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: 'Mock response from Anthropic!',
+        },
+      ],
+      model: req.body.model,
+      stop_reason: 'end_turn',
+      stop_sequence: null,
+      usage: {
+        input_tokens: 10,
+        output_tokens: 15,
+      },
+    });
+  });
+
+  return new Promise(resolve => {
+    const server = app.listen(0, () => {
+      resolve(server);
+    });
+  });
+}
+
+async function run() {
+  const server = await startMockAnthropicServer();
+  const baseURL = `http://localhost:${server.address().port}`;
+
+  await Sentry.startSpan({ op: 'function', name: 'main' }, async () => {
+    // EDGE CASE: Import and instantiate Anthropic client BEFORE LangChain is imported
+    // This simulates the timing issue where a user creates an Anthropic client in one file
+    // before importing LangChain in another file
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+    const anthropicClient = new Anthropic({
+      apiKey: 'mock-api-key',
+      baseURL,
+    });
+
+    // Use the Anthropic client directly - this will be instrumented by the Anthropic integration
+    await anthropicClient.messages.create({
+      model: 'claude-3-5-sonnet-20241022',
+      messages: [{ role: 'user', content: 'Direct Anthropic call' }],
+      temperature: 0.7,
+      max_tokens: 100,
+    });
+
+    // NOW import LangChain - at this point it will mark Anthropic to be skipped
+    // But the client created above is already instrumented
+    const { ChatAnthropic } = await import('@langchain/anthropic');
+
+    // Create a LangChain model - this uses Anthropic under the hood
+    const langchainModel = new ChatAnthropic({
+      model: 'claude-3-5-sonnet-20241022',
+      temperature: 0.7,
+      maxTokens: 100,
+      apiKey: 'mock-api-key',
+      clientOptions: {
+        baseURL,
+      },
+    });
+
+    // Use LangChain - this will be instrumented by LangChain integration
+    await langchainModel.invoke('LangChain Anthropic call');
+
+    // Create ANOTHER Anthropic client after LangChain was imported
+    // This one should NOT be instrumented (skip mechanism works correctly)
+    const anthropicClient2 = new Anthropic({
+      apiKey: 'mock-api-key',
+      baseURL,
+    });
+
+    await anthropicClient2.messages.create({
+      model: 'claude-3-5-sonnet-20241022',
+      messages: [{ role: 'user', content: 'Second direct Anthropic call' }],
+      temperature: 0.7,
+      max_tokens: 100,
+    });
+  });
+
+  await Sentry.flush(2000);
+  server.close();
+}
+
+run();

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

@@ -245,4 +245,64 @@ describe('LangChain integration', () => {
       });
     },
   );
+
+  createEsmAndCjsTests(
+    __dirname,
+    'scenario-openai-before-langchain.mjs',
+    'instrument.mjs',
+    (createRunner, test) => {
+      test('demonstrates timing issue with duplicate spans (ESM only)', 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(
+                span =>
+                  span.description === 'messages 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(
+                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 === 'messages 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');
+
+              // - 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);
+            },
+          })
+          .start()
+          .completed();
+      });
+    },
+    // This test fails on CJS because we use dynamic imports to simulate importing LangChain after the Anthropic client is created
+    { failsOnCjs: true },
+  );
 });

packages/core/src/index.ts

@@ -55,15 +55,12 @@ export { initAndBind, setCurrentClient } from './sdk';
 export { createTransport } from './transports/base';
 export { makeOfflineTransport } from './transports/offline';
 export { makeMultiplexedTransport } from './transports/multiplexed';
+export { getIntegrationsToSetup, addIntegration, defineIntegration, installedIntegrations } from './integration';
 export {
-  getIntegrationsToSetup,
-  addIntegration,
-  defineIntegration,
-  installedIntegrations,
-  _markIntegrationsDisabled,
-  _isIntegrationMarkedDisabled,
-  _clearDisabledIntegrationsMarks,
-} from './integration';
+  _INTERNAL_skipAiProviderWrapping,
+  _INTERNAL_shouldSkipAiProviderWrapping,
+  _INTERNAL_clearAiProviderSkips,
+} from './utils/ai/providerSkip';
 export { applyScopeDataToEvent, mergeScopeData } from './utils/applyScopeDataToEvent';
 export { prepareEvent } from './utils/prepareEvent';
 export { createCheckInEnvelope } from './checkin';

packages/core/src/integration.ts

@@ -8,58 +8,6 @@ import { debug } from './utils/debug-logger';
 
 export const installedIntegrations: string[] = [];
 
-/**
- * Registry to track integrations marked as disabled.
- * This is used to prevent duplicate instrumentation when higher-level integrations
- * (like LangChain) already instrument the underlying libraries (like OpenAI, Anthropic, etc.)
- */
-const MARKED_DISABLED_INTEGRATIONS = new Set<string>();
-
-/**
- * Mark one or more integrations as disabled to prevent their instrumentation from being set up.
- * This should be called during an integration's setupOnce() phase.
- * The marked integrations will be skipped when their own setupOnce() is called.
- *
- * @internal This is an internal API for coordination between integrations, not for public use.
- * @param integrationName The name(s) of the integration(s) to mark as disabled
- */
-export function _markIntegrationsDisabled(integrationName: string | string[]): void {
-  const names = Array.isArray(integrationName) ? integrationName : [integrationName];
-  names.forEach(name => {
-    MARKED_DISABLED_INTEGRATIONS.add(name);
-    DEBUG_BUILD && debug.log(`Integration marked as disabled: ${name}`);
-  });
-}
-
-/**
- * Check if an integration has been marked as disabled.
- *
- * @internal This is an internal API for coordination between integrations, not for public use.
- * @param integrationName The name of the integration to check
- * @returns true if the integration is marked as disabled
- */
-export function _isIntegrationMarkedDisabled(integrationName: string): boolean {
-  return MARKED_DISABLED_INTEGRATIONS.has(integrationName);
-}
-
-/**
- * Clear all integration marks and remove marked integrations from the installed list.
- * This is automatically called at the start of Sentry.init() to ensure a clean state
- * between different client initializations.
- *
- * This also removes the marked integrations from the global installedIntegrations list,
- * allowing them to run setupOnce() again if they're included in a new client.
- *
- * @internal This is an internal API for coordination between integrations, not for public use.
- */
-export function _clearDisabledIntegrationsMarks(): void {
-  // Remove marked integrations from the installed list so they can setup again
-  const filtered = installedIntegrations.filter(integration => !MARKED_DISABLED_INTEGRATIONS.has(integration));
-  installedIntegrations.splice(0, installedIntegrations.length, ...filtered);
-
-  MARKED_DISABLED_INTEGRATIONS.clear();
-}
-
 /** Map of integrations assigned to a client */
 export type IntegrationIndex = {
   [key: string]: Integration;

packages/core/src/utils/ai/providerSkip.ts

@@ -0,0 +1,64 @@
+import { DEBUG_BUILD } from '../../debug-build';
+import { debug } from '../debug-logger';
+
+/**
+ * Registry tracking which AI provider modules should skip instrumentation wrapping.
+ *
+ * This prevents duplicate spans when a higher-level integration (like LangChain)
+ * already instruments AI providers at a higher abstraction level.
+ */
+const SKIPPED_AI_PROVIDERS = new Set<string>();
+
+/**
+ * Mark AI provider modules to skip instrumentation wrapping.
+ *
+ * This prevents duplicate spans when a higher-level integration (like LangChain)
+ * already instruments AI providers at a higher abstraction level.
+ *
+ * @internal
+ * @param modules - Array of npm module names to skip (e.g., '@anthropic-ai/sdk', 'openai')
+ *
+ * @example
+ * ```typescript
+ * // In LangChain integration
+ * _INTERNAL_skipAiProviderWrapping(['@anthropic-ai/sdk', 'openai', '@google/generative-ai']);
+ * ```
+ */
+export function _INTERNAL_skipAiProviderWrapping(modules: string[]): void {
+  modules.forEach(module => {
+    SKIPPED_AI_PROVIDERS.add(module);
+    DEBUG_BUILD && debug.log(`AI provider "${module}" wrapping will be skipped`);
+  });
+}
+
+/**
+ * Check if an AI provider module should skip instrumentation wrapping.
+ *
+ * @internal
+ * @param module - The npm module name (e.g., '@anthropic-ai/sdk', 'openai')
+ * @returns true if wrapping should be skipped
+ *
+ * @example
+ * ```typescript
+ * // In AI provider instrumentation
+ * if (_INTERNAL_shouldSkipAiProviderWrapping('@anthropic-ai/sdk')) {
+ *   return Reflect.construct(Original, args); // Don't instrument
+ * }
+ * ```
+ */
+export function _INTERNAL_shouldSkipAiProviderWrapping(module: string): boolean {
+  return SKIPPED_AI_PROVIDERS.has(module);
+}
+
+/**
+ * Clear all AI provider skip registrations.
+ *
+ * This is automatically called at the start of Sentry.init() to ensure a clean state
+ * between different client initializations.
+ *
+ * @internal
+ */
+export function _INTERNAL_clearAiProviderSkips(): void {
+  SKIPPED_AI_PROVIDERS.clear();
+  DEBUG_BUILD && debug.log('Cleared AI provider skip registrations');
+}

packages/core/test/lib/integration.test.ts

@@ -1,14 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, test, vi } from 'vitest';
 import { getCurrentScope } from '../../src/currentScopes';
-import {
-  _clearDisabledIntegrationsMarks,
-  _isIntegrationMarkedDisabled,
-  _markIntegrationsDisabled,
-  addIntegration,
-  getIntegrationsToSetup,
-  installedIntegrations,
-  setupIntegration,
-} from '../../src/integration';
+import { addIntegration, getIntegrationsToSetup, installedIntegrations, setupIntegration } from '../../src/integration';
 import { setCurrentClient } from '../../src/sdk';
 import type { Integration } from '../../src/types-hoist/integration';
 import type { CoreOptions } from '../../src/types-hoist/options';
@@ -691,60 +683,3 @@ describe('addIntegration', () => {
     expect(logs).toHaveBeenCalledWith('Integration skipped because it was already installed: test');
   });
 });
-
-describe('Integration marking system', () => {
-  beforeEach(() => {
-    _clearDisabledIntegrationsMarks();
-    installedIntegrations.splice(0, installedIntegrations.length);
-  });
-
-  afterEach(() => {
-    _clearDisabledIntegrationsMarks();
-  });
-
-  it('marks and checks single integration', () => {
-    expect(_isIntegrationMarkedDisabled('TestIntegration')).toBe(false);
-
-    _markIntegrationsDisabled('TestIntegration');
-
-    expect(_isIntegrationMarkedDisabled('TestIntegration')).toBe(true);
-  });
-
-  it('marks and checks multiple integrations', () => {
-    _markIntegrationsDisabled(['OpenAI', 'Anthropic', 'GoogleGenAI']);
-
-    expect(_isIntegrationMarkedDisabled('OpenAI')).toBe(true);
-    expect(_isIntegrationMarkedDisabled('Anthropic')).toBe(true);
-    expect(_isIntegrationMarkedDisabled('GoogleGenAI')).toBe(true);
-    expect(_isIntegrationMarkedDisabled('Other')).toBe(false);
-  });
-
-  it('clears marks and removes from installedIntegrations', () => {
-    // Simulate scenario: integrations installed, some marked for cleanup
-    installedIntegrations.push('LangChain', 'OpenAI', 'Anthropic', 'Normal');
-    _markIntegrationsDisabled(['OpenAI', 'Anthropic']);
-
-    _clearDisabledIntegrationsMarks();
-
-    // Marks are cleared
-    expect(_isIntegrationMarkedDisabled('OpenAI')).toBe(false);
-    expect(_isIntegrationMarkedDisabled('Anthropic')).toBe(false);
-
-    // Marked integrations removed from installed list (can setup again in new client)
-    expect(installedIntegrations).toEqual(['LangChain', 'Normal']);
-  });
-
-  it('handles multi-client scenario correctly', () => {
-    // First client with LangChain
-    installedIntegrations.push('LangChain', 'OpenAI');
-    _markIntegrationsDisabled('OpenAI');
-    expect(_isIntegrationMarkedDisabled('OpenAI')).toBe(true);
-
-    // Second client initialization clears marks
-    _clearDisabledIntegrationsMarks();
-
-    // OpenAI can be used standalone in second client
-    expect(_isIntegrationMarkedDisabled('OpenAI')).toBe(false);
-    expect(installedIntegrations).toEqual(['LangChain']); // OpenAI removed, can setup fresh
-  });
-});