dd-trace 5.98.0 → 5.99.1

package/packages/dd-trace/src/llmobs/plugins/{anthropic.js → anthropic/index.js}

@@ -1,7 +1,8 @@
 'use strict'
 
-const { UNKNOWN_MODEL_PROVIDER } = require('../constants/tags')
-const LLMObsPlugin = require('./base')
+const { UNKNOWN_MODEL_PROVIDER } = require('../../constants/tags')
+const LLMObsPlugin = require('../base')
+const { appendMessage } = require('./util')
 
 const ALLOWED_METADATA_KEYS = new Set([
   'max_tokens',
@@ -144,51 +145,11 @@ class AnthropicLLMObsPlugin extends LLMObsPlugin {
     const inputMessages = []
 
     if (system) {
-      messages.unshift({ content: system, role: 'system' })
+      appendMessage(inputMessages, { role: 'system', content: system })
     }
 
     for (const message of messages) {
-      const { content, role } = message
-
-      if (typeof content === 'string') {
-        inputMessages.push({ content, role })
-        continue
-      }
-
-      for (const block of content) {
-        if (block.type === 'text') {
-          inputMessages.push({ content: block.text, role })
-        } else if (block.type === 'image') {
-          inputMessages.push({ content: '([IMAGE DETECTED])', role })
-        } else if (block.type === 'tool_use') {
-          const { text, name, id, type } = block
-          let input = block.input
-          if (typeof input === 'string') {
-            input = JSON.parse(input)
-          }
-
-          const toolCall = {
-            name,
-            arguments: input,
-            toolId: id,
-            type,
-          }
-
-          inputMessages.push({ content: text ?? '', role, toolCalls: [toolCall] })
-        } else if (block.type === 'tool_result') {
-          const { content } = block
-          const formattedContent = this.#formatAnthropicToolResultContent(content)
-          const toolResult = {
-            result: formattedContent,
-            toolId: block.tool_use_id,
-            type: 'tool_result',
-          }
-
-          inputMessages.push({ content: '', role, toolResults: [toolResult] })
-        } else {
-          inputMessages.push({ content: JSON.stringify(block), role })
-        }
-      }
+      appendMessage(inputMessages, message)
     }
 
     this._tagger.tagLLMIO(span, inputMessages)
@@ -273,25 +234,6 @@ class AnthropicLLMObsPlugin extends LLMObsPlugin {
 
     this._tagger.tagMetrics(span, metrics)
   }
-
-  // maybe can make into a util file
-  #formatAnthropicToolResultContent (content) {
-    if (typeof content === 'string') {
-      return content
-    } else if (Array.isArray(content)) {
-      const formattedContent = []
-      for (const toolResultBlock of content) {
-        if (toolResultBlock.text) {
-          formattedContent.push(toolResultBlock.text)
-        } else if (toolResultBlock.type === 'image') {
-          formattedContent.push('([IMAGE DETECTED])')
-        }
-      }
-
-      return formattedContent.join(',')
-    }
-    return JSON.stringify(content)
-  }
 }
 
 module.exports = AnthropicLLMObsPlugin

package/packages/dd-trace/src/llmobs/plugins/anthropic/util.js

@@ -0,0 +1,106 @@
+'use strict'
+
+/**
+ * @typedef {{type: 'text', text: string}} TextBlock
+ * @typedef {{type: 'image'}} ImageBlock
+ * @typedef {{
+ *  type: 'tool_use', text: string, name: string, id: string, input: string | Record<string, unknown>
+ * }} ToolUseBlock
+ * @typedef {{
+ *  type: 'tool_result',
+ *  tool_use_id: string,
+ *  content: string | Array<{type: string, text?: string}>
+ * }} ToolResultBlock
+ *
+ * @typedef {{
+ *   content: string,
+ *   role: string,
+ *   toolCalls?: Array<{
+ *     name: string,
+ *     arguments: string | Record<string, unknown>,
+ *     toolId: string,
+ *     type: string
+ *   }>,
+ *   toolResults?: Array<{
+ *     result: string,
+ *     toolId: string,
+ *     type: 'tool_result'
+ *   }>
+ * }} AnthropicLlmObsMessage
+ */
+
+/**
+ * Formats tool result into LLM Observability compatible contents
+ * @param {ToolResultBlock['content']} content
+ */
+function formatAnthropicToolResultContent (content) {
+  if (typeof content === 'string') {
+    return content
+  } else if (Array.isArray(content)) {
+    const formattedContent = []
+    for (const toolResultBlock of content) {
+      if (toolResultBlock.text) {
+        formattedContent.push(toolResultBlock.text)
+      } else if (toolResultBlock.type === 'image') {
+        formattedContent.push('([IMAGE DETECTED])')
+      }
+    }
+
+    return formattedContent.join(',')
+  }
+  return JSON.stringify(content)
+}
+
+/**
+ * Normalizes and formats a message into LLM Observability compatible contents.
+ * Can be spread into a list of other messages.
+ *
+ * @param {AnthropicLlmObsMessage[]} messages
+ * @param {{ role: string, content: string | Array<TextBlock | ImageBlock | ToolUseBlock | ToolResultBlock> }} message
+ * @returns {void}
+ */
+function appendMessage (messages, { role, content }) {
+  if (typeof content === 'string') {
+    messages.push({ content, role })
+    return
+  }
+
+  for (const block of content) {
+    if (block.type === 'text') {
+      messages.push({ content: block.text, role })
+    } else if (block.type === 'image') {
+      messages.push({ content: '([IMAGE DETECTED])', role })
+    } else if (block.type === 'tool_use') {
+      const { text, name, id, type } = block
+      let input = block.input
+      if (typeof input === 'string') {
+        input = JSON.parse(input)
+      }
+
+      const toolCall = {
+        name,
+        arguments: input,
+        toolId: id,
+        type,
+      }
+
+      messages.push({ content: text ?? '', role, toolCalls: [toolCall] })
+    } else if (block.type === 'tool_result') {
+      const { content } = block
+      const formattedContent = formatAnthropicToolResultContent(content)
+      const toolResult = {
+        result: formattedContent,
+        toolId: block.tool_use_id,
+        type: 'tool_result',
+      }
+
+      messages.push({ content: '', role, toolResults: [toolResult] })
+    } else {
+      messages.push({ content: JSON.stringify(block), role })
+    }
+  }
+}
+
+module.exports = {
+  appendMessage,
+}

package/packages/dd-trace/src/llmobs/plugins/langchain/handlers/chain.js

@@ -1,16 +1,17 @@
 'use strict'
 
 const { spanHasError } = require('../../../util')
+const { formatIO } = require('../messages')
 const LangChainLLMObsHandler = require('.')
 
 class LangChainLLMObsChainHandler extends LangChainLLMObsHandler {
   setMetaTags ({ span, inputs, results }) {
     let input
     if (inputs) {
-      input = this.formatIO(inputs)
+      input = formatIO(inputs)
     }
 
-    const output = !results || spanHasError(span) ? '' : this.formatIO(results)
+    const output = !results || spanHasError(span) ? '' : formatIO(results)
 
     // chain spans will always be workflows
     this._tagger.tagTextIO(span, input, output)

package/packages/dd-trace/src/llmobs/plugins/langchain/handlers/chat_model.js

@@ -2,6 +2,7 @@
 
 const LLMObsTagger = require('../../../tagger')
 const { spanHasError } = require('../../../util')
+const { getRole } = require('../messages')
 const LangChainLLMObsHandler = require('.')
 
 const LLM = 'llm'
@@ -22,7 +23,7 @@ class LangChainLLMObsChatModelHandler extends LangChainLLMObsHandler {
     for (const messageSet of inputs) {
       for (const message of messageSet) {
         const content = message.content || ''
-        const role = this.getRole(message)
+        const role = getRole(message)
         inputMessages.push({ content, role })
       }
     }
@@ -54,7 +55,7 @@ class LangChainLLMObsChatModelHandler extends LangChainLLMObsHandler {
     for (const messageSet of results.generations) {
       for (const chatCompletion of messageSet) {
         const chatCompletionMessage = chatCompletion.message
-        const role = this.getRole(chatCompletionMessage)
+        const role = getRole(chatCompletionMessage)
         const content = chatCompletionMessage.text || ''
         const toolCalls = this.extractToolCalls(chatCompletionMessage)
         outputMessages.push({ content, role, toolCalls })

package/packages/dd-trace/src/llmobs/plugins/langchain/handlers/embedding.js

@@ -2,6 +2,7 @@
 
 const LLMObsTagger = require('../../../tagger')
 const { spanHasError } = require('../../../util')
+const { formatIO } = require('../messages')
 const LangChainLLMObsHandler = require('.')
 
 class LangChainLLMObsEmbeddingHandler extends LangChainLLMObsHandler {
@@ -10,7 +11,7 @@ class LangChainLLMObsEmbeddingHandler extends LangChainLLMObsHandler {
     let embeddingInput, embeddingOutput
 
     if (isWorkflow) {
-      embeddingInput = this.formatIO(inputs)
+      embeddingInput = formatIO(inputs)
     } else {
       const input = Array.isArray(inputs) ? inputs : [inputs]
       embeddingInput = input.map(doc => ({ text: doc }))

package/packages/dd-trace/src/llmobs/plugins/langchain/handlers/index.js

@@ -1,11 +1,5 @@
 'use strict'
 
-const ROLE_MAPPINGS = {
-  human: 'user',
-  ai: 'assistant',
-  system: 'system',
-}
-
 class LangChainLLMObsHandler {
   constructor (tagger) {
     /** @type {import('../../../tagger')} */
@@ -18,38 +12,6 @@ class LangChainLLMObsHandler {
 
   setMetaTags () {}
 
-  formatIO (messages) {
-    if (messages.constructor.name === 'Object') { // plain JSON
-      const formatted = {}
-      for (const [key, value] of Object.entries(messages)) {
-        formatted[key] = this.formatIO(value)
-      }
-
-      return formatted
-    } else if (Array.isArray(messages)) {
-      return messages.map(message => this.formatIO(message))
-    } // either a BaseMesage type or a string
-    return this.getContentFromMessage(messages)
-  }
-
-  getContentFromMessage (message) {
-    if (typeof message === 'string') {
-      return message
-    }
-    try {
-      const messageContent = {
-        content: message.content || '',
-      }
-
-      const role = this.getRole(message)
-      if (role) messageContent.role = role
-
-      return messageContent
-    } catch {
-      return JSON.stringify(message)
-    }
-  }
-
   checkTokenUsageChatOrLLMResult (results) {
     const llmOutput = results.llmOutput
     const tokens = {
@@ -90,17 +52,6 @@ class LangChainLLMObsHandler {
       runId: runIdBase,
     }
   }
-
-  getRole (message) {
-    if (message.role) return ROLE_MAPPINGS[message.role] || message.role
-
-    const type = (
-      (typeof message.getType === 'function' && message.getType()) ||
-      (typeof message._getType === 'function' && message._getType())
-    )
-
-    return ROLE_MAPPINGS[type] || type
-  }
 }
 
 module.exports = LangChainLLMObsHandler

package/packages/dd-trace/src/llmobs/plugins/langchain/handlers/vectorstore.js

@@ -1,11 +1,12 @@
 'use strict'
 
 const { spanHasError } = require('../../../util')
+const { formatIO } = require('../messages')
 const LangChainLLMObsHandler = require('.')
 
 class LangChainLLMObsVectorStoreHandler extends LangChainLLMObsHandler {
   setMetaTags ({ span, inputs, results }) {
-    const input = this.formatIO(inputs)
+    const input = formatIO(inputs)
     if (spanHasError(span)) {
       this._tagger.tagRetrievalIO(span, input)
       return

package/packages/dd-trace/src/llmobs/plugins/langchain/messages.js

@@ -0,0 +1,76 @@
+'use strict'
+
+const ROLE_MAPPINGS = {
+  human: 'user',
+  ai: 'assistant',
+  system: 'system',
+}
+
+function getRole (message) {
+  if (message.role) return ROLE_MAPPINGS[message.role] || message.role
+
+  const type = (
+    (typeof message.getType === 'function' && message.getType()) ||
+    (typeof message._getType === 'function' && message._getType())
+  )
+
+  return ROLE_MAPPINGS[type] || type
+}
+
+function getContentFromMessage (message) {
+  if (typeof message === 'string') {
+    return message
+  }
+  try {
+    const messageContent = {
+      content: message.content || '',
+    }
+
+    const role = getRole(message)
+    if (role) messageContent.role = role
+
+    return messageContent
+  } catch {
+    return JSON.stringify(message)
+  }
+}
+
+function isBaseMessage (data) {
+  return typeof data._getType === 'function' || typeof data.getType === 'function'
+}
+
+function formatIO (data) {
+  if (data == null) return ''
+
+  if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+    return data
+  }
+
+  if (data.constructor?.name === 'Object') {
+    const formatted = {}
+    for (const [key, value] of Object.entries(data)) {
+      formatted[key] = formatIO(value)
+    }
+    return formatted
+  }
+
+  if (Array.isArray(data)) {
+    return data.map(item => formatIO(item))
+  }
+
+  // Only duck-typed BaseMessage instances collapse to { content, role }.
+  // Other class instances (e.g. LangChain Document) preserve their shape via JSON.stringify,
+  // otherwise they'd reduce to { content: '' } and lose data.
+  if (isBaseMessage(data)) return getContentFromMessage(data)
+
+  try {
+    return JSON.stringify(data)
+  } catch {
+    return String(data)
+  }
+}
+
+module.exports = {
+  getRole,
+  formatIO,
+}

package/packages/dd-trace/src/llmobs/plugins/langgraph/index.js

@@ -1,36 +1,11 @@
 'use strict'
 
 const LLMObsPlugin = require('../base')
+const { formatIO } = require('../langchain/messages')
 const { spanHasError } = require('../../util')
 
 const streamDataMap = new WeakMap()
 
-function formatIO (data) {
-  if (data == null) return ''
-
-  if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
-    return data
-  }
-
-  if (data.constructor?.name === 'Object') {
-    const formatted = {}
-    for (const [key, value] of Object.entries(data)) {
-      formatted[key] = formatIO(value)
-    }
-    return formatted
-  }
-
-  if (Array.isArray(data)) {
-    return data.map(item => formatIO(item))
-  }
-
-  try {
-    return JSON.stringify(data)
-  } catch {
-    return String(data)
-  }
-}
-
 class PregelStreamLLMObsPlugin extends LLMObsPlugin {
   static id = 'llmobs_langgraph_pregel_stream'
   static integration = 'langgraph'

package/packages/dd-trace/src/llmobs/plugins/modelcontextprotocol-sdk/index.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const LLMObsPlugin = require('../base')
+const { formatInput, formatOutput } = require('./utils')
+
+class McpToolCallLLMObsPlugin extends LLMObsPlugin {
+  static id = 'llmobs_mcp_tool_call'
+  static integration = 'modelcontextprotocol-sdk'
+  static prefix = 'tracing:orchestrion:@modelcontextprotocol/sdk:Client_callTool'
+
+  getLLMObsSpanRegisterOptions (ctx) {
+    const params = ctx.arguments?.[0]
+    const toolName = params?.name || 'unknown_tool'
+
+    return {
+      kind: 'tool',
+      name: `MCP Client Tool Call: ${toolName}`,
+    }
+  }
+
+  setLLMObsTags (ctx) {
+    const span = ctx.currentStore?.span
+    if (!span) return
+
+    const params = ctx.arguments?.[0]
+    const toolName = params?.name
+    const toolArguments = params?.arguments
+
+    const spanTags = { mcp_tool_kind: 'client' }
+
+    const serverVersion = ctx.self?.getServerVersion?.()
+    if (serverVersion) {
+      if (serverVersion.name) spanTags.mcp_server_name = serverVersion.name
+      if (serverVersion.version) spanTags.mcp_server_version = serverVersion.version
+      if (serverVersion.title) spanTags.mcp_server_title = serverVersion.title
+    }
+
+    this._tagger.tagSpanTags(span, spanTags)
+
+    const hasError = ctx.error || ctx.result?.isError
+    const input = formatInput(toolName, toolArguments)
+    const output = hasError ? undefined : formatOutput(ctx.result)
+
+    this._tagger.tagTextIO(span, input, output)
+  }
+}
+
+class McpListToolsLLMObsPlugin extends LLMObsPlugin {
+  static id = 'llmobs_mcp_list_tools'
+  static integration = 'modelcontextprotocol-sdk'
+  static prefix = 'tracing:orchestrion:@modelcontextprotocol/sdk:Client_listTools'
+
+  getLLMObsSpanRegisterOptions () {
+    return {
+      kind: 'task',
+      name: 'MCP Client List Tools',
+    }
+  }
+
+  setLLMObsTags (ctx) {
+    const span = ctx.currentStore?.span
+    if (!span || ctx.error) return
+
+    this._tagger.tagTextIO(span, null, JSON.stringify(ctx.result))
+  }
+}
+
+module.exports = [McpToolCallLLMObsPlugin, McpListToolsLLMObsPlugin]

package/packages/dd-trace/src/llmobs/plugins/modelcontextprotocol-sdk/utils.js

@@ -0,0 +1,57 @@
+'use strict'
+
+/**
+ * Formats tool call input as a JSON string.
+ * @param {string} toolName - The name of the tool being called
+ * @param {object} toolArguments - The arguments passed to the tool
+ * @returns {string} Formatted input string
+ */
+function formatInput (toolName, toolArguments) {
+  if (!toolName && !toolArguments) return ''
+
+  if (toolArguments === undefined || toolArguments === null) {
+    return toolName || ''
+  }
+
+  try {
+    return JSON.stringify({ name: toolName, arguments: toolArguments })
+  } catch {
+    return toolName || ''
+  }
+}
+
+/**
+ * Formats MCP tool call result as a structured object matching Python's output format.
+ * MCP tool results contain a `content` array with items like:
+ * `[{ type: 'text', text: '...' }, { type: 'image', data: '...', mimeType: '...' }]`
+ * @param {object} result - The MCP CallToolResult
+ * @returns {string} JSON string of `{ content: Array<{type, text, annotations, meta}>, isError: boolean }`
+ */
+function formatOutput (result) {
+  if (!result) return ''
+
+  const content = result.content
+  const isError = result.isError || false
+
+  const processed = []
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item.type !== 'text') continue
+      const contentBlock = {
+        type: item.type,
+        text: item.text || '',
+        annotations: item.annotations || {},
+        meta: item._meta || {},
+      }
+      processed.push(contentBlock)
+    }
+  }
+
+  try {
+    return JSON.stringify({ content: processed, isError })
+  } catch {
+    return ''
+  }
+}
+
+module.exports = { formatInput, formatOutput }

package/packages/dd-trace/src/llmobs/sdk.js

@@ -2,12 +2,18 @@
 
 const { channel } = require('dc-polyfill')
 
-const { isTrue, isError } = require('../util')
+const { isError, isTrue } = require('../util')
 const tracerVersion = require('../../../../package.json').version
 const logger = require('../log')
 const { getValueFromEnvSources } = require('../config/helper')
 const Span = require('../opentracing/span')
-const { SPAN_KIND, OUTPUT_VALUE, INPUT_VALUE } = require('./constants/tags')
+const {
+  SPAN_KIND,
+  OUTPUT_VALUE,
+  INPUT_VALUE,
+  LLMOBS_TRACE_ID_BRIDGE_KEY,
+  LLMOBS_PARENT_ID_BRIDGE_KEY,
+} = require('./constants/tags')
 const {
   getFunctionArguments,
   validateKind,
@@ -427,7 +433,7 @@ class LLMObs extends NoopLLMObs {
       }
 
       // When OTel tracing is enabled, add source:otel tag to allow backend to wait for OTel span conversion
-      if (isTrue(getValueFromEnvSources('DD_TRACE_OTEL_ENABLED'))) {
+      if (this._config.DD_TRACE_OTEL_ENABLED) {
         evaluationTags.source = 'otel'
       }
 
@@ -533,6 +539,20 @@ class LLMObs extends NoopLLMObs {
         ...options,
         parent: parentStore?.span,
       })
+
+      // Bridge tags read by the dd-go LLMObs trace-indexer to correlate OTel
+      // gen_ai.* spans with SDK LLMObs spans. Written once per local trace,
+      // on the first successful SDK LLMObs span registration. The shared
+      // _trace.tags bag is serialized to the first span in every flushed
+      // chunk's meta, so partial flush is covered automatically without a
+      // separate flush-time processor. Writing only after registerLLMObsSpan
+      // succeeds avoids poisoning _trace.tags with bridge tags pointing at a
+      // span that will never produce an LLMObs event.
+      const traceTags = span?.context?.()._trace?.tags
+      if (this.enabled && traceTags && !traceTags[LLMOBS_TRACE_ID_BRIDGE_KEY]) {
+        traceTags[LLMOBS_TRACE_ID_BRIDGE_KEY] = span.context().toTraceId(true)
+        traceTags[LLMOBS_PARENT_ID_BRIDGE_KEY] = span.context().toSpanId()
+      }
     }
 
     try {

package/packages/dd-trace/src/llmobs/span_processor.js

@@ -30,6 +30,7 @@ const {
   INPUT_PROMPT,
   ROUTING_API_KEY,
   ROUTING_SITE,
+  LLMOBS_SUBMITTED_TAG_KEY,
 } = require('./constants/tags')
 const { UNSERIALIZABLE_VALUE_TEXT } = require('./constants/text')
 const telemetry = require('./telemetry')
@@ -87,7 +88,19 @@ class LLMObsSpanProcessor {
         site: mlObsTags[ROUTING_SITE],
       }
 
-      this.#writer.append(formattedEvent, routing)
+      const enqueued = this.#writer.append(formattedEvent, routing)
+
+      // Marker read by the dd-go LLMObs trace-indexer: when reparenting OTel
+      // gen_ai.* spans, the parent-chain walk stops at any span carrying this
+      // tag, preserving this span as the immediate LLMObs parent. Set only
+      // when the writer actually buffered the event — format may have dropped
+      // it (user processor returned null), thrown, or the writer may have
+      // dropped it silently when its buffer is full. Leaving this tag off in
+      // those cases avoids dd-go reparenting OTel children under a span that
+      // has no corresponding LLMObs event.
+      if (enqueued) {
+        span.context()._tags[LLMOBS_SUBMITTED_TAG_KEY] = '1'
+      }
     } catch (e) {
       // this should be a rare case
       // we protect against unserializable properties in the format function, and in

package/packages/dd-trace/src/llmobs/writers/base.js

@@ -87,19 +87,25 @@ class BaseLLMObsWriter {
     return buffer
   }
 
+  /**
+   * @returns {boolean} `true` if the event was buffered, `false` if it was dropped
+   * (e.g. the per-routing buffer was full). Callers that depend on the event
+   * actually being submitted should check this value.
+   */
   append (event, routing, byteLength) {
     const buffer = this._getBuffer(routing)
 
     if (buffer.events.length >= buffer.limit) {
       logger.warn(`${this.constructor.name} event buffer full (limit is ${buffer.limit}), dropping event`)
       telemetry.recordDroppedPayload(1, this._eventType, 'buffer_full')
-      return
+      return false
     }
 
     const eventSize = byteLength || Buffer.byteLength(JSON.stringify(event))
 
     buffer.size += eventSize
     buffer.events.push(event)
+    return true
   }
 
   flush () {