fix(llmobs): add per-integration opt-out (#9733)

Adds a documented and typed `llmobs: false` per-integration option for langchain and modelcontextprotocol-sdk.

Author: crysmags

docs/API.md

@@ -21,6 +21,15 @@ tracer.use('pg', {
 })
 ```
 
+The `langchain` and `modelcontextprotocol-sdk` integrations accept an `llmobs` option. Setting it to `false` stops LLM Observability span capture for that integration only — APM spans and distributed trace context propagation are unaffected. This is useful when another enabled integration already captures the same operation and the input/output payloads would otherwise be stored twice:
+
+```javascript
+// Keep APM tracing for MCP, but let LangChain own the LLM Observability spans.
+tracer.use('modelcontextprotocol-sdk', {
+  llmobs: false
+})
+```
+
 <h5 id="amqplib"></h5>
 <h5 id="amqplib-tags"></h5>
 <h5 id="amqplib-config"></h5>

docs/test.ts

@@ -372,6 +372,7 @@ tracer.use('kafkajs');
 tracer.use('koa');
 tracer.use('koa', httpServerOptions);
 tracer.use('langchain');
+tracer.use('langchain', { llmobs: false });
 tracer.use('mariadb', { service: () => `my-custom-mariadb` })
 tracer.use('langgraph');
 tracer.use('memcached');
@@ -381,6 +382,7 @@ tracer.use('mocha');
 tracer.use('mocha', { service: 'mocha-service' });
 tracer.use('moleculer', moleculerOptions);
 tracer.use('modelcontextprotocol-sdk');
+tracer.use('modelcontextprotocol-sdk', { llmobs: false });
 tracer.use('mongodb-core');
 tracer.use('mongoose');
 tracer.use('mysql');

index.d.ts

@@ -1940,6 +1940,18 @@ declare namespace tracer {
     /** @hidden */
     interface Instrumentation extends Integration, Analyzable {}
 
+    /** @hidden */
+    interface LLMObsIntegration extends Integration {
+      /**
+       * Whether to capture LLM Observability spans for this integration. When set to `false`,
+       * the integration keeps emitting APM spans and propagating trace context, but no LLM
+       * Observability spans are produced. Useful when another integration already captures the
+       * same operation and the payloads would otherwise be stored twice.
+       * @default true
+       */
+      llmobs?: boolean;
+    }
+
     /** @hidden */
     interface DatabaseInstrumentation extends Instrumentation {
       /**
@@ -2804,7 +2816,7 @@ declare namespace tracer {
      * This plugin automatically instruments the
      * [langchain](https://js.langchain.com/) module
      */
-    interface langchain extends Instrumentation {}
+    interface langchain extends Instrumentation, LLMObsIntegration {}
 
     /**
      * This plugin automatically instruments the
@@ -2846,7 +2858,7 @@ declare namespace tracer {
      * This plugin automatically instruments the
      * [modelcontextprotocol-sdk](https://github.com/npmjs/package/@modelcontextprotocol/sdk) library.
      */
-    interface modelcontextprotocol_sdk extends Instrumentation {}
+    interface modelcontextprotocol_sdk extends Instrumentation, LLMObsIntegration {}
 
     /**
      * This plugin automatically instruments the

index.d.v5.ts

@@ -2052,6 +2052,18 @@ declare namespace tracer {
     /** @hidden */
     interface Instrumentation extends Integration, Analyzable {}
 
+    /** @hidden */
+    interface LLMObsIntegration extends Integration {
+      /**
+       * Whether to capture LLM Observability spans for this integration. When set to `false`,
+       * the integration keeps emitting APM spans and propagating trace context, but no LLM
+       * Observability spans are produced. Useful when another integration already captures the
+       * same operation and the payloads would otherwise be stored twice.
+       * @default true
+       */
+      llmobs?: boolean;
+    }
+
     /** @hidden */
     interface DatabaseInstrumentation extends Instrumentation {
       /**
@@ -2974,7 +2986,7 @@ declare namespace tracer {
      * This plugin automatically instruments the
      * [langchain](https://js.langchain.com/) module
      */
-    interface langchain extends Instrumentation {}
+    interface langchain extends Instrumentation, LLMObsIntegration {}
 
     /**
      * This plugin automatically instruments the
@@ -3016,7 +3028,7 @@ declare namespace tracer {
      * This plugin automatically instruments the
      * [modelcontextprotocol-sdk](https://github.com/npmjs/package/@modelcontextprotocol/sdk) library.
      */
-    interface modelcontextprotocol_sdk extends Instrumentation {}
+    interface modelcontextprotocol_sdk extends Instrumentation, LLMObsIntegration {}
 
     /**
      * This plugin automatically instruments the

packages/datadog-plugin-modelcontextprotocol-sdk/test/index.spec.js

@@ -10,6 +10,7 @@ const { expectSomeSpan } = require('../../dd-trace/test/plugins/helpers')
 const TestSetup = require('./test-setup')
 
 const testSetup = new TestSetup()
+const llmobsDisabledTestSetup = new TestSetup()
 const legacyStorage = storage('legacy')
 
 describe('plugin lifecycle', () => {
@@ -556,3 +557,70 @@ createIntegrationTestSuite('modelcontextprotocol-sdk', '@modelcontextprotocol/sd
     })
   })
 })
+
+// `llmobs: false` opts the integration out of LLM Observability span capture only: APM tracing and
+// the client -> server trace context propagation must keep working.
+createIntegrationTestSuite('modelcontextprotocol-sdk', '@modelcontextprotocol/sdk', {
+  subModule: '@modelcontextprotocol/sdk/client',
+  pluginConfig: { llmobs: false },
+}, (meta) => {
+  const { agent } = meta
+
+  before(async () => {
+    await llmobsDisabledTestSetup.setup(meta.mod, meta.versionMod)
+  })
+
+  after(async () => {
+    await llmobsDisabledTestSetup.teardown()
+  })
+
+  describe('with llmobs disabled', () => {
+    it('should still generate the client tool call span', async () => {
+      const traceAssertion = expectSomeSpan(agent, {
+        name: 'mcp.request',
+        type: 'mcp',
+        resource: 'client_tool_call',
+        meta: {
+          component: 'modelcontextprotocol_client',
+          '_dd.integration': 'modelcontextprotocol_client',
+          'span.kind': 'client',
+        },
+      })
+
+      const result = await llmobsDisabledTestSetup.clientCallTool()
+      assert.equal(result.content[0].text, 'Result from test-tool')
+
+      return traceAssertion
+    })
+
+    it('should still generate the client list tools span', async () => {
+      const traceAssertion = expectSomeSpan(agent, {
+        name: 'mcp.request',
+        type: 'mcp',
+        resource: 'ClientSession.list_tools',
+        meta: {
+          component: 'modelcontextprotocol_list_tools',
+          '_dd.integration': 'modelcontextprotocol_list_tools',
+          'span.kind': 'client',
+        },
+      })
+
+      const result = await llmobsDisabledTestSetup.clientListTools()
+      assert.equal(result.tools.length, 2)
+
+      return traceAssertion
+    })
+
+    it('should still parent the server request span to the client tool call span', async () => {
+      const spans = []
+      const traceAssertion = agent.assertSomeTraces(traces => {
+        spans.push(...traces.flatMap(trace => trace))
+        assertClientServerParenting(spans, 'client_tool_call')
+      })
+
+      await llmobsDisabledTestSetup.clientCallTool()
+
+      return traceAssertion
+    })
+  })
+})

packages/dd-trace/src/llmobs/plugins/base.js

@@ -84,9 +84,11 @@ class LLMObsPlugin extends TracingPlugin {
   }
 
   configure (config) {
-    // we do not want to enable any LLMObs plugins if it is disabled on the tracer
+    // we do not want to enable any LLMObs plugins if it is disabled on the tracer, or if the
+    // integration opted out via `tracer.use(<name>, { llmobs: false })`. Opting out only disables
+    // the LLMObs layer: the integration keeps emitting APM spans and propagating trace context.
     const llmobsEnabled = this._tracerConfig.llmobs.DD_LLMOBS_ENABLED
-    if (llmobsEnabled === false) {
+    if (llmobsEnabled === false || config?.llmobs === false) {
       config = typeof config === 'boolean' ? false : { ...config, enabled: false } // override to false
     }
     super.configure(config)

packages/dd-trace/test/llmobs/plugins/langchain/index.spec.js

@@ -121,6 +121,44 @@ describe('integrations', () => {
     })
   })
 
+  describe('langchain with llmobs disabled', () => {
+    const { assertNoLlmObsSpans } = useLlmObs({
+      plugin: 'langchain',
+      pluginConfig: { llmobs: false },
+    })
+
+    withVersions('langchain', ['@langchain/core'], (version) => {
+      let disabledTool
+
+      beforeEach(() => {
+        disabledTool = require(`../../../../../../versions/@langchain/core@${version}`)
+          .get('@langchain/core/tools')
+          .tool
+      })
+
+      it('does not create an LLMObs span for a tool invocation', async function () {
+        if (!disabledTool) this.skip()
+
+        const add = disabledTool(
+          ({ a, b }) => a + b,
+          {
+            name: 'add',
+            description: 'A tool that adds two numbers',
+            schema: {
+              a: { type: 'number' },
+              b: { type: 'number' },
+            },
+          }
+        )
+
+        const result = await add.invoke({ a: 1, b: 2 })
+        assert.equal(result, 3)
+
+        await assertNoLlmObsSpans()
+      })
+    })
+  })
+
   describe('langchain', () => {
     const { getEvents } = useLlmObs({ plugin: 'langchain' })