dd-trace 6.6.0 → 6.8.0

package/packages/dd-trace/src/llmobs/plugins/openai-agents/utils.js

@@ -0,0 +1,321 @@
+'use strict'
+
+const { extractContentParts, extractTextFromContentItem } = require('../openai/utils')
+const { safeJsonParse } = require('../../util')
+
+/**
+ * Flatten Responses and Chat Completions content parts without dropping
+ * provider-specific image or audio inputs.
+ *
+ * @param {Array<object>} parts
+ * @returns {{ content: string, audioParts: Array<{ mimeType: string, content: string }> }}
+ */
+function extractMessageContent (parts) {
+  const contentParts = []
+  const audioParts = []
+
+  for (const part of parts) {
+    if (!part) continue
+    const text = extractTextFromContentItem(part)
+    if (text) {
+      contentParts.push(text)
+      continue
+    }
+
+    const extracted = extractContentParts([part])
+    if (extracted.content) contentParts.push(extracted.content)
+    if (extracted.audioParts.length > 0) audioParts.push(...extracted.audioParts)
+  }
+
+  return { content: contentParts.join(''), audioParts }
+}
+
+/**
+ * Normalize OpenAI Chat Completions tool calls to the LLMObs message schema.
+ *
+ * @param {object} message
+ * @returns {Array<{ toolId?: string, name?: string, arguments: object, type?: string }>}
+ */
+function extractChatCompletionToolCalls (message) {
+  if (message.function_call) {
+    return [{
+      name: message.function_call.name,
+      arguments: safeJsonParse(message.function_call.arguments, {}),
+      type: 'function',
+    }]
+  }
+
+  const toolCalls = []
+  if (!Array.isArray(message.tool_calls)) return toolCalls
+
+  for (const toolCall of message.tool_calls) {
+    if (!toolCall) continue
+    toolCalls.push({
+      toolId: toolCall.id,
+      name: toolCall.function?.name,
+      arguments: safeJsonParse(toolCall.function?.arguments, {}),
+      type: toolCall.type,
+    })
+  }
+  return toolCalls
+}
+
+/**
+ * Normalize a Chat Completions message to the LLMObs message schema.
+ *
+ * @param {object} message
+ * @returns {object}
+ */
+function normalizeChatCompletionMessage (message) {
+  const normalized = {
+    role: message.role || 'assistant',
+    content: message.content ?? '',
+  }
+  if (message.audioParts?.length > 0) normalized.audioParts = message.audioParts
+  const toolCalls = extractChatCompletionToolCalls(message)
+  if (toolCalls.length > 0) normalized.toolCalls = toolCalls
+  if (message.tool_call_id) normalized.toolId = message.tool_call_id
+  return normalized
+}
+
+/**
+ * Extracts input messages for an LLM span. agents-openai stores only
+ * `request.input` on `spanData._input` (string or message-array), and the
+ * system instructions are echoed back on the response as `instructions`.
+ *
+ * @param {string|Array<unknown>} input - The raw `request.input` (`spanData._input`).
+ * @param {string} [instructions] - System instructions echoed on `response.instructions`.
+ * @returns {Array<{ role: string, content: string }>}
+ */
+function extractInputMessages (input, instructions) {
+  const messages = []
+
+  if (instructions) {
+    messages.push({ role: 'system', content: instructions })
+  }
+
+  if (typeof input === 'string') {
+    messages.push({ role: 'user', content: input })
+  } else if (Array.isArray(input)) {
+    for (const item of input) {
+      if (!item) continue
+      if (item.type === 'message' || item.role) {
+        const role = item.role
+        if (!role) continue
+
+        let content = ''
+        let audioParts
+        if (Array.isArray(item.content)) {
+          const extracted = extractMessageContent(item.content)
+          content = extracted.content
+          audioParts = extracted.audioParts
+        } else if (typeof item.content === 'string') {
+          content = item.content
+        }
+
+        const message = normalizeChatCompletionMessage({ ...item, content, role, audioParts })
+        if (content || message.audioParts || message.toolCalls || message.toolId) {
+          messages.push(message)
+        }
+      } else if (item.type === 'function_call') {
+        let args = item.arguments
+        if (typeof args === 'string') {
+          try {
+            args = JSON.parse(args)
+          } catch {
+            args = {}
+          }
+        }
+        messages.push({
+          role: 'assistant',
+          toolCalls: [{
+            toolId: item.call_id,
+            name: item.name,
+            arguments: args,
+            type: item.type,
+          }],
+        })
+      } else if (item.type === 'function_call_output') {
+        messages.push({
+          role: 'user',
+          toolResults: [{
+            toolId: item.call_id,
+            result: item.output,
+            name: item.name || '',
+            type: item.type,
+          }],
+        })
+      }
+    }
+  }
+
+  return messages.length > 0 ? messages : [{ role: 'user', content: '' }]
+}
+
+/**
+ * Extracts output messages from the model response.
+ *
+ * @param {{ output?: Array<unknown> }} result - The model response
+ * @returns {Array<{ role: string, content: string }>}
+ */
+function extractOutputMessages (result) {
+  const messages = []
+
+  if (result?.output) {
+    for (const item of result.output) {
+      if (!item) continue
+      if (item.type === 'message') {
+        let content = ''
+        if (Array.isArray(item.content)) {
+          const textParts = []
+          for (const contentItem of item.content) {
+            if (contentItem?.type === 'output_text' && contentItem.text) {
+              textParts.push(contentItem.text)
+            }
+          }
+          content = textParts.join('')
+        } else if (typeof item.content === 'string') {
+          content = item.content
+        }
+
+        messages.push({ role: item.role || 'assistant', content })
+      } else if (item.type === 'function_call') {
+        let args = item.arguments
+        if (typeof args === 'string') {
+          try {
+            args = JSON.parse(args)
+          } catch {
+            args = {}
+          }
+        }
+        messages.push({
+          role: 'assistant',
+          toolCalls: [{
+            toolId: item.call_id,
+            name: item.name,
+            arguments: args,
+            type: item.type,
+          }],
+        })
+      }
+    }
+  }
+
+  return messages.length > 0 ? messages : [{ content: '', role: '' }]
+}
+
+/**
+ * Extracts output messages from an OpenAI Chat Completions response.
+ *
+ * @param {Array<{ choices?: Array<{ message?: object }> }>} result - The model responses
+ * @returns {Array<object>}
+ */
+function extractGenerationOutputMessages (result) {
+  const messages = []
+
+  if (Array.isArray(result)) {
+    for (const response of result) {
+      if (!Array.isArray(response?.choices)) continue
+      for (const choice of response.choices) {
+        const message = choice?.message
+        if (!message) continue
+        messages.push(normalizeChatCompletionMessage(message))
+      }
+    }
+  }
+
+  return messages.length > 0 ? messages : [{ content: '', role: '' }]
+}
+
+/**
+ * Extracts token usage metrics from the model response. Returns `undefined`
+ * when there's nothing to tag, so callers can skip the tagger call without
+ * allocating an Object.keys array.
+ *
+ * @param {{ usage?: { inputTokens?: number, outputTokens?: number, totalTokens?: number,
+ *   outputTokensDetails?: { reasoningTokens?: number },
+ *   completion_tokens_details?: { reasoning_tokens?: number } } }} result
+ * @returns {{ inputTokens?: number, outputTokens?: number, totalTokens?: number,
+ *   reasoningOutputTokens?: number } | undefined}
+ */
+function extractMetrics (result) {
+  const usage = result?.usage
+  if (!usage) return
+
+  const inputTokens = usage.inputTokens ?? usage.input_tokens ?? usage.prompt_tokens
+  const outputTokens = usage.outputTokens ?? usage.output_tokens ?? usage.completion_tokens
+  const totalTokens = usage.totalTokens ?? usage.total_tokens
+  const reasoningTokens = usage.outputTokensDetails?.reasoningTokens ??
+    usage.output_tokens_details?.reasoning_tokens ??
+    usage.completion_tokens_details?.reasoning_tokens
+
+  if (inputTokens === undefined && outputTokens === undefined &&
+      totalTokens === undefined && !reasoningTokens) return
+
+  const metrics = {}
+  if (inputTokens !== undefined) metrics.inputTokens = inputTokens
+  if (outputTokens !== undefined) metrics.outputTokens = outputTokens
+  // Tagger maps `reasoningOutputTokens` → `reasoning_output_tokens` in the
+  // LLMObs span event. Skip when zero — emitting a zero just adds noise.
+  if (reasoningTokens) metrics.reasoningOutputTokens = reasoningTokens
+
+  if (totalTokens !== undefined) {
+    metrics.totalTokens = totalTokens
+  } else if (metrics.inputTokens !== undefined && metrics.outputTokens !== undefined) {
+    metrics.totalTokens = metrics.inputTokens + metrics.outputTokens
+  }
+
+  return metrics
+}
+
+// Fields the OpenAI Responses API echoes back from the request configuration.
+// agents-openai only stores `request.input` on the span — the user's
+// `modelSettings` aren't directly observable, so we read the response-echoed
+// values. Matches dd-trace-py's openai-agents integration (see
+// `OaiSpanAdapter.llmobs_metadata`); both ship without filtering OpenAI's
+// default values.
+const RESPONSE_METADATA_FIELDS = [
+  'temperature',
+  'max_output_tokens',
+  'top_p',
+  'tools',
+  'tool_choice',
+  'truncation',
+]
+
+/**
+ * Extracts metadata from the model response. Mirrors Python's
+ * `OaiSpanAdapter.llmobs_metadata` — emits all response-echoed configuration
+ * fields plus `text` when present. Returns `undefined` when nothing was
+ * captured, so callers can skip the tagger call without allocating.
+ *
+ * @param {object | undefined} response
+ * @returns {object | undefined}
+ */
+function extractMetadata (response) {
+  if (!response) return
+
+  let metadata
+  for (const field of RESPONSE_METADATA_FIELDS) {
+    const value = response[field]
+    if (value !== undefined && value !== null) {
+      metadata ??= {}
+      metadata[field] = value
+    }
+  }
+
+  if (response.text) {
+    metadata ??= {}
+    metadata.text = response.text
+  }
+
+  return metadata
+}
+
+module.exports = {
+  extractInputMessages,
+  extractOutputMessages,
+  extractGenerationOutputMessages,
+  extractMetrics,
+  extractMetadata,
+}

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

@@ -11,6 +11,7 @@ const {
   SPAN_KIND,
   OUTPUT_VALUE,
   INPUT_VALUE,
+  TRACE_ID,
 } = require('./constants/tags')
 const {
   getFunctionArguments,
@@ -34,12 +35,6 @@ class LLMObs extends NoopLLMObs {
    */
   #hasUserSpanProcessor = false
 
-  /**
-   * Lazily-created experiments facade (see ./experiments).
-   * @type {import('./experiments').Experiments | undefined}
-   */
-  #experiments
-
   /**
    * @param {import('../tracer')} tracer - Tracer instance
    * @param {import('./index')} llmobsModule - LLMObs module instance
@@ -65,8 +60,7 @@ class LLMObs extends NoopLLMObs {
    * a clear message on use.
    */
   get experiments () {
-    this.#experiments ??= createExperiments(this._config)
-    return this.#experiments
+    return createExperiments(this._config, this)
   }
 
   enable (options = {}) {
@@ -317,14 +311,14 @@ class LLMObs extends NoopLLMObs {
       }
       throw e
     } finally {
-      if (autoinstrumented === false) {
+      if (!autoinstrumented) {
         telemetry.recordLLMObsAnnotate(span, err)
       }
     }
   }
 
   exportSpan (span) {
-    span = span || this._active()
+    span ||= this._active()
     let err = ''
     try {
       if (!span) {
@@ -345,7 +339,7 @@ class LLMObs extends NoopLLMObs {
     }
     try {
       return {
-        traceId: span.context().toTraceId(true),
+        traceId: LLMObsTagger.tagMap.get(span)[TRACE_ID],
         spanId: span.context().toSpanId(),
       }
     } catch {
@@ -425,7 +419,7 @@ class LLMObs extends NoopLLMObs {
         err = 'invalid_metric_value'
         throw new Error('value must be a boolean for a boolean metric')
       }
-      if (metricType === 'json' && !(typeof value === 'object' && value != null && !Array.isArray(value))) {
+      if (metricType === 'json' && (typeof value !== 'object' || value == null || Array.isArray(value))) {
         err = 'invalid_metric_value'
         throw new Error('value must be a JSON object for a json metric')
       }

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

@@ -35,6 +35,7 @@ const {
   LLMOBS_SUBMITTED_TAG_KEY,
   SAMPLE_RATE,
   SAMPLING_DECISION,
+  TRACE_ID,
 } = require('./constants/tags')
 const { UNSERIALIZABLE_VALUE_TEXT } = require('./constants/text')
 const telemetry = require('./telemetry')
@@ -236,8 +237,19 @@ class LLMObsSpanProcessor {
       meta.input.prompt = prompt
     }
 
+    const apmTraceId = span.context().toTraceId(true)
+    const llmobsTraceId = mlObsTags[TRACE_ID] ?? apmTraceId
+    const dd = {
+      span_id: span.context().toSpanId(),
+      trace_id: apmTraceId,
+      sample_rate: mlObsTags[SAMPLE_RATE],
+      sampling_decision: mlObsTags[SAMPLING_DECISION],
+      apm_trace_id: apmTraceId,
+    }
+    if (tags.experiment_id) dd.scope = 'experiments'
+
     const llmObsSpanEvent = {
-      trace_id: span.context().toTraceId(true),
+      trace_id: llmobsTraceId,
       span_id: span.context().toSpanId(),
       parent_id: parentId,
       name,
@@ -247,12 +259,7 @@ class LLMObsSpanProcessor {
       status: error ? 'error' : 'ok',
       meta,
       metrics,
-      _dd: {
-        span_id: span.context().toSpanId(),
-        trace_id: span.context().toTraceId(true),
-        sample_rate: mlObsTags[SAMPLE_RATE],
-        sampling_decision: mlObsTags[SAMPLING_DECISION],
-      },
+      _dd: dd,
     }
 
     if (sessionId) llmObsSpanEvent.session_id = sessionId

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

@@ -51,9 +51,18 @@ const {
   SAMPLING_DECISION_DROPPED,
   PROPAGATED_SAMPLE_RATE_KEY,
   PROPAGATED_SAMPLING_DECISION_KEY,
+  TRACE_ID,
+  PROPAGATED_TRACE_ID_KEY,
 } = require('./constants/tags')
 const { storage } = require('./storage')
-const { findGenAIAncestorSpanId, validateCostTags, writeBridgeTags, validateToolDefinitions } = require('./util')
+const {
+  findGenAIAncestorSpanId,
+  validateCostTags,
+  writeBridgeTags,
+  validateToolDefinitions,
+  generateLlmObsTraceId,
+  normalizeLlmObsTraceId,
+} = require('./util')
 
 // global registry of LLMObs spans
 // maps LLMObs spans to their annotations
@@ -126,12 +135,20 @@ class LLMObsTagger {
 
     this._register(span)
 
+    const traceTags = span.context()._trace.tags
+
+    const llmobsTraceId =
+      registry.get(parent)?.[TRACE_ID] ??
+      normalizeLlmObsTraceId(traceTags[PROPAGATED_TRACE_ID_KEY]) ??
+      generateLlmObsTraceId(span._startTime)
+    this._setTag(span, TRACE_ID, llmobsTraceId)
+
     // When the registering span sits below an OTel `gen_ai.*` ancestor, use
     // that ancestor as the parent_id fallback and suppress the bridge
     // parent_id tag so the indexer doesn't invert the trace.
     const genAIAncestorSpanId = findGenAIAncestorSpanId(span)
 
-    writeBridgeTags(span, { includeParentId: genAIAncestorSpanId === null })
+    writeBridgeTags(span, { includeParentId: genAIAncestorSpanId === null, llmobsTraceId })
 
     this._setTag(span, ML_APP, spanMlApp)
 
@@ -141,9 +158,7 @@ class LLMObsTagger {
     if (modelName) this.tagModelName(span, modelName)
     if (modelProvider) this._setTag(span, MODEL_PROVIDER, modelProvider)
 
-    const traceTags = span.context()._trace.tags
-    sessionId = sessionId ||
-      registry.get(parent)?.[SESSION_ID] ||
+    sessionId ||= registry.get(parent)?.[SESSION_ID] ||
       traceTags[SESSION_ID_TRACE_DEFAULT_KEY] ||
       traceTags[PROPAGATED_SESSION_ID_KEY]
     if (sessionId) this._setTag(span, SESSION_ID, sessionId)
@@ -500,6 +515,10 @@ class LLMObsTagger {
     this._setTag(span, MODEL_NAME, modelName)
   }
 
+  setName (span, name) {
+    this._setTag(span, NAME, name)
+  }
+
   #tagText (span, data, key) {
     if (data) {
       if (typeof data === 'string') {

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

@@ -1,5 +1,6 @@
 'use strict'
 
+const id = require('../id')
 const log = require('../log')
 const {
   LLMOBS_PARENT_ID_BRIDGE_KEY,
@@ -7,6 +8,10 @@ const {
   SPAN_KINDS,
 } = require('./constants/tags')
 
+const DECIMAL_TRACE_ID_REGEX = /^\d+$/
+const HEX_TRACE_ID_REGEX = /^[0-9a-f]{32}$/i
+const MAX_UINT_64 = (1n << 64n) - 1n
+
 // LLM I/O is overwhelmingly ASCII (English prompts and code). Walk once
 // looking for the first non-ASCII char; if there is none, hand the input
 // straight back. Otherwise pick up the slow path from the byte that needed
@@ -312,12 +317,12 @@ function safeJsonParse (value, fallback) {
 // LLMObs root and hoists the gen_ai ancestors under it, inverting the trace.
 /**
  * @param {import('../opentracing/span')} span
- * @param {{ includeParentId?: boolean }} [opts]
+ * @param {{ includeParentId?: boolean, llmobsTraceId?: string }} [opts]
  */
-function writeBridgeTags (span, { includeParentId = true } = {}) {
+function writeBridgeTags (span, { includeParentId = true, llmobsTraceId } = {}) {
   const traceTags = span?.context?.()._trace?.tags
   if (!traceTags || traceTags[LLMOBS_TRACE_ID_BRIDGE_KEY]) return
-  traceTags[LLMOBS_TRACE_ID_BRIDGE_KEY] = span.context().toTraceId(true)
+  traceTags[LLMOBS_TRACE_ID_BRIDGE_KEY] = llmobsTraceId ?? span.context().toTraceId(true)
   if (includeParentId) {
     traceTags[LLMOBS_PARENT_ID_BRIDGE_KEY] = span.context().toSpanId()
   }
@@ -362,6 +367,51 @@ function findGenAIAncestorSpanId (span) {
   return null
 }
 
+/**
+ * Generate a 128-bit LLMObs trace ID with the span start time encoded in its high bits.
+ * @param {number} startTime
+ * @returns {string}
+ */
+function generateLlmObsTraceId (startTime) {
+  const identifier = id()
+  const traceIdHigh = Math.floor(startTime / 1000)
+    .toString(16)
+    .padStart(8, '0')
+    .padEnd(16, '0')
+
+  return identifier.toTraceIdHex(traceIdHigh).padStart(32, '0')
+}
+
+/**
+ * Convert an internally stored hexadecimal LLMObs trace ID to its distributed wire representation.
+ * @param {string | undefined} traceId
+ * @returns {string | undefined}
+ */
+function llmObsTraceIdToWire (traceId) {
+  if (!traceId) return
+  if (!HEX_TRACE_ID_REGEX.test(traceId)) return traceId
+
+  return BigInt(`0x${traceId}`).toString(10)
+}
+
+/**
+ * Normalize a distributed LLMObs trace ID to the representation expected by LLMObs span events.
+ * @param {string | undefined} traceId
+ * @returns {string | undefined}
+ */
+function normalizeLlmObsTraceId (traceId) {
+  if (!traceId) return
+
+  if (HEX_TRACE_ID_REGEX.test(traceId) && (traceId[0] === '0' || !DECIMAL_TRACE_ID_REGEX.test(traceId))) {
+    return traceId
+  }
+
+  if (!DECIMAL_TRACE_ID_REGEX.test(traceId)) return traceId
+
+  const identifier = BigInt(traceId)
+  return identifier > MAX_UINT_64 ? identifier.toString(16).padStart(32, '0') : traceId
+}
+
 // Maps an audio `format` (e.g. "wav", "mp3") to a MIME type. Defaults to `audio/wav` when the
 // format is missing. Provider-specific overrides (e.g. OpenAI's mp3 -> audio/mpeg) are passed in
 // via `mimeTypeLookup` so this stays provider-agnostic. A non-string `format` is treated as missing
@@ -396,6 +446,9 @@ module.exports = {
   audioMimeTypeFromFormat,
   encodeUnicode,
   findGenAIAncestorSpanId,
+  generateLlmObsTraceId,
+  llmObsTraceIdToWire,
+  normalizeLlmObsTraceId,
   formatAudioPart,
   validateCostTags,
   validateKind,

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

@@ -49,12 +49,18 @@ class LLMObsSpanWriter extends BaseWriter {
   }
 
   makePayload (events) {
-    return events.map(event => ({
-      '_dd.stage': 'raw',
-      '_dd.tracer_version': tracerVersion,
-      event_type: this._eventType,
-      spans: [event],
-    }))
+    return events.map(event => {
+      const eventData = {
+        '_dd.stage': 'raw',
+        '_dd.tracer_version': tracerVersion,
+        event_type: this._eventType,
+        spans: [event],
+      }
+      if (event?._dd?.scope === 'experiments') {
+        eventData['_dd.scope'] = 'experiments'
+      }
+      return eventData
+    })
   }
 
   _truncateSpanEvent (event) {

package/packages/dd-trace/src/noop/proxy.js

@@ -55,7 +55,7 @@ class NoopProxy {
 
     if (typeof fn !== 'function') return
 
-    options = options || {}
+    options ||= {}
 
     return this._tracer.trace(name, options, fn)
   }
@@ -68,7 +68,7 @@ class NoopProxy {
 
     if (typeof fn !== 'function') return fn
 
-    options = options || {}
+    options ||= {}
 
     return this._tracer.wrap(name, options, fn)
   }

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

@@ -20,7 +20,7 @@ const RETRY_JITTER = 0.2
  * @property {URL} endpoint
  * @property {number} pollIntervalMs
  * @property {number} requestTimeoutMs
- * @property {string} apiKey
+ * @property {string | undefined} apiKey
  */
 
 /**
@@ -138,7 +138,7 @@ class AgentlessConfigurationSource {
   #request (signal) {
     const headers = getClientLibraryHeaders()
     headers['Accept-Encoding'] = 'gzip'
-    headers['DD-API-KEY'] = this.#config.apiKey
+    if (this.#config.apiKey) headers['DD-API-KEY'] = this.#config.apiKey
     if (this.#etag) headers['If-None-Match'] = this.#etag
 
     /**
@@ -228,10 +228,7 @@ class AgentlessConfigurationSource {
     this.#failureWarnings.add(category)
 
     if (statusCode === 401 || statusCode === 403) {
-      log.warn(
-        'Feature Flagging agentless endpoint returned HTTP %d; verify DD_API_KEY is configured and valid',
-        statusCode
-      )
+      log.warn('Feature Flagging agentless endpoint returned HTTP %d; verify endpoint authentication', statusCode)
     } else if (statusCode) {
       log.warn('Feature Flagging agentless endpoint returned HTTP %d after %d attempts', statusCode, attempts)
     } else if (attempts > 1) {