dd-trace 5.98.0 → 5.99.0

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,7 +2,7 @@
 
 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')
@@ -427,7 +427,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'
       }
 

package/packages/dd-trace/src/openfeature/eval-metrics-hook.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const log = require('../log')
+
+const METER_NAME = 'dd-trace-js/openfeature'
+const COUNTER_NAME = 'feature_flag.evaluations'
+const COUNTER_DESCRIPTION = 'Number of feature flag evaluations'
+const COUNTER_UNIT = '{evaluation}'
+
+/**
+ * OpenFeature hook that tracks feature flag evaluation metrics using an
+ * OpenTelemetry counter.
+ *
+ * Implements the OpenFeature `finally` hook interface so it can be pushed
+ * directly onto a provider's `hooks` array. We use the `finally` stage
+ * (not diagnostic channels inside the provider's `resolve*` methods) because
+ * the OpenFeature SDK short-circuits before calling the provider when it is in
+ * NOT_READY state; the `finally` hook still fires, ensuring all evaluations are
+ * captured. It also catches type-mismatch errors detected by the SDK client
+ * after the provider returns.
+ *
+ * The counter is created lazily on the first successful `finally()` call rather
+ * than in the constructor. This is necessary because `FlaggingProvider` is
+ * constructed eagerly by `proxy.js#updateTracing()`, which runs *before*
+ * `initializeOpenTelemetryMetrics()` sets the global OTel meter provider.
+ * Calling `getMeter()` in the constructor would return the noop meter and
+ * produce a noop counter that silently discards all measurements. By deferring
+ * to `finally()` time we give the meter provider a chance to be set up first.
+ *
+ * If counter creation fails (e.g. the OTel API is not yet available), the call
+ * is silently skipped and retried on the next `finally()` invocation.
+ *
+ * When `config.otelMetricsEnabled` is false, `finally()` is always a no-op.
+ */
+class EvalMetricsHook {
+  #enabled = false
+  #counter = null
+
+  /**
+   * @param {import('../config')} config - Tracer configuration object
+   */
+  constructor (config) {
+    this.#enabled = config.otelMetricsEnabled === true
+  }
+
+  /**
+   * Returns the OTel counter, creating it on first successful call.
+   * Returns `null` if counter creation fails; will retry on next call.
+   *
+   * @returns {import('@opentelemetry/api').Counter | null}
+   */
+  #getCounter () {
+    if (this.#counter) return this.#counter
+
+    try {
+      const { metrics } = require('@opentelemetry/api')
+      const meter = metrics.getMeter(METER_NAME)
+      this.#counter = meter.createCounter(COUNTER_NAME, {
+        description: COUNTER_DESCRIPTION,
+        unit: COUNTER_UNIT,
+      })
+    } catch (e) {
+      log.warn('EvalMetricsHook: failed to create counter: %s', e.message)
+    }
+
+    return this.#counter
+  }
+
+  /**
+   * Called by the OpenFeature SDK after every flag evaluation (success or error).
+   *
+   * @param {{ flagKey: string }} hookContext - Hook context containing the flag key
+   * @param {{ variant?: string, reason?: string, errorCode?: string, flagMetadata?: object }} evaluationDetails
+   *   - Full evaluation details
+   * @returns {void}
+   */
+  finally (hookContext, evaluationDetails) {
+    if (!this.#enabled) return
+
+    const counter = this.#getCounter()
+    if (!counter) return
+
+    const attributes = {
+      'feature_flag.key': hookContext?.flagKey ?? '',
+      'feature_flag.result.variant': evaluationDetails?.variant ?? '',
+      'feature_flag.result.reason': evaluationDetails?.reason?.toLowerCase() ?? 'unknown',
+    }
+
+    const errorCode = evaluationDetails?.errorCode
+    if (errorCode) {
+      attributes['error.type'] = errorCode.toLowerCase()
+    }
+
+    const allocationKey = evaluationDetails?.flagMetadata?.allocationKey
+    if (allocationKey) {
+      attributes['feature_flag.result.allocation_key'] = allocationKey
+    }
+
+    counter.add(1, attributes)
+  }
+}
+
+module.exports = EvalMetricsHook

package/packages/dd-trace/src/openfeature/flagging_provider.js

@@ -4,6 +4,7 @@ const { DatadogNodeServerProvider } = require('@datadog/openfeature-node-server'
 const { channel } = require('dc-polyfill')
 const log = require('../log')
 const { EXPOSURE_CHANNEL } = require('./constants/constants')
+const EvalMetricsHook = require('./eval-metrics-hook')
 
 /**
  * OpenFeature provider that integrates with Datadog's feature flagging system.
@@ -24,6 +25,8 @@ class FlaggingProvider extends DatadogNodeServerProvider {
     this._tracer = tracer
     this._config = config
 
+    this.hooks.push(new EvalMetricsHook(config))
+
     log.debug('%s created with timeout: %dms', this.constructor.name,
       config.experimental.flaggingProvider.initializationTimeoutMs)
   }

package/packages/dd-trace/src/opentelemetry/logs/index.js

@@ -61,7 +61,7 @@ function initializeOpenTelemetryLogs (config) {
   // Create OTLP exporter using resolved config values
   const exporter = new OtlpHttpLogExporter(
     config.otelLogsUrl,
-    config.otelLogsHeaders,
+    config.OTEL_EXPORTER_OTLP_LOGS_HEADERS,
     config.otelLogsTimeout,
     config.otelLogsProtocol,
     resourceAttributes

package/packages/dd-trace/src/opentelemetry/logs/otlp_http_log_exporter.js

@@ -22,13 +22,14 @@ class OtlpHttpLogExporter extends OtlpHttpExporterBase {
    * Creates a new OtlpHttpLogExporter instance.
    *
    * @param {string} url - OTLP endpoint URL
-   * @param {string} headers - Additional HTTP headers as comma-separated key=value string
+   * @param {Record<string, string>|undefined} headers - Additional HTTP headers parsed from the
+   *   corresponding `OTEL_EXPORTER_OTLP_*_HEADERS` env by the MAP parser.
    * @param {number} timeout - Request timeout in milliseconds
    * @param {string} protocol - OTLP protocol (http/protobuf or http/json)
    * @param {Resource} resource - Resource attributes
    */
   constructor (url, headers, timeout, protocol, resource) {
-    super(url, headers, timeout, protocol, '/v1/logs', 'logs')
+    super(url, headers, timeout, protocol, 'logs')
     this.transformer = new OtlpTransformer(resource, protocol)
   }
 

package/packages/dd-trace/src/opentelemetry/metrics/index.js

@@ -58,7 +58,7 @@ function initializeOpenTelemetryMetrics (config) {
 
   const exporter = new OtlpHttpMetricExporter(
     config.otelMetricsUrl,
-    config.otelMetricsHeaders,
+    config.OTEL_EXPORTER_OTLP_METRICS_HEADERS,
     config.otelMetricsTimeout,
     config.otelMetricsProtocol,
     resourceAttributes