dd-trace 5.133.0 → 5.134.0

package/packages/dd-trace/src/aiguard/evaluation.js

@@ -1,10 +1,24 @@
 'use strict'
 
-const { HTTP_CLIENT_IP, HTTP_USERAGENT, NETWORK_CLIENT_IP } = require('../../../../ext/tags')
+const {
+  ERROR,
+  HTTP_CLIENT_IP,
+  HTTP_USERAGENT,
+  MANUAL_DROP,
+  MANUAL_KEEP,
+  NETWORK_CLIENT_IP,
+  RESOURCE_NAME,
+  SAMPLING_PRIORITY,
+  SERVICE_NAME,
+  SPAN_KIND,
+  SPAN_TYPE,
+} = require('../../../../ext/tags')
 const createRfdc = require('../../../../vendor/dist/rfdc')
 const clone = createRfdc({ proto: false, circles: false })
 const { USER_ID, USER_SESSION_ID } = require('../appsec/addresses')
 const { getActiveRequest } = require('../appsec/store')
+const { ERROR_MESSAGE, ERROR_STACK, ERROR_TYPE, PROCESS_ID, SAMPLING_PRIORITY_KEY } = require('../constants')
+const log = require('../log')
 const { keepTrace } = require('../priority_sampler')
 const { extractIp } = require('../plugins/util/ip_extractor')
 const { AI_GUARD } = require('../standalone/product')
@@ -20,6 +34,12 @@ const ALLOW = 'ALLOW'
 /** @typedef {import('../../../../index').aiguard.RedactionReplacement} RedactionReplacement */
 /** @typedef {import('../opentracing/span')} Span */
 
+/**
+ * @typedef {object} ExtraEntry
+ * @property {string} key
+ * @property {unknown} value
+ */
+
 /**
  * @typedef {object} EvaluationResponse
  * @property {string} action
@@ -30,6 +50,8 @@ const ALLOW = 'ALLOW'
  * @property {boolean} hasTagProbabilities
  * @property {boolean} blockingEnabled
  * @property {unknown} redactionReplacements
+ * @property {ExtraEntry[]} extraTags
+ * @property {ExtraEntry[]} extraMetastruct
  */
 
 /**
@@ -40,6 +62,8 @@ const ALLOW = 'ALLOW'
  * @property {boolean} shouldBlock
  * @property {boolean} hasTagProbabilities
  * @property {{ enabled: boolean, applied: boolean, failures: number }} redaction
+ * @property {ExtraEntry[]} extraTags
+ * @property {ExtraEntry[]} extraMetastruct
  */
 
 /**
@@ -68,6 +92,38 @@ function isRecord (value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
+// Shared by every evaluation without extra entries, so the common case allocates nothing.
+const NO_EXTRA_ENTRIES = /** @type {ExtraEntry[]} */ (/** @type {unknown} */ (Object.freeze([])))
+
+/**
+ * Normalizes a backend extra field into well-formed key/value entries. The backend sends lists of
+ * entries rather than objects because the dotted keys are not valid JSON:API member names. Values
+ * are kept as-is: which of them reach the span is decided when they are applied.
+ *
+ * @param {string} field
+ * @param {unknown} entries
+ * @returns {ExtraEntry[]}
+ */
+function normalizeExtraEntries (field, entries) {
+  if (entries === undefined) return NO_EXTRA_ENTRIES
+  if (!Array.isArray(entries)) {
+    log.debug('AI Guard: ignoring %s of type %s', field, entries === null ? 'null' : typeof entries)
+    return NO_EXTRA_ENTRIES
+  }
+
+  const normalized = []
+  for (const entry of entries) {
+    const key = isRecord(entry) ? entry.key : undefined
+    // A __proto__ key is never valid: it cannot become an own property on the span tags or the meta-struct.
+    if (typeof key === 'string' && key.length > 0 && key !== '__proto__') {
+      normalized.push({ key, value: entry.value })
+    } else {
+      log.debug('AI Guard: ignoring malformed %s entry', field)
+    }
+  }
+  return normalized.length === 0 ? NO_EXTRA_ENTRIES : normalized
+}
+
 /**
  * Parses the backend evaluation response into the tracer's internal contract.
  *
@@ -89,6 +145,9 @@ function parseEvaluationResponse (body) {
     hasTagProbabilities: isRecord(attributes.tag_probs),
     blockingEnabled: attributes.is_blocking_enabled === true,
     redactionReplacements: attributes.redaction_replacements,
+    // Malformed extra entries are dropped here instead of turning the response into a bad_response.
+    extraTags: normalizeExtraEntries('extra_tags', attributes.extra_tags),
+    extraMetastruct: normalizeExtraEntries('extra_metastruct', attributes.extra_metastruct),
   }
 }
 
@@ -132,6 +191,8 @@ function createEvaluationOutcome (messages, evaluation, options) {
       applied: redaction.redacted,
       failures: redaction.failures,
     },
+    extraTags: evaluation.extraTags,
+    extraMetastruct: evaluation.extraMetastruct,
   }
 }
 
@@ -147,6 +208,86 @@ const SERVICE_ENTRY_TAG_MAPPINGS = [
   [USER_SESSION_ID, TAGS.USR_SESSION_ID_TAG_KEY],
 ]
 
+// Backend extra tags never override what the tracer computes itself, nor keys that control the
+// span or its trace (sampling, service, resource, error state). Internal _dd keys are covered by
+// isReservedExtraTag instead of being listed here.
+const RESERVED_EXTRA_TAGS = new Set([
+  TAGS.ACTION_TAG_KEY,
+  TAGS.REASON_TAG_KEY,
+  TAGS.TARGET_TAG_KEY,
+  TAGS.TOOL_NAME_TAG_KEY,
+  TAGS.BLOCKED_TAG_KEY,
+  TAGS.REDACTED_TAG_KEY,
+  TAGS.EVENT_TAG_KEY,
+  ...SERVICE_ENTRY_TAG_MAPPINGS.map(([, destinationTag]) => destinationTag),
+  MANUAL_KEEP,
+  MANUAL_DROP,
+  SAMPLING_PRIORITY,
+  SERVICE_NAME,
+  RESOURCE_NAME,
+  SPAN_TYPE,
+  SPAN_KIND,
+  ERROR,
+  ERROR_TYPE,
+  ERROR_MESSAGE,
+  ERROR_STACK,
+  SAMPLING_PRIORITY_KEY,
+  PROCESS_ID,
+  'analytics.event',
+  'language',
+  'runtime-id',
+  'service.version',
+  'version',
+  'env',
+])
+
+/**
+ * Returns whether a backend extra tag key must not be set on the span.
+ *
+ * @param {string} key
+ */
+function isReservedExtraTag (key) {
+  // _dd is the tracer's internal namespace (_dd.*, _dd1.*): the span formatter writes sampling,
+  // top-level and propagation keys there and a span tag with the same key would overwrite them.
+  // This is not an AI Guard namespace filter; the backend owns ai_guard.* keys.
+  return key.startsWith('_dd') || RESERVED_EXTRA_TAGS.has(key)
+}
+
+const RESERVED_EXTRA_META_STRUCT_KEYS = new Set(['messages', 'attack_categories', 'sds', 'tag_probs'])
+
+/**
+ * Copies backend-provided extra_tags to the span and extra_metastruct to the AI Guard meta-struct,
+ * skipping values and keys the span must not receive. Keys are used verbatim and entries are
+ * applied in order, so a repeated key keeps its last value.
+ *
+ * @param {Span} span
+ * @param {EvaluationMetaStruct} metaStruct
+ * @param {ExtraEntry[]} extraTags
+ * @param {ExtraEntry[]} extraMetastruct
+ */
+function applyExtraSpanData (span, metaStruct, extraTags, extraMetastruct) {
+  // The client decodes values with JSON.parse, so a string check and a null check cover every JSON type.
+  for (const { key, value } of extraTags) {
+    if (typeof value !== 'string') {
+      log.debug('AI Guard: ignoring extra_tags entry %s with non-string value', key)
+    } else if (isReservedExtraTag(key)) {
+      log.debug('AI Guard: ignoring reserved extra tag %s', key)
+    } else {
+      span.setTag(key, value)
+    }
+  }
+
+  for (const { key, value } of extraMetastruct) {
+    if (value === undefined || value === null) {
+      log.debug('AI Guard: ignoring extra_metastruct entry %s with null value', key)
+    } else if (RESERVED_EXTRA_META_STRUCT_KEYS.has(key)) {
+      log.debug('AI Guard: ignoring reserved extra_metastruct key %s', key)
+    } else {
+      metaStruct[key] = value
+    }
+  }
+}
+
 class EvaluationReporter {
   #config
   #maxMessagesLength
@@ -230,6 +371,7 @@ class EvaluationReporter {
     if (result.tags.length > 0) report.metaStruct.attack_categories = result.tags
     if (result.sds.length > 0) report.metaStruct.sds = result.sds
     if (outcome.hasTagProbabilities) report.metaStruct.tag_probs = result.tagProbabilities
+    applyExtraSpanData(report.span, report.metaStruct, outcome.extraTags, outcome.extraMetastruct)
 
     if (redaction.enabled) {
       report.span.setTag(TAGS.REDACTED_TAG_KEY, redaction.applied ? 'true' : 'false')

package/packages/dd-trace/src/appsec/iast/path-line.js

@@ -66,7 +66,8 @@ function getCallSiteFramesForLocation (callSiteFrames, externallyExcludedPaths)
 
       if (
         !isExcluded(callsite, externallyExcludedPaths) &&
-        (!filepath.includes(pathLine.ddBasePath) || globalThis.__DD_ESBUILD_IAST_WITH_NO_SM)
+        (pathLine.ddBasePath === undefined || !filepath.includes(pathLine.ddBasePath) ||
+          globalThis.__DD_ESBUILD_IAST_WITH_NO_SM)
       ) {
         clientFrames.push(callsite)
       }

package/packages/dd-trace/src/appsec/stack_trace.js

@@ -34,8 +34,9 @@ function getCallSiteList (maxDepth = 100, constructorOpt) {
 
 function filterOutFramesFromLibrary (callSiteList) {
   return callSiteList.filter(callSite => {
-    if (globalThis.__DD_ESBUILD_IAST_WITH_NO_SM) {
-      // bundled and no SourceMap, not possible to discriminate if the frame comes from dd-trace code or not
+    if (globalThis.__DD_ESBUILD_IAST_WITH_NO_SM || ddBasePath === undefined) {
+      // bundled without a SourceMap, or dd-trace's location is unknown: not possible to discriminate if the frame
+      // comes from dd-trace code or not
       return true
     }
 

package/packages/dd-trace/src/ci-visibility/dynamic-instrumentation/worker/index.js

@@ -228,9 +228,10 @@ async function addBreakpoint (probe) {
   }
 }
 
-function start () {
+async function start () {
+  await session.post('Debugger.enable')
+  // Only flag the session as started once enabled, so the next probe retries a failed start and reports its cause
   sessionStarted = true
-  return session.post('Debugger.enable') // return instead of await to reduce number of promises created
 }
 
 function drainBreakpointHitRequests () {

package/packages/dd-trace/src/config/generated-config-types.d.ts

@@ -439,6 +439,7 @@ export interface GeneratedConfig {
     DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: number;
     DD_FEATURE_FLAGS_ENABLED: boolean;
     DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED: boolean;
+    DD_FEATURE_FLAGS_EXPOSURES_DATADOG_LOGGING_ENABLED: boolean;
     DD_FLAGGING_EVALUATION_COUNTS_ENABLED: boolean;
   };
   flushInterval: number;
@@ -726,6 +727,7 @@ export interface GeneratedEnvVarConfig {
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: number;
   DD_FEATURE_FLAGS_ENABLED: boolean;
   DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED: boolean;
+  DD_FEATURE_FLAGS_EXPOSURES_DATADOG_LOGGING_ENABLED: boolean;
   DD_FLAGGING_EVALUATION_COUNTS_ENABLED: boolean;
   DD_GIT_BRANCH: string | undefined;
   DD_GIT_COMMIT_AUTHOR_DATE: string | undefined;

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

@@ -12,6 +12,7 @@ const uuid = require('../../../../vendor/dist/crypto-randomuuid') // we need to
 const set = require('../../../datadog-core/src/utils/src/set')
 const { DD_MAJOR, NODE_MAJOR } = require('../../../../version')
 const log = require('../log')
+const { warn } = require('../log/writer')
 const pkg = require('../pkg')
 const { isTrue } = require('../util')
 const telemetry = require('../telemetry')
@@ -25,6 +26,7 @@ const {
 const { ORIGIN_KEY, DATADOG_MINI_AGENT_PATH } = require('../constants')
 const { appendRules } = require('../payload-tagging/config')
 const { createSiteUrl } = require('../exporters/common/url')
+const { getUnsupportedRuntime } = require('../debugger/unsupported-runtime')
 const ConfigBase = require('./config-base')
 const {
   getEnvironmentVariable,
@@ -200,6 +202,12 @@ class Config extends ConfigBase {
    */
   #parsedDdTags
 
+  /**
+   * Options already explained as deactivated, so recalculating the config doesn't repeat the explanation
+   * @type {Set<ConfigPath>}
+   */
+  #explainedDeactivations = new Set()
+
   /**
    * @type {Record<string, string>}
    */
@@ -639,6 +647,12 @@ class Config extends ConfigBase {
       setAndTrack(this, 'remoteConfig.DD_REMOTE_CONFIGURATION_ENABLED', false)
     }
 
+    if (this.isCiVisibility) {
+      // Test Optimization reports its metrics through instrumentation telemetry, not DogStatsD.
+      set(this, 'dogstatsd', undefined)
+      setAndTrack(this, 'runtimeMetrics.enabled', false)
+    }
+
     const isTestOptimizationWorker = this.isCiVisibility &&
       TEST_OPTIMIZATION_WORKER_EXPORTERS.has(this.tracing.DD_TRACE_EXPERIMENTAL_EXPORTER)
     if (isTestOptimizationWorker) {
@@ -750,11 +764,42 @@ class Config extends ConfigBase {
       deactivateIfEnabledAndWarnOnWindows(this, 'DD_PROFILING_ASYNC_CONTEXT_FRAME_ENABLED')
     }
 
+    const unsupportedRuntime = getUnsupportedRuntime()
+    if (unsupportedRuntime !== undefined) {
+      this.#deactivateOnUnsupportedRuntime(
+        'dynamicInstrumentation.DD_DYNAMIC_INSTRUMENTATION_ENABLED',
+        `Live Debugger/Dynamic Instrumentation is disabled, because it is not supported on ${unsupportedRuntime}.`
+      )
+      this.#deactivateOnUnsupportedRuntime(
+        'testOptimization.DD_TEST_FAILED_TEST_REPLAY_ENABLED',
+        'Failed Test Replay is disabled, ' +
+          `because Live Debugger/Dynamic Instrumentation is not supported on ${unsupportedRuntime}.`
+      )
+    }
+
     // Single tags update is tracked as a calculated value.
     setAndTrack(this, 'tags', this.tags)
 
     telemetry.updateConfig([...configWithOrigin.values()], this)
   }
+
+  /**
+   * Only explains the deactivation of an option that was explicitly set, since Failed Test Replay is enabled by
+   * default.
+   *
+   * @param {ConfigPath} name
+   * @param {string} reason
+   */
+  #deactivateOnUnsupportedRuntime (name, reason) {
+    if (!get(this, name)) return
+
+    if (this.startupLogs && trackedConfigOrigins.has(name) && !this.#explainedDeactivations.has(name)) {
+      this.#explainedDeactivations.add(name)
+      // `log.warn` only prints with debug logging enabled, so write the diagnostic like the startup logs do
+      warn(`DATADOG TRACER DIAGNOSTIC - ${reason}`)
+    }
+    setAndTrack(this, name, false)
+  }
 }
 
 /**

package/packages/dd-trace/src/config/supported-configurations.json

@@ -1004,6 +1004,15 @@
         "namespace": "featureFlags"
       }
     ],
+    "DD_FEATURE_FLAGS_EXPOSURES_DATADOG_LOGGING_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "true",
+        "description": "Enable Feature Flagging exposure delivery to Datadog independently of flag evaluation and evaluation telemetry.",
+        "namespace": "featureFlags"
+      }
+    ],
     "DD_FLAGGING_EVALUATION_COUNTS_ENABLED": [
       {
         "implementation": "A",

package/packages/dd-trace/src/debugger/devtools_client/breakpoints.js

@@ -103,14 +103,14 @@ async function addBreakpoint (probe) {
       file, lineNumber, columnNumber, probe.id, probe.version
     )
     const position = await getGeneratedPosition(url, source, lineNumber, sourceMapURL)
-    if (position.line !== null && position.column !== null) {
-      lineNumber = position.line
-      columnNumber = position.column
-    } else {
+    if (position.line === null || position.column === null) {
       throw new Error(
         // eslint-disable-next-line @stylistic/max-len
         `Could not find generated position for ${url}:${lineNumber}:${columnNumber} (probe: ${probe.id}, version: ${probe.version})`
       )
+    } else {
+      lineNumber = position.line
+      columnNumber = position.column
     }
   }
 
@@ -357,9 +357,10 @@ async function reEvaluateProbe (probe) {
 }
 
 async function start () {
-  sessionStarted = true
   log.debug('[debugger:devtools_client] Starting debugger')
   await session.post('Debugger.enable')
+  // Only flag the session as started once enabled, so the next probe retries a failed start and reports its cause
+  sessionStarted = true
 
   // Wait until there's a pause in script-loading to avoid accidentally adding probes to incorrect scripts. This is not
   // a guarantee, but best effort.

package/packages/dd-trace/src/debugger/devtools_client/condition.js

@@ -312,9 +312,9 @@ function isInstanceOfCoreType (type, variable, fallback = `${variable} instanceo
 function getSize (variable) {
   return `((val) => {
     if (${isString('val')} || ${isArrayOrTypedArray('val')}) {
-      return ${guardAgainstPropertyAccessSideEffects('val', '"length"')}
+      return ${guardAgainstPropertyAccessSideEffects('"length"')}
     } else if (${isInstanceOfCoreType('Set', 'val')} || ${isInstanceOfCoreType('Map', 'val')}) {
-      return ${guardAgainstPropertyAccessSideEffects('val', '"size"')}
+      return ${guardAgainstPropertyAccessSideEffects('"size"')}
     } else if (${isInstanceOfCoreType('WeakSet', 'val')} || ${isInstanceOfCoreType('WeakMap', 'val')}) {
       throw new TypeError('Cannot get size of WeakSet or WeakMap')
     } else if (typeof val === 'object' && val !== null) {
@@ -338,12 +338,12 @@ function accessProperty (variable, keyOrIndex, allowMapAccess) {
     } else if (${isInstanceOfCoreType('Set', 'val')} || ${isInstanceOfCoreType('WeakSet', 'val')}) {
       throw new Error('Accessing a Set or WeakSet is not allowed')
     } else {
-      return ${guardAgainstPropertyAccessSideEffects('val', 'key')}
+      return ${guardAgainstPropertyAccessSideEffects('key')}
     }
   })(${variable}, ${keyOrIndex})`
 }
 
-function guardAgainstPropertyAccessSideEffects (variable, propertyName) {
+function guardAgainstPropertyAccessSideEffects (propertyName) {
   return `((val, key) => {
     if (
       ${isInstanceOfCoreType('Proxy', 'val', 'true')} ||
@@ -353,7 +353,7 @@ function guardAgainstPropertyAccessSideEffects (variable, propertyName) {
     } else {
       return val[key]
     }
-  })(${variable}, ${propertyName})`
+  })(val, ${propertyName})`
 }
 
 function guardAgainstCoercionSideEffects (variable) {

package/packages/dd-trace/src/debugger/devtools_client/snapshot/collector.js

@@ -126,8 +126,8 @@ async function traverseGetPropertiesResult (props, opts, depth) {
     if (prop.value === undefined) continue
     const { value: { type, objectId, subtype, description } } = prop
     if (type === 'object') {
-      if (objectId === undefined) continue // if `subtype` is "null"
-      if (LEAF_SUBTYPES.has(subtype)) continue // don't waste time with these subtypes
+      // if `subtype` is "null"
+      if (objectId === undefined || LEAF_SUBTYPES.has(subtype)) continue // don't waste time with these subtypes
       const size = parseLengthFromDescription(description, subtype)
       if (size !== null && size >= LARGE_OBJECT_SKIP_THRESHOLD) {
         const empty = []
@@ -310,8 +310,7 @@ function removeNonEnumerableProperties (props) {
 }
 
 function parseLengthFromDescription (description, subtype) {
-  if (typeof description !== 'string') return null
-  if (!SIZE_IN_DESCRIPTION_SUBTYPES.has(subtype)) return null
+  if (typeof description !== 'string' || !SIZE_IN_DESCRIPTION_SUBTYPES.has(subtype)) return null
 
   const open = description.lastIndexOf('(')
   if (open === -1) return null
@@ -323,8 +322,7 @@ function parseLengthFromDescription (description, subtype) {
   if (s === '') return null
 
   const n = Number(s)
-  if (!Number.isSafeInteger(n) || n < 0) return null
-  if (String(n) !== s) return null
+  if (!Number.isSafeInteger(n) || n < 0 || String(n) !== s) return null
 
   return n
 }

package/packages/dd-trace/src/debugger/unsupported-runtime.js

@@ -0,0 +1,16 @@
+'use strict'
+
+/**
+ * Get the name of the runtime if it can't run Live Debugger/Dynamic Instrumentation, or `undefined` if it can.
+ *
+ * Live Debugger/Dynamic Instrumentation needs the Debugger domain of the `node:inspector` module. Bun only implements a
+ * few of its methods, never returns their results, and never emits its events. Deno doesn't let worker threads
+ * connect to the main thread inspector. Deno reports a Node.js `process.version`, so both runtimes are detected by
+ * their own `process.versions` entry instead.
+ */
+function getUnsupportedRuntime () {
+  if (process.versions.bun !== undefined) return 'Bun'
+  if (process.versions.deno !== undefined) return 'Deno'
+}
+
+module.exports = { getUnsupportedRuntime }

package/packages/dd-trace/src/llmobs/agent-manifest.js

@@ -35,7 +35,7 @@ const LABEL_FIELDS = ['name', 'instructions', 'model']
  *   model_settings?: Record<string, unknown>,
  *   tools?: AgentTool[],
  * }} AgentManifestFields
- * @typedef {{ manifest: AgentManifestFields }} AgentDeclaration
+ * @typedef {{ version?: string, manifest?: AgentManifestFields }} AgentDeclaration
  */
 
 /**
@@ -50,8 +50,9 @@ function buildAgentDeclaration (agent) {
   let declaration
   try {
     if (isPlainObject(agent)) {
+      const version = toAgentVersion(agent.version)
       const manifest = buildAgentManifest(agent)
-      if (manifest !== undefined) declaration = { manifest }
+      if (version !== undefined || manifest !== undefined) declaration = { version, manifest }
     } else {
       log.warn('Dropping agent annotation, the agent must be a plain object.')
     }
@@ -105,6 +106,21 @@ function buildAgentManifest (agent) {
   return manifest
 }
 
+/**
+ * Unset values (`undefined`, `null`, `''`) are ignored without a warning, so they leave an earlier version in place.
+ * A comma is rejected because intake splits tags on it.
+ *
+ * @param {unknown} version
+ */
+function toAgentVersion (version) {
+  if (typeof version === 'string' && version !== '') {
+    if (!version.includes(',')) return version
+    log.warn('Dropping the agent version, it must not contain a comma.')
+    return
+  }
+  if (!isUnset(version)) log.warn('Dropping the agent version, it must be a string.')
+}
+
 /**
  * @param {unknown} settings
  * @param {string[]} dropped
@@ -293,4 +309,5 @@ function isScalar (value) {
 module.exports = {
   MANUAL_FRAMEWORK_NAME,
   buildAgentDeclaration,
+  toAgentVersion,
 }

package/packages/dd-trace/src/llmobs/constants/tags.js

@@ -23,6 +23,8 @@ module.exports = {
   METADATA: '_ml_obs.meta.metadata',
   COST_TAGS: '_ml_obs.meta.metadata._dd.cost_tags',
   AGENT_MANIFEST: '_ml_obs.meta.metadata._dd.agent_manifest',
+  AGENT_VERSION: '_ml_obs.agent_version',
+  AGENT_VERSION_TAG_KEY: 'agent_version',
   METRICS: '_ml_obs.metrics',
   TOOL_DEFINITIONS: '_ml_obs.meta.tool_definitions',
   ML_APP: '_ml_obs.meta.ml_app',
@@ -33,6 +35,7 @@ module.exports = {
 
   PARENT_AGENT_NAME: '_ml_obs.parent_agent_name',
   PARENT_AGENT_SPAN_ID: '_ml_obs.parent_agent_span_id',
+  PARENT_AGENT_VERSION: '_ml_obs.parent_agent_version',
   PROPAGATED_PARENT_AGENT_ID_KEY: '_dd.p.llmobs_pagent_span_id',
   PROPAGATED_PARENT_AGENT_NAME_KEY: '_dd.p.llmobs_pagent_name',
   PROPAGATED_SAMPLE_RATE_KEY: '_dd.p.llmobs_sr',

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

@@ -12,6 +12,9 @@ const AUDIO_MIME_TYPES = {
   mp3: 'audio/mpeg',
 }
 
+const DECISION_PROVIDER_TAG = 'decision_provider'
+const DECISION_PROVIDER = 'openai'
+
 module.exports = {
   INPUT_TYPE_IMAGE,
   INPUT_TYPE_FILE,
@@ -19,4 +22,6 @@ module.exports = {
   IMAGE_FALLBACK,
   FILE_FALLBACK,
   AUDIO_MIME_TYPES,
+  DECISION_PROVIDER_TAG,
+  DECISION_PROVIDER,
 }

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

@@ -8,7 +8,13 @@ const {
 } = require('../../constants/tags')
 const { audioMimeTypeFromFormat, formatAudioPart } = require('../../audio-utils')
 const { safeJsonParse } = require('../../util')
-const { AUDIO_MIME_TYPES, IMAGE_FALLBACK, INPUT_TYPE_IMAGE } = require('./constants')
+const {
+  AUDIO_MIME_TYPES,
+  DECISION_PROVIDER,
+  DECISION_PROVIDER_TAG,
+  IMAGE_FALLBACK,
+  INPUT_TYPE_IMAGE,
+} = require('./constants')
 const {
   extractChatTemplateFromInstructions,
   normalizePromptVariables,
@@ -479,6 +485,8 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
   }
 
   #tagDecision (span, inputs, response, error) {
+    this._tagger.tagSpanTags(span, { [DECISION_PROVIDER_TAG]: DECISION_PROVIDER })
+
     const { input, questions } = inputs
 
     const inputMessages = typeof input === 'string'

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

@@ -29,7 +29,7 @@ const {
   getFunctionArguments,
   validateKind,
 } = require('./util')
-const { buildAgentDeclaration } = require('./agent-manifest')
+const { buildAgentDeclaration, toAgentVersion } = require('./agent-manifest')
 /** @typedef {import('./agent-manifest').AgentDeclaration} AgentDeclaration */
 const { storage } = require('./storage')
 const telemetry = require('./telemetry')
@@ -163,7 +163,7 @@ class LLMObs extends NoopLLMObs {
     const {
       spanOptions,
       ...llmobsOptions
-    } = this.#extractOptions(options)
+    } = this.#extractOptions(options, kind)
 
     if (fn.length > 1) {
       return this._tracer.trace(name, spanOptions, (span, cb) =>
@@ -193,7 +193,7 @@ class LLMObs extends NoopLLMObs {
     const {
       spanOptions,
       ...llmobsOptions
-    } = this.#extractOptions(options)
+    } = this.#extractOptions(options, kind)
 
     const llmobs = this
 
@@ -719,21 +719,32 @@ class LLMObs extends NoopLLMObs {
     }
   }
 
-  #extractOptions (options) {
+  #extractOptions (options, kind) {
     const {
       modelName,
       modelProvider,
       sessionId,
       mlApp,
+      version,
       _decorator,
       ...spanOptions
     } = options
 
+    let agentVersion
+    if (version !== undefined) {
+      if (kind === 'agent') {
+        agentVersion = toAgentVersion(version)
+      } else {
+        logger.warn('Dropping the version option on a %s span, it is only supported for agent spans.', kind)
+      }
+    }
+
     return {
       mlApp,
       modelName,
       modelProvider,
       sessionId,
+      agentVersion,
       _decorator,
       spanOptions,
     }