dd-trace 5.104.0 → 5.106.0

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

@@ -41,7 +41,7 @@ const VERCEL_AI_GENERATION_METADATA_PREFIX = 'ai.settings.'
  */
 function getSpanTags (ctx) {
   const span = ctx.currentStore?.span
-  return /** @type {SpanTags} */ (ctx.attributes ?? span?.context()._tags ?? {})
+  return /** @type {SpanTags} */ (ctx.attributes ?? span?.context().getTags() ?? {})
 }
 
 /**
@@ -66,11 +66,22 @@ function getOperation (span) {
 }
 
 /**
- * Get the LLM token usage from the span tags
- * Supports both AI SDK v4 (promptTokens/completionTokens) and v5 (inputTokens/outputTokens)
- * @template T extends {inputTokens: number, outputTokens: number, totalTokens: number}
- * @param {T} tags
- * @returns {Pick<T, 'inputTokens' | 'outputTokens' | 'totalTokens'>}
+ * Get the LLM token usage from the span tags.
+ *
+ * Supports both AI SDK v4 (promptTokens/completionTokens) and v5+
+ * (inputTokens/outputTokens), and surfaces prompt-cache metrics for providers
+ * that report them. The AI SDK convention is that `inputTokens` already
+ * includes cached tokens, so cache reads are reported as a subset of input
+ * tokens rather than added on top.
+ *
+ * @param {SpanTags} tags
+ * @returns {{
+ *   inputTokens?: number,
+ *   outputTokens?: number,
+ *   totalTokens?: number,
+ *   cacheReadTokens?: number,
+ *   cacheWriteTokens?: number
+ * }}
  */
 function getUsage (tags) {
   const usage = {}
@@ -87,9 +98,84 @@ function getUsage (tags) {
   const totalTokens = tags['ai.usage.totalTokens'] ?? (inputTokens + outputTokens)
   if (!Number.isNaN(totalTokens)) usage.totalTokens = totalTokens
 
+  // Prompt-cache metrics. AI SDK v6 standardizes cache READ tokens via
+  // `ai.usage.cachedInputTokens`; cache WRITE tokens (and earlier AI SDK
+  // versions / providers that don't fill `cachedInputTokens`) are only
+  // available through provider-specific `ai.response.providerMetadata`.
+  // Skip zero values: the AI SDK sets `cachedInputTokens=0` on every span
+  // regardless of provider, so emitting it would add noise to spans that
+  // don't actually use prompt caching (e.g. OpenAI).
+  const providerCache = getProviderCacheTokens(tags['ai.response.providerMetadata'])
+
+  const cacheReadTokens = tags['ai.usage.cachedInputTokens'] ?? providerCache.cacheReadTokens
+  if (cacheReadTokens) usage.cacheReadTokens = cacheReadTokens
+
+  if (providerCache.cacheWriteTokens) usage.cacheWriteTokens = providerCache.cacheWriteTokens
+
+  // Normalize `inputTokens` to the sum convention used by `bedrockruntime.js`.
+  // Some SDK combinations (e.g. `ai@5` + `@ai-sdk/amazon-bedrock@3`) pass the
+  // raw fresh count through, which makes `nonCached = input - cacheRead -
+  // cacheWrite` go negative downstream.
+  //
+  // Detection: if `inputTokens < cacheSum`, the value cannot already be a sum
+  // that includes them (non-negative arithmetic). This is provider/version
+  // agnostic and won't double-count on stacks where the SDK already
+  // normalized (`ai@6` + `bedrock@4` / `anthropic@3`, OpenAI, Google).
+  if (usage.inputTokens != null) {
+    const cacheSum = (usage.cacheReadTokens || 0) + (usage.cacheWriteTokens || 0)
+    if (usage.inputTokens < cacheSum) {
+      usage.inputTokens += cacheSum
+      if (usage.totalTokens != null) {
+        usage.totalTokens = usage.inputTokens + (usage.outputTokens || 0)
+      }
+    }
+  }
+
   return usage
 }
 
+/**
+ * Extract prompt-cache token counts from the stringified
+ * `ai.response.providerMetadata` attribute.
+ *
+ * The AI SDK does not standardize cache WRITE tokens on the usage object, and
+ * earlier versions / providers may also omit `ai.usage.cachedInputTokens`, so
+ * we read the provider-specific shape directly. Only Bedrock and Anthropic
+ * are handled here as they are the providers that report cache writes today.
+ *
+ * @see https://ai-sdk.dev/providers/ai-sdk-providers/amazon-bedrock#cache-points
+ * @see https://ai-sdk.dev/providers/ai-sdk-providers/anthropic#cache-control
+ *
+ * @param {string | undefined} providerMetadataJson
+ * @returns {{ cacheReadTokens?: number, cacheWriteTokens?: number }}
+ */
+function getProviderCacheTokens (providerMetadataJson) {
+  if (!providerMetadataJson) return {}
+
+  const metadata = getJsonStringValue(providerMetadataJson, null)
+  if (!metadata || typeof metadata !== 'object') return {}
+
+  const result = {}
+
+  const bedrockUsage = metadata.bedrock?.usage
+  if (bedrockUsage) {
+    if (bedrockUsage.cacheReadInputTokens != null) result.cacheReadTokens = bedrockUsage.cacheReadInputTokens
+    if (bedrockUsage.cacheWriteInputTokens != null) result.cacheWriteTokens = bedrockUsage.cacheWriteInputTokens
+  }
+
+  const anthropic = metadata.anthropic
+  if (anthropic) {
+    if (result.cacheReadTokens == null && anthropic.cacheReadInputTokens != null) {
+      result.cacheReadTokens = anthropic.cacheReadInputTokens
+    }
+    if (result.cacheWriteTokens == null && anthropic.cacheCreationInputTokens != null) {
+      result.cacheWriteTokens = anthropic.cacheCreationInputTokens
+    }
+  }
+
+  return result
+}
+
 /**
  * Safely JSON parses a string value with a default fallback
  * @template T typeof defaultValue

package/packages/dd-trace/src/llmobs/plugins/bedrockruntime.js

@@ -7,12 +7,22 @@ const {
   extractTextAndResponseReason,
   parseModelId,
   extractTextAndResponseReasonFromStream,
+  extractConverseToolDefinitions,
+  extractRequestParamsConverse,
+  extractTextAndResponseReasonConverse,
+  extractTextAndResponseReasonConverseFromStream,
 } = require('../../../../datadog-plugin-aws-sdk/src/services/bedrockruntime/utils')
 const BaseLLMObsPlugin = require('./base')
 
 const llmobsStore = storage('llmobs')
 
-const ENABLED_OPERATIONS = new Set(['invokeModel', 'invokeModelWithResponseStream'])
+const ENABLED_OPERATIONS = new Set([
+  'invokeModel',
+  'invokeModelWithResponseStream',
+  'converse',
+  'converseStream',
+])
+const CONVERSE_OPERATIONS = new Set(['converse', 'converseStream'])
 
 /**
  * @typedef {{
@@ -79,10 +89,18 @@ class BedrockRuntimeLLMObsPlugin extends BaseLLMObsPlugin {
   setLLMObsTags ({ ctx, request, span, response, modelProvider, modelName, tokensFromHeaders }) {
     const isStream = request?.operation?.toLowerCase().includes('stream')
     telemetry.incrementLLMObsSpanStartCount({ autoinstrumented: true, integration: 'bedrock' })
+    this.#registerSpan(span, request)
 
+    if (CONVERSE_OPERATIONS.has(request?.operation)) {
+      this.#tagConverseSpan({ ctx, request, span, response, tokensFromHeaders, isStream })
+    } else {
+      this.#tagInvokeModelSpan({ ctx, request, span, response, modelProvider, modelName, tokensFromHeaders, isStream })
+    }
+  }
+
+  #registerSpan (span, request) {
     const parent = llmobsStore.getStore()?.span
     // Use full modelId and unified provider for LLMObs (required for backend cost estimation).
-    // Split modelProvider/modelName from parseModelId() are still used below for response parsing.
     this._tagger.registerLLMObsSpan(span, {
       parent,
       modelName: request.params.modelId.toLowerCase(),
@@ -91,38 +109,42 @@ class BedrockRuntimeLLMObsPlugin extends BaseLLMObsPlugin {
       name: 'bedrock-runtime.command',
       integration: 'bedrock',
     })
+  }
+
+  #tagConverseSpan ({ ctx, request, span, response, tokensFromHeaders, isStream }) {
+    const requestParams = extractRequestParamsConverse(request.params)
+    const textAndResponseReason = isStream
+      ? extractTextAndResponseReasonConverseFromStream(ctx.chunks)
+      : extractTextAndResponseReasonConverse(response)
+
+    const toolDefinitions = extractConverseToolDefinitions(request.params)
+    if (toolDefinitions.length > 0) this._tagger.tagToolDefinitions(span, toolDefinitions)
+    if (textAndResponseReason.finishReason) {
+      this._tagger.tagMetadata(span, { stop_reason: textAndResponseReason.finishReason })
+    }
+    this.#tagCommon({ span, requestParams, textAndResponseReason, tokensFromHeaders })
+  }
 
+  #tagInvokeModelSpan ({ ctx, request, span, response, modelProvider, modelName, tokensFromHeaders, isStream }) {
     const requestParams = extractRequestParams(request.params, modelProvider)
     // for streamed responses, we'll use the coerced response object we formed in the stream handler
     const textAndResponseReason = isStream
       ? extractTextAndResponseReasonFromStream(ctx.chunks, modelProvider, modelName)
       : extractTextAndResponseReason(response, modelProvider, modelName)
 
-    // add metadata tags
+    this.#tagCommon({ span, requestParams, textAndResponseReason, tokensFromHeaders })
+  }
+
+  #tagCommon ({ span, requestParams, textAndResponseReason, tokensFromHeaders }) {
     this._tagger.tagMetadata(span, {
       temperature: Number.parseFloat(requestParams.temperature) || 0,
       max_tokens: Number.parseInt(requestParams.maxTokens) || 0,
     })
-
-    // add I/O tags
-    this._tagger.tagLLMIO(
-      span,
-      requestParams.prompt,
-      [{ content: textAndResponseReason.message, role: textAndResponseReason.role }]
-    )
-
-    // add token metrics
-    const { inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens } = extractTokens({
+    this._tagger.tagLLMIO(span, requestParams.prompt, textAndResponseReason.messages)
+    this._tagger.tagMetrics(span, extractTokens({
       tokensFromHeaders,
       usage: textAndResponseReason.usage,
-    })
-    this._tagger.tagMetrics(span, {
-      inputTokens,
-      outputTokens,
-      totalTokens,
-      cacheReadTokens,
-      cacheWriteTokens,
-    })
+    }))
   }
 }
 

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

@@ -55,7 +55,7 @@ class GenAiLLMObsPlugin extends LLMObsPlugin {
 
     const inputs = args[0]
     const response = ctx.result
-    const error = !!span.context()._tags.error
+    const error = !!span.context().getTag('error')
 
     const operation = getOperation(methodName)
 

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

@@ -7,7 +7,7 @@ class LangChainLLMObsHandler {
   }
 
   getName ({ span }) {
-    return span?.context()._tags?.['resource.name']
+    return span?.context()?.getTag('resource.name')
   }
 
   setMetaTags () {}

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

@@ -44,7 +44,8 @@ class BaseLangChainLLMObsPlugin extends LLMObsPlugin {
 
   getLLMObsSpanRegisterOptions (ctx) {
     const span = ctx.currentStore?.span
-    const tags = span?.context()._tags || {}
+    const spanContext = span?.context()
+    const tags = spanContext?.getTags() || {}
 
     const modelProvider = tags['langchain.request.provider'] // could be undefined
     const modelName = tags['langchain.request.model'] // could be undefined
@@ -76,7 +77,7 @@ class BaseLangChainLLMObsPlugin extends LLMObsPlugin {
       return
     }
 
-    const provider = span?.context()._tags['langchain.request.provider']
+    const provider = span?.context()?.getTag('langchain.request.provider')
     const integrationName = this.getIntegrationName(type, provider)
     this.setMetadata(span, provider)
 
@@ -93,14 +94,15 @@ class BaseLangChainLLMObsPlugin extends LLMObsPlugin {
     const metadata = {}
 
     // these fields won't be set for non model-based operations
+    const spanContext = span?.context()
     const temperature =
-      span?.context()._tags[`langchain.request.${provider}.parameters.temperature`] ||
-      span?.context()._tags[`langchain.request.${provider}.parameters.model_kwargs.temperature`]
+      spanContext?.getTag(`langchain.request.${provider}.parameters.temperature`) ||
+      spanContext?.getTag(`langchain.request.${provider}.parameters.model_kwargs.temperature`)
 
     const maxTokens =
-      span?.context()._tags[`langchain.request.${provider}.parameters.max_tokens`] ||
-      span?.context()._tags[`langchain.request.${provider}.parameters.maxTokens`] ||
-      span?.context()._tags[`langchain.request.${provider}.parameters.model_kwargs.max_tokens`]
+      spanContext?.getTag(`langchain.request.${provider}.parameters.max_tokens`) ||
+      spanContext?.getTag(`langchain.request.${provider}.parameters.maxTokens`) ||
+      spanContext?.getTag(`langchain.request.${provider}.parameters.model_kwargs.max_tokens`)
 
     if (temperature) {
       metadata.temperature = Number.parseFloat(temperature)

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

@@ -35,7 +35,7 @@ class PregelStreamLLMObsPlugin extends LLMObsPlugin {
 
 class NextStreamLLMObsPlugin extends LLMObsPlugin {
   static id = 'llmobs_langgraph_next_stream'
-  static prefix = 'tracing:orchestrion:@langchain/langgraph:Pregel_stream_next'
+  static prefix = 'tracing:orchestrion:@langchain/langgraph:Pregel_stream:next'
 
   start () {} // no-op: span was already registered by PregelStreamLLMObsPlugin
 

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

@@ -63,7 +63,7 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
 
     const inputs = ctx.args[0] // completion, chat completion, and embeddings take one argument
     const response = ctx.result?.data // no result if error
-    const error = !!span.context()._tags.error
+    const error = !!span.context().getTag('error')
 
     const operation = getOperation(methodName)
 

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

@@ -11,8 +11,6 @@ const {
   SPAN_KIND,
   OUTPUT_VALUE,
   INPUT_VALUE,
-  LLMOBS_TRACE_ID_BRIDGE_KEY,
-  LLMOBS_PARENT_ID_BRIDGE_KEY,
 } = require('./constants/tags')
 const {
   getFunctionArguments,
@@ -553,20 +551,6 @@ 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

@@ -107,7 +107,7 @@ class LLMObsSpanProcessor {
       // 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'
+        span.context().setTag(LLMOBS_SUBMITTED_TAG_KEY, '1')
       }
     } catch (e) {
       // this should be a rare case
@@ -123,7 +123,7 @@ class LLMObsSpanProcessor {
   format (span) {
     let inputType, outputType
 
-    const spanTags = span.context()._tags
+    const spanTags = span.context().getTags()
     const mlObsTags = LLMObsTagger.tagMap.get(span)
 
     const spanKind = mlObsTags[SPAN_KIND]
@@ -318,7 +318,7 @@ class LLMObsSpanProcessor {
       language: 'javascript',
     }
 
-    const errType = span.context()._tags[ERROR_TYPE] || error?.name
+    const errType = span.context().getTag(ERROR_TYPE) || error?.name
     if (errType) tags.error_type = errType
 
     if (sessionId) tags.session_id = sessionId

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

@@ -43,7 +43,7 @@ const {
   INSTRUMENTATION_METHOD_ANNOTATED,
 } = require('./constants/tags')
 const { storage } = require('./storage')
-const { validateCostTags } = require('./util')
+const { findGenAIAncestorSpanId, validateCostTags, writeBridgeTags } = require('./util')
 
 // global registry of LLMObs spans
 // maps LLMObs spans to their annotations
@@ -97,6 +97,13 @@ class LLMObsTagger {
 
     this._register(span)
 
+    // 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 })
+
     this._setTag(span, ML_APP, spanMlApp)
 
     if (name) this._setTag(span, NAME, name)
@@ -113,6 +120,7 @@ class LLMObsTagger {
     const parentId =
       parent?.context().toSpanId() ??
       span.context()._trace.tags[PROPAGATED_PARENT_ID_KEY] ??
+      genAIAncestorSpanId ??
       ROOT_PARENT_ID
     this._setTag(span, PARENT_ID_KEY, parentId)
 

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

@@ -45,7 +45,7 @@ function incrementLLMObsSpanStartCount (tags, value = 1) {
 
 function incrementLLMObsSpanFinishedCount (span, value = 1) {
   const mlObsTags = LLMObsTagger.tagMap.get(span)
-  const spanTags = span.context()._tags
+  const spanTags = span.context().getTags()
 
   const isRootSpan = mlObsTags[PARENT_ID_KEY] === ROOT_PARENT_ID
   const hasSessionId = mlObsTags[SESSION_ID] != null

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

@@ -1,7 +1,11 @@
 'use strict'
 
 const log = require('../log')
-const { SPAN_KINDS } = require('./constants/tags')
+const {
+  LLMOBS_PARENT_ID_BRIDGE_KEY,
+  LLMOBS_TRACE_ID_BRIDGE_KEY,
+  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
@@ -233,8 +237,8 @@ function getFunctionArguments (fn, args = []) {
 }
 
 function spanHasError (span) {
-  const tags = span.context()._tags
-  return !!(tags.error || tags['error.type'])
+  const spanContext = span.context()
+  return !!(spanContext.getTag('error') || spanContext.getTag('error.type'))
 }
 
 // LLM SDKs stream tool-call argument JSON across SSE chunks; a malformed
@@ -248,11 +252,70 @@ function safeJsonParse (value, fallback) {
   }
 }
 
+// Bridge tags read by the trace-indexer to pull OTel `gen_ai.*` spans into
+// the same LLMObs trace. Written once per local trace (first-writer wins on
+// `_trace.tags`). Pass `includeParentId: false` when the span sits below an
+// OTel `gen_ai.*` ancestor — without it the indexer treats this span as the
+// LLMObs root and hoists the gen_ai ancestors under it, inverting the trace.
+/**
+ * @param {import('../opentracing/span')} span
+ * @param {{ includeParentId?: boolean }} [opts]
+ */
+function writeBridgeTags (span, { includeParentId = true } = {}) {
+  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)
+  if (includeParentId) {
+    traceTags[LLMOBS_PARENT_ID_BRIDGE_KEY] = span.context().toSpanId()
+  }
+}
+
+// Walks the APM parent chain for the nearest ancestor with any `gen_ai.*`
+// tag. Lets an auto-instrumented LLMObs span nested under a manual OTel
+// workflow point its `parent_id` at the OTel parent so the SDK-emitted
+// event renders under it instead of as a parallel root.
+/**
+ * @param {import('../opentracing/span')} span
+ * @returns {string | null}
+ */
+function findGenAIAncestorSpanId (span) {
+  const ctx = span?.context?.()
+  let parentId = ctx?._parentId?.toString(10)
+  if (!parentId || parentId === '0') return null
+
+  const started = ctx._trace?.started
+  if (!started || started.length === 0) return null
+
+  // Linear scan per hop — parent chains are short, avoids a per-call Map.
+  while (parentId && parentId !== '0') {
+    let parent = null
+    for (const s of started) {
+      if (s.context()._spanId.toString(10) === parentId) {
+        parent = s
+        break
+      }
+    }
+    if (!parent) return null
+
+    const tags = parent.context().getTags()
+    if (tags) {
+      for (const key of Object.keys(tags)) {
+        if (key.startsWith('gen_ai.')) return parentId
+      }
+    }
+
+    parentId = parent.context()._parentId?.toString(10)
+  }
+  return null
+}
+
 module.exports = {
   encodeUnicode,
+  findGenAIAncestorSpanId,
   validateCostTags,
   validateKind,
   getFunctionArguments,
   safeJsonParse,
   spanHasError,
+  writeBridgeTags,
 }

package/packages/dd-trace/src/log/index.js

@@ -107,7 +107,7 @@ function publishFormatted (ch, formatter, ...args) {
 
 function getErrorLog (err) {
   if (typeof err?.delegate === 'function') {
-    const result = err.delegate()
+    const result = err.delegate(...err.args)
     return Array.isArray(result) ? Log.parse(...result) : Log.parse(result)
   }
   return err