dd-trace 5.100.0 → 5.101.0

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

@@ -237,15 +237,23 @@ function formatContentObject (content) {
     }
   }
 
-  // Check for function calls
-  const functionCalls = parts.filter(part => part.functionCall)
-  if (functionCalls.length > 0) {
+  // Two filter passes over `parts` collapse to a single walk. Most parts are
+  // text-only so neither bucket is allocated unless a matching part appears.
+  let functionCalls
+  let functionResponses
+  for (const part of parts) {
+    if (part.functionCall) {
+      (functionCalls ??= []).push(part)
+    } else if (part.functionResponse) {
+      (functionResponses ??= []).push(part)
+    }
+  }
+
+  if (functionCalls) {
     return formatFunctionCallMessage(parts, functionCalls, role)
   }
 
-  // Check for function responses
-  const functionResponses = parts.filter(part => part.functionResponse)
-  if (functionResponses.length > 0) {
+  if (functionResponses) {
     return formatFunctionResponseMessage(functionResponses, role)
   }
 
@@ -326,15 +334,26 @@ function formatNonStreamingCandidate (candidate) {
 
   const { parts } = content
 
-  // Check for function calls
-  const functionCalls = parts.filter(part => part.functionCall)
-  if (functionCalls.length > 0) {
+  // One walk replaces three (`filter` + two `find`); priority order is
+  // functionCall > executableCode > codeExecutionResult, same as before.
+  let functionCalls
+  let executableCode
+  let codeExecutionResult
+  for (const part of parts) {
+    if (part.functionCall) {
+      (functionCalls ??= []).push(part)
+    } else if (!executableCode && part.executableCode) {
+      executableCode = part
+    } else if (!codeExecutionResult && part.codeExecutionResult) {
+      codeExecutionResult = part
+    }
+  }
+
+  if (functionCalls) {
     messages.push(formatFunctionCallMessage(parts, functionCalls, ROLES.ASSISTANT))
     return messages
   }
 
-  // Check for executable code
-  const executableCode = parts.find(part => part.executableCode)
   if (executableCode) {
     messages.push({
       role: ROLES.ASSISTANT,
@@ -346,8 +365,6 @@ function formatNonStreamingCandidate (candidate) {
     return messages
   }
 
-  // Check for code execution result
-  const codeExecutionResult = parts.find(part => part.codeExecutionResult)
   if (codeExecutionResult) {
     messages.push({
       role: ROLES.ASSISTANT,

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

@@ -7,6 +7,7 @@ const {
   INSTRUMENTATION_METHOD_AUTO,
   UNKNOWN_MODEL_PROVIDER,
 } = require('../../constants/tags')
+const { safeJsonParse } = require('../../util')
 const {
   extractChatTemplateFromInstructions,
   normalizePromptVariables,
@@ -183,13 +184,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
   _tagChatCompletion (span, inputs, response, error) {
     const { messages, model, ...parameters } = inputs
 
-    const metadata = Object.entries(parameters).reduce((obj, [key, value]) => {
-      if (!['tools', 'functions'].includes(key)) {
-        obj[key] = value
+    const metadata = {}
+    for (const key of Object.keys(parameters)) {
+      if (key !== 'tools' && key !== 'functions') {
+        metadata[key] = parameters[key]
       }
-
-      return obj
-    }, {})
+    }
 
     this._tagger.tagMetadata(span, metadata)
 
@@ -213,14 +213,14 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
       if (message.function_call) {
         const functionCallInfo = {
           name: message.function_call.name,
-          arguments: JSON.parse(message.function_call.arguments),
+          arguments: safeJsonParse(message.function_call.arguments),
         }
         outputMessages.push({ content, role, toolCalls: [functionCallInfo] })
       } else if (message.tool_calls) {
         const toolCallsInfo = []
         for (const toolCall of message.tool_calls) {
           const toolCallInfo = {
-            arguments: JSON.parse(toolCall.function.arguments),
+            arguments: safeJsonParse(toolCall.function.arguments),
             name: toolCall.function.name,
             toolId: toolCall.id,
             type: toolCall.type,
@@ -277,22 +277,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
             inputMessages.push({ role, content })
           }
         } else if (item.type === 'function_call') {
-          // Function call: convert to message with tool_calls
-          // Parse arguments if it's a JSON string
-          let parsedArgs = item.arguments
-          if (typeof parsedArgs === 'string') {
-            try {
-              parsedArgs = JSON.parse(parsedArgs)
-            } catch {
-              parsedArgs = {}
-            }
-          }
           inputMessages.push({
             role: 'assistant',
             toolCalls: [{
               toolId: item.call_id,
               name: item.name,
-              arguments: parsedArgs,
+              arguments: safeJsonParse(item.arguments, {}),
               type: item.type,
             }],
           })
@@ -317,12 +307,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
       inputMessages.push({ role: 'user', content: input })
     }
 
-    const inputMetadata = Object.entries(parameters).reduce((obj, [key, value]) => {
+    const inputMetadata = {}
+    for (const key of Object.keys(parameters)) {
       if (allowedParamKeys.has(key)) {
-        obj[key] = value
+        inputMetadata[key] = parameters[key]
       }
-      return obj
-    }, {})
+    }
 
     this._tagger.tagMetadata(span, inputMetadata)
 
@@ -354,21 +344,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
           })
         } else if (item.type === 'function_call') {
           // Handle function_call type (responses API tool calls)
-          let args = item.arguments
-          // Parse arguments if it's a JSON string
-          if (typeof args === 'string') {
-            try {
-              args = JSON.parse(args)
-            } catch {
-              args = {}
-            }
-          }
           outputMessages.push({
             role: 'assistant',
             toolCalls: [{
               toolId: item.call_id,
               name: item.name,
-              arguments: args,
+              arguments: safeJsonParse(item.arguments, {}),
               type: item.type,
             }],
           })
@@ -390,23 +371,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
 
           // Extract tool calls if present in message.tool_calls
           if (Array.isArray(item.tool_calls)) {
-            outputMsg.toolCalls = item.tool_calls.map(tc => {
-              let args = tc.function?.arguments || tc.arguments
-              // Parse arguments if it's a JSON string
-              if (typeof args === 'string') {
-                try {
-                  args = JSON.parse(args)
-                } catch {
-                  args = {}
-                }
-              }
-              return {
-                toolId: tc.id,
-                name: tc.function?.name || tc.name,
-                arguments: args,
-                type: tc.type || 'function_call',
-              }
-            })
+            outputMsg.toolCalls = item.tool_calls.map(tc => ({
+              toolId: tc.id,
+              name: tc.function?.name || tc.name,
+              arguments: safeJsonParse(tc.function?.arguments || tc.arguments, {}),
+              type: tc.type || 'function_call',
+            }))
           }
 
           outputMessages.push(outputMsg)

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

@@ -251,7 +251,7 @@ class LLMObs extends NoopLLMObs {
         throw new Error('LLMObs span must have a span kind specified')
       }
 
-      const { inputData, outputData, metadata, metrics, tags, prompt } = options
+      const { inputData, outputData, metadata, metrics, tags, prompt, costTags } = options
 
       if (inputData || outputData) {
         if (spanKind === 'llm') {
@@ -271,9 +271,13 @@ class LLMObs extends NoopLLMObs {
       if (metrics) {
         this._tagger.tagMetrics(span, metrics)
       }
+      // Apply tags before costTags so costTags can reference tags from the same annotation.
       if (tags) {
         this._tagger.tagSpanTags(span, tags)
       }
+      if (costTags != null) {
+        this._tagger.tagCostTags(span, costTags, 'annotate')
+      }
       if (prompt) {
         this._tagger.tagPrompt(span, prompt)
       }

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

@@ -14,6 +14,8 @@ const {
   MODEL_NAME,
   MODEL_PROVIDER,
   METADATA,
+  COST_TAGS,
+  TOOL_DEFINITIONS,
   INPUT_MESSAGES,
   INPUT_VALUE,
   INTEGRATION,
@@ -130,8 +132,20 @@ class LLMObsSpanProcessor {
       meta.model_provider = (mlObsTags[MODEL_PROVIDER] || 'custom').toLowerCase()
     }
 
-    if (mlObsTags[METADATA]) {
-      this.#addObject(mlObsTags[METADATA], meta.metadata = {})
+    if (mlObsTags[METADATA] || mlObsTags[COST_TAGS]) {
+      const metadata = {}
+      if (mlObsTags[METADATA]) this.#addObject(mlObsTags[METADATA], metadata)
+      // Only seed `metadata._dd` when there's something to put in it (currently cost_tags). Mirrors
+      // dd-trace-py and the cross-language wire format enforced by system-tests — metadata-only
+      // spans must not carry an empty `_dd: {}` block.
+      if (mlObsTags[COST_TAGS]) {
+        this.#getDdMetadata(metadata).cost_tags = mlObsTags[COST_TAGS]
+      }
+      meta.metadata = metadata
+    }
+
+    if (mlObsTags[TOOL_DEFINITIONS]) {
+      this.#addObject(mlObsTags[TOOL_DEFINITIONS], meta.tool_definitions = [])
     }
 
     if (spanKind === 'llm' && mlObsTags[INPUT_MESSAGES]) {
@@ -259,6 +273,18 @@ class LLMObsSpanProcessor {
     add(obj, carrier)
   }
 
+  /**
+   * Returns `metadata._dd`, normalizing it to a fresh object if missing or invalid.
+   * @param {Record<string, unknown>} metadata
+   * @returns {Record<string, unknown>}
+   */
+  #getDdMetadata (metadata) {
+    if (!metadata._dd || typeof metadata._dd !== 'object' || Array.isArray(metadata._dd)) {
+      metadata._dd = {}
+    }
+    return metadata._dd
+  }
+
   #getTags (span, mlApp, sessionId, error) {
     let tags = {
       ...this.#config.parsedDdTags,

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

@@ -12,7 +12,9 @@ const {
   INPUT_DOCUMENTS,
   OUTPUT_VALUE,
   METADATA,
+  COST_TAGS,
   METRICS,
+  TOOL_DEFINITIONS,
   PARENT_ID_KEY,
   INPUT_MESSAGES,
   OUTPUT_MESSAGES,
@@ -41,6 +43,7 @@ const {
   INSTRUMENTATION_METHOD_ANNOTATED,
 } = require('./constants/tags')
 const { storage } = require('./storage')
+const { validateCostTags } = require('./util')
 
 // global registry of LLMObs spans
 // maps LLMObs spans to their annotations
@@ -120,6 +123,11 @@ class LLMObsTagger {
     const tags = annotationContext?.tags
     if (tags) this.tagSpanTags(span, tags)
 
+    // apply after tags so only keys present at span start are accepted.
+    if (annotationContext?.costTags != null) {
+      this.tagCostTags(span, annotationContext.costTags, 'annotation_context')
+    }
+
     // apply annotation context name
     const annotationContextName = annotationContext?.name
     if (annotationContextName) this._setTag(span, NAME, annotationContextName)
@@ -159,6 +167,14 @@ class LLMObsTagger {
     this.#tagText(span, outputData, OUTPUT_VALUE)
   }
 
+  tagToolDefinitions (span, toolDefinitions) {
+    if (Array.isArray(toolDefinitions) && toolDefinitions.length > 0) {
+      this._setTag(span, TOOL_DEFINITIONS, toolDefinitions)
+    } else {
+      this.#handleFailure('Tool definitions must be a non-empty array.', 'invalid_tool_definitions')
+    }
+  }
+
   tagMetadata (span, metadata) {
     const existingMetadata = registry.get(span)?.[METADATA]
     if (existingMetadata) {
@@ -225,6 +241,32 @@ class LLMObsTagger {
     }
   }
 
+  /**
+   * Validates and tags cost tag keys on an LLMObs span. Cost tag references are validated against
+   * the span's already-applied tags, which are read from the registry.
+   * @param {import('../opentracing/span')} span
+   * @param {unknown} costTags Raw user-provided cost tags; validated here.
+   * @param {'annotate' | 'annotation_context'} source
+   */
+  tagCostTags (span, costTags, source) {
+    const spanTags = registry.get(span)?.[TAGS] || {}
+    const validatedCostTags = validateCostTags(span, costTags, source, spanTags)
+    if (!validatedCostTags.length) return
+
+    // Might consider switching to a `Set` if per-span cost tag cardinality grows large enough that
+    // this `.includes`/`.push` merge becomes a hot spot
+    const currentCostTags = registry.get(span)?.[COST_TAGS]
+    if (currentCostTags) {
+      for (const costTag of validatedCostTags) {
+        if (!currentCostTags.includes(costTag)) {
+          currentCostTags.push(costTag)
+        }
+      }
+    } else {
+      this._setTag(span, COST_TAGS, validatedCostTags)
+    }
+  }
+
   /**
    * Tags a prompt on an LLMObs span.
    * @param {import('../opentracing/span')} span

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

@@ -6,6 +6,7 @@ const telemetryMetrics = require('../telemetry/metrics')
 const {
   SPAN_KIND,
   MODEL_PROVIDER,
+  ML_APP,
   PARENT_ID_KEY,
   SESSION_ID,
   ROOT_PARENT_ID,
@@ -123,6 +124,32 @@ function recordLLMObsAnnotate (span, err, value = 1) {
   llmobsMetrics.count('annotations', tags).inc(value)
 }
 
+function recordCostTagsAnnotated (span, source, value = 1) {
+  const mlObsTags = LLMObsTagger.tagMap.get(span) || {}
+  const tags = {
+    span_kind: mlObsTags[SPAN_KIND] || 'N/A',
+    source,
+    ml_app: mlObsTags[ML_APP] || 'N/A',
+    model_provider: mlObsTags[MODEL_PROVIDER] || 'N/A',
+  }
+
+  llmobsMetrics.count('cost_tags.annotated', tags).inc(value)
+}
+
+function recordCostTagsSubmitted (span, count, source, state, reason = 'none') {
+  const mlObsTags = LLMObsTagger.tagMap.get(span) || {}
+  const tags = {
+    span_kind: mlObsTags[SPAN_KIND] || 'N/A',
+    source,
+    ml_app: mlObsTags[ML_APP] || 'N/A',
+    model_provider: mlObsTags[MODEL_PROVIDER] || 'N/A',
+    state,
+    reason,
+  }
+
+  llmobsMetrics.count('cost_tags.submitted', tags).inc(count)
+}
+
 function recordUserFlush (err, value = 1) {
   const tags = { error: Number(!!err) }
   if (err) tags.error_type = err
@@ -167,6 +194,8 @@ module.exports = {
   recordLLMObsSpanSize,
   recordDroppedPayload,
   recordLLMObsAnnotate,
+  recordCostTagsAnnotated,
+  recordCostTagsSubmitted,
   recordUserFlush,
   recordExportSpan,
   recordSubmitEvaluation,

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

@@ -1,14 +1,25 @@
 'use strict'
 
+const log = require('../log')
 const { SPAN_KINDS } = require('./constants/tags')
 
+// 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
+// escaping. ~5x faster on typical prompt strings than the per-char `+=`
+// loop the function used to do unconditionally.
 function encodeUnicode (str = '') {
-  let result = ''
-  for (let i = 0; i < str.length; i++) {
-    const code = str.charCodeAt(i)
-    result += code > 127 ? String.raw`\u${code.toString(16).padStart(4, '0')}` : str[i]
+  for (let index = 0; index < str.length; index++) {
+    if (str.charCodeAt(index) > 127) {
+      let result = str.slice(0, index)
+      for (; index < str.length; index++) {
+        const code = str.charCodeAt(index)
+        result += code > 127 ? String.raw`\u${code.toString(16).padStart(4, '0')}` : str[index]
+      }
+      return result
+    }
   }
-  return result
+  return str
 }
 
 function validateKind (kind) {
@@ -22,6 +33,57 @@ function validateKind (kind) {
   return kind
 }
 
+/**
+ * Validates cost tag keys and records telemetry for the annotation source.
+ * @param {import('../opentracing/span')} span
+ * @param {unknown} costTags
+ * @param {string} source
+ * @param {Record<string, unknown>} spanTags
+ * @returns {string[]}
+ */
+function validateCostTags (span, costTags, source, spanTags) {
+  // Lazy-required to avoid the `index.js -> telemetry -> tagger -> util` module cycle.
+  const telemetry = require('./telemetry')
+
+  telemetry.recordCostTagsAnnotated(span, source)
+
+  if (!Array.isArray(costTags)) {
+    log.warn('costTags must be an array of strings. Ignoring value.')
+    telemetry.recordCostTagsSubmitted(span, 1, source, 'error', 'non_list')
+    return []
+  }
+
+  const validatedCostTags = new Set()
+  let nonStringEntries = 0
+  let missingSpanTags = 0
+
+  for (const costTag of costTags) {
+    if (typeof costTag !== 'string') {
+      log.warn('costTags entries must be strings. Skipping entry %s.', costTag)
+      nonStringEntries++
+      continue
+    }
+    if (!Object.hasOwn(spanTags, costTag)) {
+      log.warn('costTags entry "%s" must reference a key present in span tags. Skipping entry.', costTag)
+      missingSpanTags++
+      continue
+    }
+    validatedCostTags.add(costTag)
+  }
+
+  if (nonStringEntries) {
+    telemetry.recordCostTagsSubmitted(span, nonStringEntries, source, 'error', 'non_string_entry')
+  }
+  if (missingSpanTags) {
+    telemetry.recordCostTagsSubmitted(span, missingSpanTags, source, 'error', 'missing_span_tag')
+  }
+  if (validatedCostTags.size) {
+    telemetry.recordCostTagsSubmitted(span, validatedCostTags.size, source, 'success')
+  }
+
+  return [...validatedCostTags]
+}
+
 // extracts the argument names from a function string
 function parseArgumentNames (str) {
   const result = []
@@ -174,9 +236,22 @@ function spanHasError (span) {
   return !!(tags.error || tags['error.type'])
 }
 
+// LLM SDKs stream tool-call argument JSON across SSE chunks; a malformed
+// accumulation would otherwise throw straight into the chunk subscriber.
+function safeJsonParse (value, fallback) {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return fallback === undefined ? value : fallback
+  }
+}
+
 module.exports = {
   encodeUnicode,
+  validateCostTags,
   validateKind,
   getFunctionArguments,
+  safeJsonParse,
   spanHasError,
 }

package/packages/dd-trace/src/opentelemetry/active-span-proxy.js

@@ -0,0 +1,42 @@
+'use strict'
+
+const BridgeSpanBase = require('./bridge-span-base')
+const { setOtelResource } = require('./span-helpers')
+
+/**
+ * OTel `Span`-compatible proxy around an already-active Datadog span.
+ *
+ * Makes `trace.getActiveSpan()` forward attribute/link/event/status/exception writes onto
+ * the Datadog span. `end()` is intentionally a no-op: the span's lifecycle belongs to
+ * whoever created it. Mutation methods all bail out once the underlying Datadog span has
+ * finished (gated inside the helpers), matching OTel `Span` semantics.
+ */
+class ActiveSpanProxy extends BridgeSpanBase {
+  /** @type {import('./span_context')} */
+  #otelSpanContext
+
+  /**
+   * @param {import('../opentracing/span')} ddSpan
+   * @param {import('./span_context')} otelSpanContext
+   */
+  constructor (ddSpan, otelSpanContext) {
+    super(ddSpan)
+    this.#otelSpanContext = otelSpanContext
+  }
+
+  spanContext () {
+    return this.#otelSpanContext
+  }
+
+  /**
+   * @param {string} name
+   */
+  updateName (name) {
+    setOtelResource(this._ddSpan, name)
+    return this
+  }
+
+  end () {}
+}
+
+module.exports = ActiveSpanProxy

package/packages/dd-trace/src/opentelemetry/bridge-span-base.js

@@ -0,0 +1,106 @@
+'use strict'
+
+const {
+  addOtelEvent,
+  addOtelLink,
+  addOtelLinks,
+  applyOtelStatus,
+  recordException,
+  setOtelAttribute,
+  setOtelAttributes,
+} = require('./span-helpers')
+
+/**
+ * Shared base for the OTel-bridge span classes (`Span` and `ActiveSpanProxy`). Subclasses
+ * pass the underlying Datadog span to `super(ddSpan)` and provide `spanContext()`, `end()`,
+ * and `updateName()`. The writable-span gate lives in the helpers in `span-helpers.js`,
+ * so neither bridge can drift from it.
+ *
+ * `_ddSpan` is left as a `_underscore` field rather than `#private` so the bridge does not
+ * expand its published API to expose the underlying DD span. External callers that need
+ * the reference (`ContextManager` proxy-cache check, OTLP serialization, tests) reach in
+ * via `_ddSpan`, matching the existing convention for "internal, may break".
+ */
+class BridgeSpanBase {
+  // OTel SpanStatusCode: 0 = UNSET, 1 = OK, 2 = ERROR. Tracked for OK-is-final precedence.
+  #statusCode = 0
+
+  /**
+   * @param {import('../opentracing/span')} ddSpan
+   */
+  constructor (ddSpan) {
+    this._ddSpan = ddSpan
+  }
+
+  get ended () {
+    return this._ddSpan._duration !== undefined
+  }
+
+  isRecording () {
+    return !this.ended
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('@opentelemetry/api').AttributeValue} value
+   */
+  setAttribute (key, value) {
+    setOtelAttribute(this._ddSpan, key, value)
+    return this
+  }
+
+  /**
+   * @param {import('@opentelemetry/api').Attributes} attributes
+   */
+  setAttributes (attributes) {
+    setOtelAttributes(this._ddSpan, attributes)
+    return this
+  }
+
+  /**
+   * @param {string} name
+   * @param {import('@opentelemetry/api').Attributes | import('@opentelemetry/api').TimeInput} [attributesOrStartTime]
+   * @param {import('@opentelemetry/api').TimeInput} [startTime]
+   */
+  addEvent (name, attributesOrStartTime, startTime) {
+    addOtelEvent(this._ddSpan, name, attributesOrStartTime, startTime)
+    return this
+  }
+
+  /**
+   * Accepts the OTel `Link` shape and the deprecated `(SpanContext, Attributes)` form.
+   *
+   * @param {import('@opentelemetry/api').Link | import('@opentelemetry/api').SpanContext} link
+   * @param {import('@opentelemetry/api').Attributes} [attrs]
+   */
+  addLink (link, attrs) {
+    addOtelLink(this._ddSpan, link, attrs)
+    return this
+  }
+
+  /**
+   * @param {import('@opentelemetry/api').Link[]} links
+   */
+  addLinks (links) {
+    addOtelLinks(this._ddSpan, links)
+    return this
+  }
+
+  /**
+   * @param {import('@opentelemetry/api').Exception} exception
+   * @param {import('@opentelemetry/api').TimeInput} [timeInput]
+   */
+  recordException (exception, timeInput) {
+    recordException(this._ddSpan, exception, timeInput)
+  }
+
+  /**
+   * @param {import('@opentelemetry/api').SpanStatus} status
+   */
+  setStatus (status) {
+    this.#statusCode = applyOtelStatus(this._ddSpan, this.#statusCode, status)
+    return this
+  }
+}
+
+module.exports = BridgeSpanBase