dd-trace 6.9.0 → 6.10.0

package/packages/dd-trace/src/carrier.js

@@ -0,0 +1,356 @@
+'use strict'
+
+/** @typedef {Record<string, unknown>} Carrier */
+/** @typedef {string | Buffer} PathwayValue */
+
+const FIELD_READ = 1
+const FIELD_WRITE = 2
+const FIELD_HAS = 4
+const FIELD_DELETE = 8
+const FIELD_NAME_LENGTH = 16
+
+/** @type {Record<string, unknown>} */
+const carrierOperations = {}
+
+/**
+ * @typedef {object} CarrierCapability
+ * @property {unknown} [read]
+ * @property {unknown} [write]
+ * @property {unknown} [has]
+ * @property {unknown} [delete]
+ * @property {unknown} [nameLength]
+ */
+
+/**
+ * @template Value
+ * @typedef {object} CarrierField
+ * @property {(carrier: Carrier) => Value | undefined} read
+ * @property {(carrier: Carrier, value: Value) => void} write
+ * @property {(carrier: Carrier) => boolean} has
+ * @property {(carrier: Carrier) => void} delete
+ * @property {(carrier: Carrier, target: Carrier) => void} copy
+ * @property {number} nameLength
+ */
+
+/**
+ * @template {CarrierCapability} Capability
+ * @param {string} name
+ * @param {number} operations
+ * @param {Capability} capability
+ * @returns {Capability}
+ */
+function defineCapability (name, operations, capability) {
+  const suffix = name[0].toUpperCase() + name.slice(1)
+  if (operations & FIELD_READ) carrierOperations[`read${suffix}`] = capability.read
+  if (operations & FIELD_WRITE) carrierOperations[`write${suffix}`] = capability.write
+  if (operations & FIELD_HAS) carrierOperations[`has${suffix}`] = capability.has
+  if (operations & FIELD_DELETE) carrierOperations[`delete${suffix}`] = capability.delete
+  if (operations & FIELD_NAME_LENGTH) carrierOperations[`${name}NameLength`] = capability.nameLength
+  return capability
+}
+
+/**
+ * @template Value
+ * @param {string} fieldName
+ * @param {string} headerName
+ * @param {(value: unknown) => Value | undefined} resolve
+ * @param {number} operations
+ * @returns {CarrierField<Value>}
+ */
+function defineField (fieldName, headerName, resolve, operations) {
+  return defineCapability(fieldName, operations, {
+    /**
+     * @param {Carrier} carrier
+     * @returns {Value | undefined}
+     */
+    read (carrier) {
+      return resolve(carrier[headerName])
+    },
+
+    /**
+     * @param {Carrier} carrier
+     * @param {Value} value
+     * @returns {void}
+     */
+    write (carrier, value) {
+      carrier[headerName] = value
+    },
+
+    /**
+     * @param {Carrier} carrier
+     * @returns {boolean}
+     */
+    has (carrier) {
+      return headerName in carrier
+    },
+
+    /**
+     * @param {Carrier} carrier
+     * @returns {void}
+     */
+    delete (carrier) {
+      delete carrier[headerName]
+    },
+
+    /**
+     * @param {Carrier} carrier
+     * @param {Carrier} target
+     * @returns {void}
+     */
+    copy (carrier, target) {
+      if (Object.hasOwn(carrier, headerName)) target[headerName] = carrier[headerName]
+    },
+
+    nameLength: headerName.length,
+  })
+}
+
+/**
+ * Skipping non-strings keeps a Symbol or a throwing `toString` from aborting
+ * extraction, which discards the whole context rather than one field.
+ *
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function readListText (value) {
+  if (typeof value === 'string') return value
+  if (!Array.isArray(value)) return
+
+  let joined = ''
+  let first = true
+
+  for (const item of value) {
+    if (typeof item !== 'string') continue
+    if (first) {
+      joined = item
+      first = false
+    } else {
+      joined += `,${item}`
+    }
+  }
+
+  return joined
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function readLastText (value) {
+  if (typeof value === 'string') return value
+  if (!Array.isArray(value)) return
+
+  let result
+  for (let i = value.length - 1; i >= 0; i--) {
+    if (typeof value[i] === 'string') {
+      result = value[i]
+      break
+    }
+  }
+  return result
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function readUniqueText (value) {
+  let result
+  if (typeof value === 'string') {
+    result = value
+  } else if (Array.isArray(value) && value.length === 1 && typeof value[0] === 'string') {
+    result = value[0]
+  }
+  return result
+}
+
+/**
+ * @param {unknown} value
+ * @returns {PathwayValue | undefined}
+ */
+function readLastPathway (value) {
+  if (typeof value === 'string' || Buffer.isBuffer(value)) return value
+  if (!Array.isArray(value)) return
+
+  let result
+  for (let i = value.length - 1; i >= 0; i--) {
+    const item = value[i]
+    if (typeof item === 'string' || Buffer.isBuffer(item)) {
+      result = item
+      break
+    }
+  }
+  return result
+}
+
+const datadogTraceId = defineField(
+  'datadogTraceId',
+  'x-datadog-trace-id',
+  readLastText,
+  FIELD_READ | FIELD_WRITE
+)
+const datadogParentId = defineField(
+  'datadogParentId',
+  'x-datadog-parent-id',
+  readLastText,
+  FIELD_READ | FIELD_WRITE | FIELD_DELETE
+)
+const datadogOrigin = defineField(
+  'datadogOrigin',
+  'x-datadog-origin',
+  readLastText,
+  FIELD_READ | FIELD_WRITE
+)
+const datadogSamplingPriority = defineField(
+  'datadogSamplingPriority',
+  'x-datadog-sampling-priority',
+  readLastText,
+  FIELD_READ | FIELD_WRITE
+)
+defineField('datadogTags', 'x-datadog-tags', readListText, FIELD_READ | FIELD_WRITE)
+defineField('baggage', 'baggage', readListText, FIELD_READ | FIELD_WRITE)
+const b3TraceId = defineField('b3TraceId', 'x-b3-traceid', readLastText, FIELD_READ | FIELD_WRITE)
+const b3SpanId = defineField('b3SpanId', 'x-b3-spanid', readLastText, FIELD_READ | FIELD_WRITE)
+const b3ParentId = defineField('b3ParentId', 'x-b3-parentspanid', readLastText, FIELD_WRITE)
+const b3Sampled = defineField('b3Sampled', 'x-b3-sampled', readLastText, FIELD_READ | FIELD_WRITE)
+const b3Flags = defineField('b3Flags', 'x-b3-flags', readLastText, FIELD_READ | FIELD_WRITE)
+const b3 = defineField('b3', 'b3', readLastText, FIELD_READ | FIELD_WRITE)
+defineField('sqsd', 'x-aws-sqsd-attr-_datadog', readLastText, FIELD_READ)
+const traceparent = defineField('traceparent', 'traceparent', readUniqueText, FIELD_READ | FIELD_WRITE)
+const tracestate = defineField('tracestate', 'tracestate', readListText, FIELD_READ | FIELD_WRITE)
+const dsmBase64 = defineField(
+  'dsmBase64',
+  'dd-pathway-ctx-base64',
+  readLastPathway,
+  FIELD_READ | FIELD_WRITE | FIELD_HAS | FIELD_NAME_LENGTH
+)
+const dsmBinary = defineField('dsmBinary', 'dd-pathway-ctx', readLastPathway, FIELD_READ | FIELD_HAS)
+
+const legacyBaggagePrefix = 'ot-baggage-'
+// RFC 7230 `token`, compatible with Node.js header-name validation.
+const httpHeaderNameExpr = /^[0-9A-Za-z!#$%&'*+\-.^_`|~]+$/
+
+defineCapability('legacyBaggage', FIELD_READ | FIELD_WRITE, {
+  /**
+   * @param {Record<string, string> | undefined} carrier
+   * @param {string} key
+   * @param {string} value
+   * @returns {Record<string, string> | undefined}
+   */
+  write (carrier, key, value) {
+    const name = legacyBaggagePrefix + key
+    if (!httpHeaderNameExpr.test(name)) return
+
+    carrier ??= {}
+    carrier[name] = value
+    return carrier
+  },
+
+  /**
+   * @param {Carrier} carrier
+   * @param {Record<string, string>} target
+   * @returns {void}
+   */
+  read (carrier, target) {
+    for (const name of Object.keys(carrier)) {
+      if (!name.startsWith(legacyBaggagePrefix)) continue
+      const key = name.slice(legacyBaggagePrefix.length)
+      if (!key) continue
+      const value = readLastText(carrier[name])
+      if (value !== undefined) target[key] = value
+    }
+  },
+})
+
+const textMapLogFields = [
+  datadogTraceId,
+  datadogParentId,
+  datadogSamplingPriority,
+  datadogOrigin,
+  b3TraceId,
+  b3SpanId,
+  b3ParentId,
+  b3Sampled,
+  b3Flags,
+  b3,
+  traceparent,
+  tracestate,
+]
+const dsmLogFields = [dsmBinary, dsmBase64]
+
+/**
+ * @param {Carrier} carrier
+ * @param {Array<Pick<CarrierField<unknown>, 'copy'>>} selectedFields
+ * @returns {Carrier}
+ */
+function pick (carrier, selectedFields) {
+  /** @type {Carrier} */
+  const result = {}
+  for (const field of selectedFields) field.copy(carrier, result)
+  return result
+}
+
+/**
+ * @param {Carrier} carrier
+ * @returns {Carrier}
+ */
+function pickTextMap (carrier) {
+  return pick(carrier, textMapLogFields)
+}
+
+/**
+ * @param {Carrier} carrier
+ * @returns {Carrier}
+ */
+function pickDsm (carrier) {
+  return pick(carrier, dsmLogFields)
+}
+
+/**
+ * @typedef {object} CarrierOperations
+ * @property {typeof datadogParentId.delete} deleteDatadogParentId
+ * @property {typeof dsmBase64.nameLength} dsmBase64NameLength
+ * @property {typeof dsmBase64.has} hasDsmBase64
+ * @property {typeof dsmBinary.has} hasDsmBinary
+ * @property {typeof pickDsm} pickDsm
+ * @property {typeof pickTextMap} pickTextMap
+ * @property {(carrier: Carrier) => string | undefined} readBaggage
+ * @property {typeof b3.read} readB3
+ * @property {typeof b3Flags.read} readB3Flags
+ * @property {typeof b3Sampled.read} readB3Sampled
+ * @property {typeof b3SpanId.read} readB3SpanId
+ * @property {typeof b3TraceId.read} readB3TraceId
+ * @property {typeof datadogOrigin.read} readDatadogOrigin
+ * @property {typeof datadogParentId.read} readDatadogParentId
+ * @property {typeof datadogSamplingPriority.read} readDatadogSamplingPriority
+ * @property {(carrier: Carrier) => string | undefined} readDatadogTags
+ * @property {typeof datadogTraceId.read} readDatadogTraceId
+ * @property {typeof dsmBase64.read} readDsmBase64
+ * @property {typeof dsmBinary.read} readDsmBinary
+ * @property {(carrier: Carrier, target: Record<string, string>) => void} readLegacyBaggage
+ * @property {(carrier: Carrier) => string | undefined} readSqsd
+ * @property {typeof traceparent.read} readTraceparent
+ * @property {typeof tracestate.read} readTracestate
+ * @property {(carrier: Carrier, value: string) => void} writeBaggage
+ * @property {typeof b3.write} writeB3
+ * @property {typeof b3Flags.write} writeB3Flags
+ * @property {typeof b3ParentId.write} writeB3ParentId
+ * @property {typeof b3Sampled.write} writeB3Sampled
+ * @property {typeof b3SpanId.write} writeB3SpanId
+ * @property {typeof b3TraceId.write} writeB3TraceId
+ * @property {typeof datadogOrigin.write} writeDatadogOrigin
+ * @property {typeof datadogParentId.write} writeDatadogParentId
+ * @property {typeof datadogSamplingPriority.write} writeDatadogSamplingPriority
+ * @property {(carrier: Carrier, value: string) => void} writeDatadogTags
+ * @property {typeof datadogTraceId.write} writeDatadogTraceId
+ * @property {typeof dsmBase64.write} writeDsmBase64
+ * @property {(carrier: Record<string, string> | undefined, key: string, value: string) =>
+ *   Record<string, string> | undefined} writeLegacyBaggage
+ * @property {typeof traceparent.write} writeTraceparent
+ * @property {typeof tracestate.write} writeTracestate
+ */
+
+carrierOperations.pickDsm = pickDsm
+carrierOperations.pickTextMap = pickTextMap
+
+module.exports = /** @type {CarrierOperations} */ (carrierOperations)

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

@@ -272,6 +272,7 @@ export interface GeneratedConfig {
   DD_TRACE_HAPI_HAPI_ENABLED: boolean;
   DD_TRACE_HONO_ENABLED: boolean;
   DD_TRACE_HTTP_ENABLED: boolean;
+  DD_TRACE_HTTP_SERVER_ERROR_STATUSES: string;
   DD_TRACE_HTTP2_ENABLED: boolean;
   DD_TRACE_HTTPS_ENABLED: boolean;
   DD_TRACE_IOREDIS_ENABLED: boolean;
@@ -727,6 +728,7 @@ export interface GeneratedEnvVarConfig {
   DD_HEAP_SNAPSHOT_COUNT: number;
   DD_HEAP_SNAPSHOT_DESTINATION: string;
   DD_HEAP_SNAPSHOT_INTERVAL: number;
+  DD_HTTP_SERVER_ERROR_STATUSES: string;
   DD_IAST_DB_ROWS_TO_TAINT: number;
   DD_IAST_DEDUPLICATION_ENABLED: boolean;
   DD_IAST_ENABLED: boolean;
@@ -966,6 +968,7 @@ export interface GeneratedEnvVarConfig {
   DD_TRACE_HEADER_TAGS: string[];
   DD_TRACE_HONO_ENABLED: boolean;
   DD_TRACE_HTTP_ENABLED: boolean;
+  DD_TRACE_HTTP_SERVER_ERROR_STATUSES: string;
   DD_TRACE_HTTP2_ENABLED: boolean;
   DD_TRACE_HTTPS_ENABLED: boolean;
   DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED: boolean;

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

@@ -2999,6 +2999,16 @@
         "default": "true"
       }
     ],
+    "DD_TRACE_HTTP_SERVER_ERROR_STATUSES": [
+      {
+        "implementation": "A",
+        "type": "string",
+        "default": "500-599",
+        "aliases": [
+          "DD_HTTP_SERVER_ERROR_STATUSES"
+        ]
+      }
+    ],
     "DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED": [
       {
         "implementation": "A",

package/packages/dd-trace/src/datastreams/context.js

@@ -13,7 +13,12 @@ function getDataStreamsContext () {
 function setDataStreamsContext (dataStreamsContext) {
   log.debug('Setting new DSM Context: %j.', dataStreamsContext)
 
-  if (dataStreamsContext) legacyStorage.enterWith({ ...legacyStorage.getStore(), dataStreamsContext })
+  // `undefined` clears: a message that carries no context must not inherit the previous message's.
+  // The identity check keeps the common no-context case from allocating a store per message.
+  const store = legacyStorage.getStore()
+  if (store?.dataStreamsContext !== dataStreamsContext) {
+    legacyStorage.enterWith({ ...store, dataStreamsContext })
+  }
 }
 
 module.exports = {

package/packages/dd-trace/src/datastreams/manager.js

@@ -16,9 +16,13 @@ class DataStreamsManager {
     return ctx
   }
 
+  /**
+   * @param {Record<string, string>|undefined} carrier Pass every message's carrier, including the
+   *   ones without a context: that is what starts a new pathway instead of extending the previous
+   *   message's.
+   */
   decodeDataStreamsContext (carrier) {
     const ctx = DsmPathwayCodec.decode(carrier)
-    // we erase the previous context everytime we decode a new one
     DataStreamsContext.setDataStreamsContext(ctx)
     return ctx
   }

package/packages/dd-trace/src/datastreams/pathway.js

@@ -5,23 +5,25 @@
 // this inconsistency is ok because hashes do not need to be consistent across services
 const crypto = require('crypto')
 const { LRUCache } = require('../../../../vendor/dist/lru-cache')
+const {
+  hasDsmBase64,
+  hasDsmBinary,
+  pickDsm,
+  readDsmBase64,
+  readDsmBinary,
+  writeDsmBase64,
+} = require('../carrier')
 const log = require('../log')
-const pick = require('../../../datadog-core/src/utils/src/pick')
 const { encodeVarintInto, decodeVarint } = require('./encoding')
 
 const cache = new LRUCache({ max: 500 })
 
-const CONTEXT_PROPAGATION_KEY = 'dd-pathway-ctx'
-const CONTEXT_PROPAGATION_KEY_BASE64 = 'dd-pathway-ctx-base64'
-
 const PATHWAY_CONTEXT_BYTES = 20
 
 // Reused across `encodePathwayContext` calls; the buffer is fully rewritten before each
 // `Buffer.from(...)` copy-out so callers never observe mutation between checkpoints.
 const pathwayScratch = Buffer.allocUnsafe(PATHWAY_CONTEXT_BYTES)
 
-const logKeys = [CONTEXT_PROPAGATION_KEY, CONTEXT_PROPAGATION_KEY_BASE64]
-
 function shaHash (checkpointString) {
   // Copy out of the 32-byte digest so the LRU cache doesn't retain it.
   return Buffer.from(crypto.createHash('sha256').update(checkpointString).digest().subarray(0, 8))
@@ -114,7 +116,7 @@ function decodePathwayContext (pathwayContext) {
 }
 
 /**
- * @param {string} pathwayContext
+ * @param {string | Buffer} pathwayContext
  * @returns {ReturnType<typeof decodePathwayContext>|undefined}
  */
 function decodePathwayContextBase64 (pathwayContext) {
@@ -142,10 +144,10 @@ const DsmPathwayCodec = {
   encode (dataStreamsContext, carrier) {
     if (!dataStreamsContext || !dataStreamsContext.hash) return
     carrier ??= {}
-    carrier[CONTEXT_PROPAGATION_KEY_BASE64] = encodePathwayContextBase64(dataStreamsContext)
+    writeDsmBase64(carrier, encodePathwayContextBase64(dataStreamsContext))
 
     // eslint-disable-next-line eslint-rules/eslint-log-printf-style
-    log.debug(() => `Injected into DSM carrier: ${JSON.stringify(pick(carrier, logKeys))}.`)
+    log.debug(() => `Injected into DSM carrier: ${JSON.stringify(pickDsm(carrier))}.`)
 
     return carrier
   },
@@ -155,25 +157,25 @@ const DsmPathwayCodec = {
    * @returns {ReturnType<typeof decodePathwayContext>|undefined}
    */
   decode (carrier) {
-    // eslint-disable-next-line eslint-rules/eslint-log-printf-style
-    log.debug(() => `Attempting extract from DSM carrier: ${JSON.stringify(pick(carrier, logKeys))}.`)
-
     if (carrier == null) return
 
+    // eslint-disable-next-line eslint-rules/eslint-log-printf-style
+    log.debug(() => `Attempting extract from DSM carrier: ${JSON.stringify(pickDsm(carrier))}.`)
+
     let ctx
-    if (CONTEXT_PROPAGATION_KEY_BASE64 in carrier) {
+    if (hasDsmBase64(carrier)) {
       // decode v2 encoding of base64
-      ctx = decodePathwayContextBase64(carrier[CONTEXT_PROPAGATION_KEY_BASE64])
-    } else if (CONTEXT_PROPAGATION_KEY in carrier) {
-      try {
+      const encoded = readDsmBase64(carrier)
+      if (encoded !== undefined) ctx = decodePathwayContextBase64(encoded)
+    } else if (hasDsmBinary(carrier)) {
+      const encoded = readDsmBinary(carrier)
+      if (Buffer.isBuffer(encoded)) {
         // decode v1 encoding
-        ctx = decodePathwayContext(carrier[CONTEXT_PROPAGATION_KEY])
-      } catch {
-        // pass
+        ctx = decodePathwayContext(encoded)
       }
       // cover case where base64 context was received under wrong key
-      if (!ctx && CONTEXT_PROPAGATION_KEY in carrier) {
-        ctx = decodePathwayContextBase64(carrier[CONTEXT_PROPAGATION_KEY])
+      if (!ctx && encoded !== undefined) {
+        ctx = decodePathwayContextBase64(encoded)
       }
     }
 
@@ -182,7 +184,6 @@ const DsmPathwayCodec = {
 }
 
 module.exports = {
-  CONTEXT_PROPAGATION_KEY_BASE64,
   computePathwayHash: computeHash,
   encodePathwayContext,
   decodePathwayContext,

package/packages/dd-trace/src/datastreams/processor.js

@@ -5,10 +5,11 @@ const pkg = require('../../../../package.json')
 
 const { LogCollapsingLowestDenseDDSketch } = require('../../../../vendor/dist/@datadog/sketches-js')
 const { PATHWAY_HASH, DSM_TRANSACTION_ID, DSM_TRANSACTION_CHECKPOINT } = require('../../../../ext/tags')
+const { dsmBase64NameLength } = require('../carrier')
 const log = require('../log')
 const processTags = require('../process-tags')
 const propagationHash = require('../propagation-hash')
-const { CONTEXT_PROPAGATION_KEY_BASE64, computePathwayHash } = require('./pathway')
+const { computePathwayHash } = require('./pathway')
 const { DataStreamsWriter } = require('./writer')
 const { getAmqpMessageSize, getHeadersSize, getMessageSize, getSizeOrZero } = require('./size')
 const { SchemaBuilder } = require('./schemas/schema_builder')
@@ -21,7 +22,7 @@ const ENTRY_PARENT_HASH = Buffer.from('0000000000000000', 'hex')
 // bytes, encoded as 28 base64 chars; together with the header key and
 // JSON framing (matching the prior `JSON.stringify({key: value})` byte
 // count minus 1), this is a fixed value.
-const PATHWAY_HEADER_BYTES = CONTEXT_PROPAGATION_KEY_BASE64.length + 28 + 6
+const PATHWAY_HEADER_BYTES = dsmBase64NameLength + 28 + 6
 
 class StatsPoint {
   constructor (hash, parentHash, edgeTags) {

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

@@ -16,6 +16,11 @@ module.exports = {
   PROPAGATED_ML_APP_KEY: '_dd.p.llmobs_ml_app',
   PROPAGATED_SESSION_ID_KEY: '_dd.p.llmobs_sid',
   PARENT_ID_KEY: '_ml_obs.llmobs_parent_id',
+
+  PARENT_AGENT_NAME: '_ml_obs.parent_agent_name',
+  PARENT_AGENT_SPAN_ID: '_ml_obs.parent_agent_span_id',
+  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',
   PROPAGATED_SAMPLING_DECISION_KEY: '_dd.p.llmobs_sd',
   SAMPLE_RATE: '_ml_obs.sample_rate',

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

@@ -2,6 +2,7 @@
 
 const { channel } = require('dc-polyfill')
 
+const { readDatadogTags, writeDatadogTags } = require('../carrier')
 const log = require('../log')
 const { DD_MAJOR } = require('../../../../version')
 const startupLogs = require('../startup-log')
@@ -12,6 +13,8 @@ const {
   PROPAGATED_ML_APP_KEY,
   PROPAGATED_PARENT_ID_KEY,
   PROPAGATED_SESSION_ID_KEY,
+  PROPAGATED_PARENT_AGENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_NAME_KEY,
   SAMPLE_RATE,
   SAMPLING_DECISION,
   PROPAGATED_SAMPLE_RATE_KEY,
@@ -20,6 +23,7 @@ const {
   PROPAGATED_TRACE_ID_KEY,
 } = require('./constants/tags')
 const { storage } = require('./storage')
+const { agentNameWireSafe, appendOptionalPropagatedTag, resolveAgentAttribution, stripTagsetEntry } = require('./util')
 const telemetry = require('./telemetry')
 const LLMObsSpanProcessor = require('./span_processor')
 const LLMObsEvalMetricsWriter = require('./writers/evaluations')
@@ -147,9 +151,17 @@ function handleLLMObsInjection ({ carrier }) {
 
   if (!parentId && !mlApp && samplingDecision == null && !sessionId && !propagatedTraceId) return
 
+  // Propagate the nearest agent so spans in the downstream process attribute correctly. When the
+  // active span sits under a distributed agent, `resolveAgentAttribution` inherits the propagated
+  // id/name already on the parent's registry entry, so the chain survives multiple hops. Resolved
+  // after the bail-out above so we don't allocate when there is nothing to inject.
+  const { name: parentAgentName, spanId: parentAgentSpanId } = resolveAgentAttribution(
+    mlObsSpanTags, parent
+  )
+
   // `_injectTags` only writes `x-datadog-tags` when the trace has `_dd.p.*`
   // tags, so it may be undefined here — coalesce before appending.
-  const existing = carrier['x-datadog-tags']
+  const existing = readDatadogTags(carrier)
   let tags = existing || ''
   if (parentId) tags += `${tags ? ',' : ''}${PROPAGATED_PARENT_ID_KEY}=${parentId}`
   if (mlApp) tags += `${tags ? ',' : ''}${PROPAGATED_ML_APP_KEY}=${mlApp}`
@@ -157,7 +169,27 @@ function handleLLMObsInjection ({ carrier }) {
   if (sampleRate != null) tags += `${tags ? ',' : ''}${PROPAGATED_SAMPLE_RATE_KEY}=${sampleRate}`
   if (samplingDecision != null) tags += `${tags ? ',' : ''}${PROPAGATED_SAMPLING_DECISION_KEY}=${samplingDecision}`
   if (propagatedTraceId != null) tags += `${tags ? ',' : ''}${PROPAGATED_TRACE_ID_KEY}=${propagatedTraceId}`
-  if (tags !== existing) carrier['x-datadog-tags'] = tags
+  // When a local agent attribution is resolved, strip any stale upstream pagent entries that
+  // `_injectTags` may have already written into the carrier (it propagates all `_dd.p.*` from
+  // `_trace.tags`). This ensures the downstream sees a consistent id-only or id+name pair
+  // rather than a mix from different hops. The id is always digit-safe; an unsafe name is wiped.
+  if (parentAgentSpanId) {
+    tags = stripTagsetEntry(tags, PROPAGATED_PARENT_AGENT_ID_KEY)
+    tags = stripTagsetEntry(tags, PROPAGATED_PARENT_AGENT_NAME_KEY)
+  }
+  const maxLength = globalTracerConfig.DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH
+  const tagsWithId = appendOptionalPropagatedTag(
+    tags, PROPAGATED_PARENT_AGENT_ID_KEY, parentAgentSpanId, null, maxLength
+  )
+  // Only append the name when the id fit: a name without an id is unresolvable by the backend.
+  if (tagsWithId === tags) {
+    tags = tagsWithId
+  } else {
+    tags = appendOptionalPropagatedTag(
+      tagsWithId, PROPAGATED_PARENT_AGENT_NAME_KEY, parentAgentName, agentNameWireSafe, maxLength
+    )
+  }
+  if (tags !== existing) writeDatadogTags(carrier, tags)
 }
 
 function handleFlush () {

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

@@ -27,6 +27,8 @@ const {
   ML_APP,
   TAGS,
   PARENT_ID_KEY,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
   SESSION_ID,
   NAME,
   INPUT_PROMPT,
@@ -157,6 +159,20 @@ class LLMObsSpanProcessor {
       this.#addObject(mlObsTags[TOOL_DEFINITIONS], meta.tool_definitions)
     }
 
+    // Surface the agent attribution resolved at registration, but only on spans that actually
+    // have an agent ancestor. The id is always present in that case; the name may be missing when
+    // it arrived id-only over distributed propagation (older/unsafe upstream). Emit the name as
+    // explicit `null` then, matching the cross-language wire shape (dd-trace-py sends null, not an
+    // absent key) so the shared backend and system-tests see the same payload.
+    const parentAgentName = mlObsTags[PARENT_AGENT_NAME]
+    const parentAgentSpanId = mlObsTags[PARENT_AGENT_SPAN_ID]
+    if (parentAgentName != null || parentAgentSpanId != null) {
+      meta.agent_attribution = {
+        pagent_name: parentAgentName ?? null,
+        pagent_span_id: parentAgentSpanId,
+      }
+    }
+
     const llmObsSpan = new LLMObservabilitySpan(spanKind)
 
     if (spanKind === 'llm' && mlObsTags[INPUT_MESSAGES]) {