dd-trace 5.99.1 → 5.101.0

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/openfeature/eval-metrics-hook.js

@@ -30,7 +30,7 @@ const COUNTER_UNIT = '{evaluation}'
  * 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.
+ * When `config.DD_METRICS_OTEL_ENABLED` is false, `finally()` is always a no-op.
  */
 class EvalMetricsHook {
   #enabled = false
@@ -40,7 +40,7 @@ class EvalMetricsHook {
    * @param {import('../config')} config - Tracer configuration object
    */
   constructor (config) {
-    this.#enabled = config.otelMetricsEnabled === true
+    this.#enabled = config.DD_METRICS_OTEL_ENABLED === true
   }
 
   /**

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

package/packages/dd-trace/src/opentelemetry/context_manager.js

@@ -2,8 +2,9 @@
 
 const { trace, ROOT_CONTEXT, propagation } = require('@opentelemetry/api')
 const { storage } = require('../../../datadog-core')
-const { getAllBaggageItems, setBaggageItem, removeAllBaggageItems } = require('../baggage')
+const { getAllBaggageItems, setAllBaggageItems, removeAllBaggageItems } = require('../baggage')
 
+const ActiveSpanProxy = require('./active-span-proxy')
 const SpanContext = require('./span_context')
 
 class ContextManager {
@@ -48,11 +49,19 @@ class ContextManager {
       ddContext._otelSpanContext = new SpanContext(ddContext)
     }
 
-    if (store && trace.getSpanContext(store) === ddContext._otelSpanContext) {
+    // Cache the active-span proxy next to the bridge span context. This lets
+    // `trace.getActiveSpan()` forward attribute/status/link/exception writes
+    // onto the active Datadog span rather than returning a NonRecordingSpan
+    // whose mutation methods are silent no-ops.
+    if (!ddContext._otelActiveSpan) {
+      ddContext._otelActiveSpan = new ActiveSpanProxy(activeSpan, ddContext._otelSpanContext)
+    }
+
+    if (store && trace.getSpan(store) === ddContext._otelActiveSpan) {
       return otelBaggages ? propagation.setBaggage(store, otelBaggages) : store
     }
 
-    const wrappedContext = trace.setSpanContext(baseContext, ddContext._otelSpanContext)
+    const wrappedContext = trace.setSpan(baseContext, ddContext._otelActiveSpan)
     return otelBaggages ? propagation.setBaggage(wrappedContext, otelBaggages) : wrappedContext
   }
 
@@ -64,13 +73,16 @@ class ContextManager {
       return this._store.run(context, cb, ...args)
     }
     const baggages = propagation.getBaggage(context)
-    let baggageItems = []
-    if (baggages) {
-      baggageItems = baggages.getAllEntries()
-    }
-    removeAllBaggageItems()
-    for (const baggage of baggageItems) {
-      setBaggageItem(baggage[0], baggage[1].value)
+    const baggageItems = baggages ? baggages.getAllEntries() : []
+    if (baggageItems.length > 0) {
+      /** @type {Record<string, string>} */
+      const items = {}
+      for (const [key, entry] of baggageItems) {
+        items[key] = entry.value
+      }
+      setAllBaggageItems(items)
+    } else {
+      removeAllBaggageItems()
     }
     if (span && span._ddSpan) {
       const ddSpan = span._ddSpan

package/packages/dd-trace/src/opentelemetry/span-helpers.js

@@ -0,0 +1,308 @@
+'use strict'
+
+const { performance } = require('node:perf_hooks')
+
+const { timeInputToHrTime } = require('../../../../vendor/dist/@opentelemetry/core')
+
+const { ERROR_MESSAGE, ERROR_STACK, ERROR_TYPE, IGNORE_OTEL_ERROR } = require('../constants')
+const DatadogSpanContext = require('../opentracing/span_context')
+const TraceState = require('../opentracing/propagation/tracestate')
+
+const id = require('../id')
+
+const { timeOrigin } = performance
+
+/**
+ * @typedef {{
+ *   _ddContext?: import('../opentracing/span_context'),
+ *   toTraceId?: (get128?: boolean) => string,
+ *   toSpanId?: (get128?: boolean) => string,
+ *   traceId?: string,
+ *   spanId?: string,
+ *   traceFlags?: number,
+ *   traceState?: { serialize: () => string }
+ * }} LinkContextLike
+ * @typedef {{ context: LinkContextLike, attributes?: Record<string, unknown> }} OtelLink
+ * @typedef {{
+ *   name?: string,
+ *   message?: string,
+ *   stack?: string,
+ *   type?: string,
+ *   escaped?: unknown
+ * }} ExceptionLike
+ * @typedef {number | Date | [number, number]} TimeInput
+ */
+
+/**
+ * @param {import('../opentracing/span')} ddSpan
+ */
+function isWritable (ddSpan) {
+  return ddSpan._duration === undefined
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is TimeInput}
+ */
+function isTimeInput (value) {
+  return typeof value === 'number' ||
+    value instanceof Date ||
+    (Array.isArray(value) && value.length === 2 &&
+      typeof value[0] === 'number' && typeof value[1] === 'number')
+}
+
+/**
+ * @param {LinkContextLike} ctx
+ * @returns {ctx is import('../opentracing/span_context')}
+ */
+function isDatadogSpanContext (ctx) {
+  return typeof ctx.toTraceId === 'function' && typeof ctx.toSpanId === 'function'
+}
+
+/**
+ * @param {unknown} link
+ * @returns {link is OtelLink}
+ */
+function isOtelLink (link) {
+  return typeof link === 'object' && link !== null && 'context' in link
+}
+
+/**
+ * The OTel-shipped `hrTimeToMilliseconds` rounds, which drops sub-millisecond precision.
+ *
+ * @param {TimeInput} [timeInput]
+ */
+function timeInputToMilliseconds (timeInput) {
+  const hrTime = timeInputToHrTime(timeInput || (performance.now() + timeOrigin))
+  return hrTime[0] * 1e3 + hrTime[1] / 1e6
+}
+
+/**
+ * Resolves the OTel `addEvent(name, attributesOrStartTime, startTime)` overloads into a
+ * `{ attributes, startTime }` pair where `startTime` is always a millisecond number, so the
+ * caller can hand the OTel inputs straight to `DatadogSpan.addEvent` without `Date`/hrTime
+ * confusion.
+ *
+ * @param {Record<string, unknown> | TimeInput | undefined} attributesOrStartTime
+ * @param {TimeInput} [startTime]
+ */
+function normalizeOtelEvent (attributesOrStartTime, startTime) {
+  let attributes
+  if (attributesOrStartTime) {
+    if (isTimeInput(attributesOrStartTime)) {
+      startTime = attributesOrStartTime
+    } else if (typeof attributesOrStartTime === 'object') {
+      attributes = attributesOrStartTime
+    }
+  }
+  return { attributes, startTime: timeInputToMilliseconds(startTime) }
+}
+
+/**
+ * Accepts the native `DatadogSpanContext` (`toTraceId`/`toSpanId`), the bridge wrapper
+ * (`_ddContext`), or a standard OTel `SpanContext` (`traceId`/`spanId` strings); returns
+ * a `DatadogSpanContext` or `undefined` when nothing usable is present.
+ *
+ * @param {LinkContextLike | undefined | null} context
+ */
+function normalizeLinkContext (context) {
+  if (!context) return
+
+  if (context._ddContext) return context._ddContext
+
+  if (isDatadogSpanContext(context)) return context
+
+  if (typeof context.traceId !== 'string' || typeof context.spanId !== 'string') return
+
+  let sampling
+  if (typeof context.traceFlags === 'number') {
+    sampling = { priority: context.traceFlags & 1 }
+  }
+
+  let tracestate
+  if (context.traceState?.serialize) {
+    tracestate = TraceState.fromString(context.traceState.serialize())
+  }
+
+  return new DatadogSpanContext({
+    traceId: id(context.traceId, 16),
+    spanId: id(context.spanId, 16),
+    sampling,
+    tracestate,
+  })
+}
+
+/**
+ * Mirrors `http.response.status_code` onto `http.status_code` (DD's special tag used by APM
+ * trace metrics and client-side stats); both names end up on the span.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} key
+ * @param {unknown} value
+ */
+function setOtelAttribute (ddSpan, key, value) {
+  if (!isWritable(ddSpan)) return
+
+  if (key === 'http.response.status_code') {
+    ddSpan.setTag('http.status_code', String(value))
+  }
+
+  ddSpan.setTag(key, value)
+}
+
+/**
+ * Same `http.status_code` mirror as `setOtelAttribute`; does not mutate the caller's
+ * `attributes` object.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {Record<string, unknown>} attributes
+ */
+function setOtelAttributes (ddSpan, attributes) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.addTags(attributes)
+  if ('http.response.status_code' in attributes) {
+    ddSpan.setTag('http.status_code', String(attributes['http.response.status_code']))
+  }
+}
+
+/**
+ * Accepts both `{ context, attributes }` and the deprecated `(context, attrs)` form.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {LinkContextLike | OtelLink} link
+ * @param {Record<string, unknown>} [attrs]
+ */
+function addOtelLink (ddSpan, link, attrs) {
+  if (!isWritable(ddSpan) || !link) return
+
+  // TODO: Drop the (context, attrs) form in v6.0.0.
+  const { context, attributes } = isOtelLink(link)
+    ? link
+    : { context: link, attributes: attrs ?? {} }
+
+  const ddSpanContext = normalizeLinkContext(context)
+  if (!ddSpanContext) return
+
+  ddSpan.addLink({ context: ddSpanContext, attributes })
+}
+
+/**
+ * Forwards the array-form `addLinks` overload; non-array inputs are silently ignored to
+ * match the OTel API's lenient handling.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {Array<LinkContextLike | OtelLink>} links
+ */
+function addOtelLinks (ddSpan, links) {
+  if (!isWritable(ddSpan) || !Array.isArray(links)) return
+
+  for (const link of links) {
+    addOtelLink(ddSpan, link)
+  }
+}
+
+/**
+ * Owns the OTel `addEvent(name, attributesOrStartTime, startTime)` overload normalization so
+ * the bridge classes can delegate without touching `Date`/hrTime conversion.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ * @param {Record<string, unknown> | TimeInput | undefined} [attributesOrStartTime]
+ * @param {TimeInput} [startTime]
+ */
+function addOtelEvent (ddSpan, name, attributesOrStartTime, startTime) {
+  if (!isWritable(ddSpan)) return
+
+  const event = normalizeOtelEvent(attributesOrStartTime, startTime)
+  ddSpan.addEvent(name, event.attributes, event.startTime)
+}
+
+/**
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {ExceptionLike} exception
+ * @param {TimeInput} [timeInput]
+ */
+function recordException (ddSpan, exception, timeInput) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.addTags({
+    [ERROR_TYPE]: exception.name,
+    [ERROR_MESSAGE]: exception.message,
+    [ERROR_STACK]: exception.stack,
+    [IGNORE_OTEL_ERROR]: ddSpan.context()._tags[IGNORE_OTEL_ERROR] ?? true,
+  })
+
+  const attributes = {}
+  if (exception.message) attributes['exception.message'] = exception.message
+  if (exception.type) attributes['exception.type'] = exception.type
+  if (exception.escaped) attributes['exception.escaped'] = exception.escaped
+  if (exception.stack) attributes['exception.stacktrace'] = exception.stack
+
+  ddSpan.addEvent(exception.name ?? 'Error', attributes, timeInputToMilliseconds(timeInput))
+}
+
+/**
+ * Applies OTel `setStatus({ code, message })` per spec: UNSET / missing is a no-op, OK is
+ * final, ERROR is replaceable. Only ERROR writes tags; the returned code is the one the
+ * caller must store for the next call.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {number} currentCode 0 = UNSET, 1 = OK, 2 = ERROR.
+ * @param {{ code?: number, message?: string }} [status]
+ * @returns {number} The new status code to track on the caller.
+ */
+function applyOtelStatus (ddSpan, currentCode, status) {
+  if (!isWritable(ddSpan)) return currentCode
+
+  const code = status?.code
+  if (!code || currentCode === 1) return currentCode
+
+  if (code === 2) {
+    ddSpan.addTags({
+      [ERROR_MESSAGE]: status.message,
+      [IGNORE_OTEL_ERROR]: false,
+    })
+  }
+
+  return code
+}
+
+/**
+ * OTel `updateName` for OTel-created bridge spans: writes the DD operation name, matching
+ * the OTel SDK semantic that `updateName` updates the canonical span identifier.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ */
+function setOtelOperationName (ddSpan, name) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.setOperationName(name)
+}
+
+/**
+ * OTel `updateName` for DD-native spans the bridge did not create: writes `resource.name`
+ * so the operation name (and the backend metric aggregation it drives) stays stable.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ */
+function setOtelResource (ddSpan, name) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.setTag('resource.name', name)
+}
+
+module.exports = {
+  addOtelEvent,
+  addOtelLink,
+  addOtelLinks,
+  applyOtelStatus,
+  normalizeLinkContext,
+  recordException,
+  setOtelAttribute,
+  setOtelAttributes,
+  setOtelOperationName,
+  setOtelResource,
+}