dd-trace 6.9.0 → 6.10.0

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

@@ -23,7 +23,11 @@ const {
   OUTPUT_MESSAGES,
   TAGS,
   NAME,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
   PROPAGATED_PARENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_NAME_KEY,
   ROOT_PARENT_ID,
   CACHE_READ_INPUT_TOKENS_METRIC_KEY,
   CACHE_WRITE_INPUT_TOKENS_METRIC_KEY,
@@ -57,6 +61,7 @@ const {
 const { storage } = require('./storage')
 const {
   findGenAIAncestorSpanId,
+  resolveAgentAttribution,
   validateCostTags,
   writeBridgeTags,
   validateToolDefinitions,
@@ -173,6 +178,7 @@ class LLMObsTagger {
     this._setTag(span, PARENT_ID_KEY, parentId)
 
     this.#tagSamplingDecision(span, parent)
+    this.#tagAgentAttribution(span, parent)
 
     // apply annotation context
     const annotationContext = storage.getStore()?.annotationContext
@@ -229,6 +235,34 @@ class LLMObsTagger {
     if (samplingDecision != null) this._setTag(span, SAMPLING_DECISION, samplingDecision)
   }
 
+  /**
+   * Store the nearest agent ancestor on the span so it can be surfaced as
+   * `meta.agent_attribution` at finish. Resolved once here, at registration, so downstream
+   * children inherit it with a single lookup rather than walking the ancestor chain.
+   *
+   * @param {import('../opentracing/span')} span
+   * @param {import('../opentracing/span')} [parent] the LLMObs parent span, if any
+   */
+  // TODO: spans whose kind changes after registration (e.g. claude-agent-sdk tools promoted to
+  // sub-agents) will not retroactively update already-finished children's attribution. Follow up.
+  #tagAgentAttribution (span, parent) {
+    let name, spanId
+    if (registry.has(parent)) {
+      // Local LLMObs parent: attribute to it if it is an agent, else inherit its resolution.
+      ({ name, spanId } = resolveAgentAttribution(registry.get(parent), parent))
+    } else if (span.context()._trace.tags[PROPAGATED_PARENT_ID_KEY]) {
+      // Distributed LLMObs parent: inherit the nearest agent propagated from upstream. The
+      // name may be absent when the upstream hop ran an older SDK or its name was not
+      // wire-safe; the id-only case is expected and the backend resolves the name by span id.
+      const traceTags = span.context()._trace.tags
+      name = traceTags[PROPAGATED_PARENT_AGENT_NAME_KEY]
+      spanId = traceTags[PROPAGATED_PARENT_AGENT_ID_KEY]
+    }
+
+    if (name != null) this._setTag(span, PARENT_AGENT_NAME, name)
+    if (spanId != null) this._setTag(span, PARENT_AGENT_SPAN_ID, spanId)
+  }
+
   // TODO: similarly for the following `tag` methods,
   // how can we transition from a span weakmap to core API functionality
   tagLLMIO (span, inputData, outputData) {
@@ -696,6 +730,59 @@ class LLMObsTagger {
     return filteredAudioParts
   }
 
+  // Image counterpart of #filterAudioParts, with the same wire shape and validation.
+  #filterImageParts (imageParts) {
+    if (!Array.isArray(imageParts)) {
+      imageParts = [imageParts]
+    }
+
+    const filteredImageParts = []
+    for (const imagePart of imageParts) {
+      if (imagePart == null || typeof imagePart !== 'object') {
+        this.#handleFailure('Image part must be an object.', 'invalid_io_messages')
+        continue
+      }
+
+      const { mimeType, content, attachmentKey } = imagePart
+
+      if (typeof mimeType !== 'string' || !mimeType) {
+        this.#handleFailure('Image part mimeType must be a non-empty string.', 'invalid_io_messages')
+        continue
+      }
+
+      if (content == null && attachmentKey == null) {
+        this.#handleFailure("Image part must have either 'content' or 'attachmentKey'.", 'invalid_io_messages')
+        continue
+      }
+
+      if (content != null && attachmentKey != null) {
+        this.#handleFailure(
+          "Image part must have only one of 'content' or 'attachmentKey', not both.", 'invalid_io_messages'
+        )
+        continue
+      }
+
+      const imagePartObj = { mime_type: mimeType }
+
+      if (content == null) {
+        if (typeof attachmentKey !== 'string') {
+          this.#handleFailure('Image part attachmentKey must be a string.', 'invalid_io_messages')
+          continue
+        }
+        imagePartObj.attachment_key = attachmentKey
+      } else {
+        if (typeof content !== 'string') {
+          this.#handleFailure('Image part content must be a base64-encoded string.', 'invalid_io_messages')
+          continue
+        }
+        imagePartObj.content = content
+      }
+
+      filteredImageParts.push(imagePartObj)
+    }
+    return filteredImageParts
+  }
+
   #tagMessages (span, data, key) {
     if (!data) {
       return
@@ -723,6 +810,7 @@ class LLMObsTagger {
         toolResults,
         toolId,
         audioParts,
+        imageParts,
       } = message
       const messageObj = {}
 
@@ -764,6 +852,14 @@ class LLMObsTagger {
         }
       }
 
+      if (imageParts != null) {
+        const filteredImageParts = this.#filterImageParts(imageParts)
+
+        if (filteredImageParts.length) {
+          messageObj.image_parts = filteredImageParts
+        }
+      }
+
       if (toolId) {
         if (role === 'tool') {
           condition = this.#tagConditionalString(toolId, 'Tool ID', messageObj, 'tool_id') && condition

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

@@ -6,6 +6,10 @@ const {
   LLMOBS_PARENT_ID_BRIDGE_KEY,
   LLMOBS_TRACE_ID_BRIDGE_KEY,
   SPAN_KINDS,
+  SPAN_KIND,
+  NAME,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
 } = require('./constants/tags')
 
 const DECIMAL_TRACE_ID_REGEX = /^\d+$/
@@ -294,6 +298,76 @@ function getFunctionArguments (fn, args = []) {
   }
 }
 
+// The `x-datadog-tags` tagset encoder rejects commas (the entry delimiter) and any byte
+// outside 0x20-0x7E, and a raise there drops the ENTIRE header (taking ml_app,
+// llmobs_trace_id, parent_id, sampling with it). An agent name is arbitrary user text, so it
+// must be skipped rather than sanitized when unsafe: only the digit-safe id then propagates and
+// the backend resolves the real name by span id. `=` is legal in tagset values (illegal only in
+// keys), so a name containing `=` is safe and must not be dropped.
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function agentNameWireSafe (name) {
+  // Conservative slice of the 512B shared tagset budget, mirroring dd-trace-py.
+  if (Buffer.byteLength(name, 'utf8') > 256) return false
+  for (let index = 0; index < name.length; index++) {
+    const code = name.charCodeAt(index)
+    if (code < 0x20 || code > 0x7E || code === 0x2C /* comma */) return false
+  }
+  return true
+}
+
+/**
+ * Resolve the nearest agent that a *child* of `span` should be attributed to.
+ *
+ * If `span` is itself an agent, the child attributes directly to `span`. Otherwise `span`
+ * already resolved its own nearest agent at registration, so the child inherits that with a
+ * single lookup rather than walking the ancestor chain. An agent never attributes itself.
+ *
+ * @param {Record<string, unknown> | undefined} tags - Registry entry for the parent span.
+ * @param {import('../opentracing/span')} [span] - The parent span itself (needed for span id / name).
+ * @returns {{ name: string | undefined, spanId: string | undefined }}
+ */
+function resolveAgentAttribution (tags, span) {
+  if (!tags) return { name: undefined, spanId: undefined }
+  if (tags[SPAN_KIND] === 'agent') {
+    return { name: tags[NAME] || span._name, spanId: span.context().toSpanId() }
+  }
+  return { name: tags[PARENT_AGENT_NAME], spanId: tags[PARENT_AGENT_SPAN_ID] }
+}
+
+/**
+ * Removes all `key=value` entries for the given key from a comma-separated tagset string.
+ *
+ * @param {string} tags - Existing tagset string (may be empty).
+ * @param {string} key
+ * @returns {string}
+ */
+function stripTagsetEntry (tags, key) {
+  if (!tags.includes(key)) return tags
+  return tags.split(',').filter(entry => !entry.startsWith(`${key}=`)).join(',')
+}
+
+/**
+ * Appends `key=value` to the tagset string with a comma separator, but only when `value` is
+ * truthy, passes the optional `safeguard` predicate, and fits within `maxTagSetLength`. Returns
+ * the original `tags` unchanged when the value is absent, unsafe, or would overflow the budget.
+ *
+ * @param {string} tags - Existing tagset string (may be empty).
+ * @param {string} key
+ * @param {string | undefined} value
+ * @param {((v: string) => boolean) | null} [safeguard]
+ * @param {number} [maxTagSetLength]
+ * @returns {string}
+ */
+function appendOptionalPropagatedTag (tags, key, value, safeguard, maxTagSetLength) {
+  if (!value || (safeguard && !safeguard(value))) return tags
+  const entry = `${tags ? ',' : ''}${key}=${value}`
+  if (maxTagSetLength != null && tags.length + entry.length > maxTagSetLength) return tags
+  return `${tags}${entry}`
+}
+
 function spanHasError (span) {
   const spanContext = span.context()
   return !!(spanContext.getTag('error') || spanContext.getTag('error.type'))
@@ -443,6 +517,8 @@ function formatAudioPart (data, mimeType) {
 }
 
 module.exports = {
+  agentNameWireSafe,
+  appendOptionalPropagatedTag,
   audioMimeTypeFromFormat,
   encodeUnicode,
   findGenAIAncestorSpanId,
@@ -450,6 +526,8 @@ module.exports = {
   llmObsTraceIdToWire,
   normalizeLlmObsTraceId,
   formatAudioPart,
+  resolveAgentAttribution,
+  stripTagsetEntry,
   validateCostTags,
   validateKind,
   getFunctionArguments,