dd-trace 5.103.0 → 5.105.0

package/packages/dd-trace/src/openfeature/span-enrichment-hook.js

@@ -0,0 +1,143 @@
+'use strict'
+
+const { channel } = require('dc-polyfill')
+const log = require('../log')
+const { SpanEnrichmentState } = require('./span-enrichment')
+
+const finishCh = channel('dd-trace:span:finish')
+
+/**
+ * OpenFeature hook that enriches APM spans with feature flag evaluation data.
+ *
+ * Implements the OpenFeature `finally` hook interface to capture flag evaluations
+ * and add span tags for observability. Tags are accumulated during the span's
+ * lifetime and applied when the root span finishes.
+ *
+ * Span tags added:
+ * - `ffe_flags_enc`: Base64 delta-varint encoded serial IDs
+ * - `ffe_subjects_enc`: JSON dict of SHA256(targeting_key) → encoded serial IDs
+ * - `ffe_runtime_defaults`: JSON dict of flag_key → default value string
+ */
+class SpanEnrichmentHook {
+  #tracer
+  /** @type {WeakMap<object, SpanEnrichmentState>} */
+  #spanStates = new WeakMap()
+
+  /**
+   * Handler for span finish channel. Applies accumulated tags to the span.
+   * Arrow function to preserve `this` binding for channel subscription.
+   *
+   * @param {object} span - The span that is finishing
+   */
+  #onSpanFinish = (span) => {
+    const state = this.#spanStates.get(span)
+    if (!state || !state.hasData()) return
+
+    try {
+      const tags = state.toSpanTags()
+
+      for (const [key, value] of Object.entries(tags)) {
+        if (value) {
+          span.setTag(key, value)
+        }
+      }
+    } catch (err) {
+      log.warn('SpanEnrichmentHook: error applying span tags: %s', err.message)
+    } finally {
+      this.#spanStates.delete(span)
+    }
+  }
+
+  /**
+   * @param {import('../tracer')} tracer - Datadog tracer instance
+   */
+  constructor (tracer) {
+    this.#tracer = tracer
+    finishCh.subscribe(this.#onSpanFinish)
+  }
+
+  /**
+   * Called by the OpenFeature SDK after every flag evaluation (success or error).
+   *
+   * @param {object} hookContext - Hook context containing the flag key and evaluation context
+   * @param {string} hookContext.flagKey - The flag key being evaluated
+   * @param {object} [hookContext.context] - Evaluation context
+   * @param {string} [hookContext.context.targetingKey] - Targeting key
+   * @param {object} evaluationDetails - Full evaluation details including flag metadata
+   * @param {object} [evaluationDetails.flagMetadata] - Metadata from the provider
+   * @param {number} [evaluationDetails.flagMetadata.__dd_split_serial_id] - Serial ID from UFC split
+   * @param {boolean} [evaluationDetails.flagMetadata.__dd_do_log] - Whether to log subject
+   * @param {string} [evaluationDetails.variant] - Variant key if flag was found in UFC
+   * @param {boolean|string|number|object} [evaluationDetails.value] - Evaluated value
+   * @returns {void}
+   */
+  finally (hookContext, evaluationDetails) {
+    try {
+      const rootSpan = this._getRootSpan()
+      if (!rootSpan) return
+
+      const state = this._getOrCreateState(rootSpan)
+      const { flagKey, context } = hookContext || {}
+      const { flagMetadata, variant, value } = evaluationDetails || {}
+
+      const serialId = flagMetadata?.__dd_split_serial_id
+      const doLog = flagMetadata?.__dd_do_log ?? false
+      const targetingKey = context?.targetingKey
+
+      if (serialId != null) {
+        state.addSerialId(serialId)
+
+        if (doLog && targetingKey) {
+          state.addSubject(targetingKey, serialId)
+        }
+      } else if (variant === undefined) {
+        state.addDefault(flagKey, value)
+      }
+    } catch (err) {
+      log.warn('SpanEnrichmentHook: error in finally hook: %s', err.message)
+    }
+  }
+
+  /**
+   * Get the root span for the current trace context.
+   * The root span is always the first span in trace.started since spans
+   * are added in creation order and the root is created first.
+   *
+   * @returns {object|null} The root span, or null if no active span
+   * @private
+   */
+  _getRootSpan () {
+    const span = this.#tracer.scope().active()
+    if (!span) return null
+
+    const trace = span.context()._trace
+
+    return trace?.started?.[0] ?? span
+  }
+
+  /**
+   * Get or create enrichment state for a span.
+   *
+   * @param {object} span - The span to get state for
+   * @returns {SpanEnrichmentState} The enrichment state
+   * @private
+   */
+  _getOrCreateState (span) {
+    let state = this.#spanStates.get(span)
+    if (!state) {
+      state = new SpanEnrichmentState()
+      this.#spanStates.set(span, state)
+    }
+    return state
+  }
+
+  /**
+   * Cleanup method to unsubscribe from channels.
+   * Should be called when the provider is shut down.
+   */
+  destroy () {
+    finishCh.unsubscribe(this.#onSpanFinish)
+  }
+}
+
+module.exports = SpanEnrichmentHook

package/packages/dd-trace/src/openfeature/span-enrichment.js

@@ -0,0 +1,149 @@
+'use strict'
+
+const log = require('../log')
+
+const { encodeDeltaVarint, hashTargetingKey } = require('./encoding')
+
+const MAX_SERIAL_IDS = 200
+const MAX_SUBJECTS = 10
+const MAX_EXPERIMENTS_PER_SUBJECT = 20
+const MAX_DEFAULTS = 5
+const MAX_DEFAULT_VALUE_LENGTH = 64
+
+/**
+ * Manages feature flag enrichment state for a single root span.
+ * Accumulates serial IDs, subjects, and defaults throughout the span's lifetime.
+ */
+class SpanEnrichmentState {
+  constructor () {
+    /** @type {Set<number>} */
+    this._serialIds = new Set()
+
+    /** @type {Map<string, Set<number>>} hashed targeting key -> serial IDs */
+    this._subjects = new Map()
+
+    /** @type {Map<string, string>} flag key -> runtime default value */
+    this._defaults = new Map()
+  }
+
+  /**
+   * Add a serial ID from a flag evaluation.
+   *
+   * @param {number} serialId - The serial ID to add
+   * @returns {boolean} True if added, false if limit reached
+   */
+  addSerialId (serialId) {
+    if (this._serialIds.size >= MAX_SERIAL_IDS) {
+      log.debug('SpanEnrichment: MAX_SERIAL_IDS limit (%d) reached, dropping serialId %d', MAX_SERIAL_IDS, serialId)
+      return false
+    }
+    this._serialIds.add(serialId)
+    return true
+  }
+
+  /**
+   * Add a subject (targeting key) with its associated serial ID.
+   * Only called when doLog=true.
+   *
+   * @param {string} targetingKey - The targeting key (will be hashed)
+   * @param {number} serialId - The serial ID associated with this evaluation
+   * @returns {boolean} True if added, false if limit reached
+   */
+  addSubject (targetingKey, serialId) {
+    const hashedKey = hashTargetingKey(targetingKey)
+
+    if (this._subjects.has(hashedKey)) {
+      const subjectIds = this._subjects.get(hashedKey)
+      if (subjectIds.size >= MAX_EXPERIMENTS_PER_SUBJECT) {
+        log.debug('SpanEnrichment: MAX_EXPERIMENTS_PER_SUBJECT limit (%d) reached for subject',
+          MAX_EXPERIMENTS_PER_SUBJECT)
+        return false
+      }
+      subjectIds.add(serialId)
+      return true
+    }
+
+    if (this._subjects.size >= MAX_SUBJECTS) {
+      log.debug('SpanEnrichment: MAX_SUBJECTS limit (%d) reached, dropping subject', MAX_SUBJECTS)
+      return false
+    }
+
+    this._subjects.set(hashedKey, new Set([serialId]))
+    return true
+  }
+
+  /**
+   * Add a default fallback for a flag not found in UFC.
+   *
+   * @param {string} flagKey - The flag key
+   * @param {boolean|string|number|object} defaultValue - The default value used
+   * @returns {boolean} True if added, false if limit reached
+   */
+  addDefault (flagKey, defaultValue) {
+    if (this._defaults.has(flagKey)) {
+      return true
+    }
+
+    if (this._defaults.size >= MAX_DEFAULTS) {
+      log.debug('SpanEnrichment: MAX_DEFAULTS limit (%d) reached, dropping flag %s', MAX_DEFAULTS, flagKey)
+      return false
+    }
+
+    let valueStr = typeof defaultValue === 'object' && defaultValue !== null
+      ? JSON.stringify(defaultValue)
+      : String(defaultValue)
+
+    if (valueStr.length > MAX_DEFAULT_VALUE_LENGTH) {
+      valueStr = valueStr.slice(0, MAX_DEFAULT_VALUE_LENGTH)
+    }
+
+    this._defaults.set(flagKey, valueStr)
+    return true
+  }
+
+  /**
+   * Check if there is any enrichment data to add to the span.
+   * Note: _subjects is not checked because addSubject() is never called without first
+   * calling addSerialId(), so _subjects having data necessitates _serialIds having data.
+   *
+   * @returns {boolean} True if there is data to add
+   */
+  hasData () {
+    return this._serialIds.size > 0 || this._defaults.size > 0
+  }
+
+  /**
+   * Convert accumulated state to span tags.
+   *
+   * @returns {object} Object with ffe_flags_enc, ffe_subjects_enc, and ffe_runtime_defaults tags
+   */
+  toSpanTags () {
+    const tags = {}
+
+    if (this._serialIds.size > 0) {
+      tags.ffe_flags_enc = encodeDeltaVarint(this._serialIds)
+    }
+
+    if (this._subjects.size > 0) {
+      const subjectsObj = Object.fromEntries(
+        [...this._subjects].map(([key, ids]) => [key, encodeDeltaVarint(ids)])
+      )
+      tags.ffe_subjects_enc = JSON.stringify(subjectsObj)
+    }
+
+    if (this._defaults.size > 0) {
+      tags.ffe_runtime_defaults = JSON.stringify(Object.fromEntries(this._defaults))
+    }
+
+    return tags
+  }
+}
+
+module.exports = {
+  SpanEnrichmentState,
+  MAX_SERIAL_IDS,
+  MAX_SUBJECTS,
+  MAX_EXPERIMENTS_PER_SUBJECT,
+  MAX_DEFAULTS,
+  MAX_DEFAULT_VALUE_LENGTH,
+}

package/packages/dd-trace/src/openfeature/writers/exposures.js

@@ -8,8 +8,14 @@ const {
   EVP_PAYLOAD_SIZE_LIMIT,
   EVP_EVENT_SIZE_LIMIT,
 } = require('../constants/constants')
+const log = require('../../log')
 const BaseFFEWriter = require('./base')
 
+// Disabled-state cap. Drops invalidate experiment results because the provider's
+// exposure dedupe cache keeps masking dropped events after recovery. The first
+// drop emits a warning and `droppedEventCount` accumulates the cumulative loss.
+const PENDING_MAX_EVENTS = 1000
+
 /**
  * @typedef {object} ExposureEvent
  * @property {number} timestamp - Unix timestamp in milliseconds
@@ -42,11 +48,21 @@ const BaseFFEWriter = require('./base')
  * ExposuresWriter is responsible for sending exposure events to the Datadog Agent.
  */
 class ExposuresWriter extends BaseFFEWriter {
+  // Disabled until the agent strategy probe resolves.
+  #enabled = false
+
+  /** @type {ExposureEvent[]} */
+  #pendingEvents = []
+
+  /** @type {ExposureContext} */
+  #context
+
+  #dropWarned = false
+
   /**
    * @param {import('../../config/config-base')} config - Tracer configuration object
    */
   constructor (config) {
-    // Build full EVP endpoint path
     const basePath = EVP_PROXY_AGENT_BASE_PATH.replace(/\/+$/, '')
     const endpoint = EXPOSURES_ENDPOINT.replace(/^\/+/, '')
     const fullEndpoint = `${basePath}/${endpoint}`
@@ -60,33 +76,33 @@ class ExposuresWriter extends BaseFFEWriter {
         [EVP_SUBDOMAIN_HEADER_NAME]: EVP_SUBDOMAIN_VALUE,
       },
     })
-    this._enabled = false // Start disabled until agent strategy is set
-    this._pendingEvents = [] // Buffer events until enabled
 
+    /** @type {ExposureContext} */
     const context = {
       service: config.service,
     }
-    // Only include version and env if they are defined
+
     if (config.version !== undefined) {
       context.version = config.version
     }
+
     if (config.env !== undefined) {
       context.env = config.env
     }
 
-    this._context = context
+    this.#context = context
   }
 
   /**
    * @param {boolean} enabled - Whether to enable the writer
    */
   setEnabled (enabled) {
-    this._enabled = enabled
+    this.#enabled = enabled
 
-    if (enabled && this._pendingEvents.length > 0) {
+    if (enabled && this.#pendingEvents.length > 0) {
       // Flush all pending events as a batch
-      super.append(this._pendingEvents)
-      this._pendingEvents = []
+      super.append(this.#pendingEvents)
+      this.#pendingEvents = []
     }
   }
 
@@ -95,24 +111,38 @@ class ExposuresWriter extends BaseFFEWriter {
    * @param {ExposureEvent|ExposureEvent[]} events - Exposure event(s) to append
    */
   append (events) {
-    if (!this._enabled) {
-      // Buffer events until writer is ready
-      if (Array.isArray(events)) {
-        this._pendingEvents.push(...events)
-      } else {
-        this._pendingEvents.push(events)
-      }
+    if (this.#enabled) {
+      super.append(events)
       return
     }
-    super.append(events)
+
+    const eventArray = Array.isArray(events) ? events : [events]
+    this.#pendingEvents.push(...eventArray)
+    if (this.#pendingEvents.length > PENDING_MAX_EVENTS) {
+      const dropped = this.#pendingEvents.length - PENDING_MAX_EVENTS
+      this.#pendingEvents.splice(0, dropped)
+      this._droppedEvents += dropped
+      if (!this.#dropWarned) {
+        this.#dropWarned = true
+        log.warn(
+          '%s dropped exposure event(s) at cap %d. This may invalidate experiment results.',
+          this.constructor.name, PENDING_MAX_EVENTS)
+      }
+    }
+  }
+
+  /**
+   * @returns {number} Cumulative number of exposure events dropped due to buffer overflow.
+   */
+  get droppedEventCount () {
+    return this._droppedEvents
   }
 
   /**
    * Flushes buffered exposure events to the agent
    */
   flush () {
-    if (!this._enabled) {
-      // Don't flush when disabled
+    if (!this.#enabled) {
       return
     }
     super.flush()
@@ -125,6 +155,7 @@ class ExposuresWriter extends BaseFFEWriter {
    */
   makePayload (events) {
     const formattedEvents = events.map(event => {
+      /** @type {ExposureEvent} */
       return {
         timestamp: event.timestamp || Date.now(),
         allocation: {
@@ -145,7 +176,7 @@ class ExposuresWriter extends BaseFFEWriter {
     })
 
     return {
-      context: this._context,
+      context: this.#context,
       exposures: formattedEvents,
     }
   }

package/packages/dd-trace/src/opentelemetry/metrics/periodic_metric_reader.js

@@ -336,7 +336,7 @@ class MetricAggregator {
       }
     }
 
-    this.#applyDeltaTemporality(metricsMap, lastExportedState)
+    this.#applyDeltaTemporality(metricsMap.values(), lastExportedState)
     return metricsMap
   }
 

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

@@ -7,6 +7,7 @@ const { timeInputToHrTime } = require('../../../../vendor/dist/@opentelemetry/co
 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 { DD_MAJOR } = require('../../../../version')
 
 const id = require('../id')
 
@@ -176,8 +177,8 @@ function setOtelAttributes (ddSpan, attributes) {
 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)
+  // v5 still accepts the legacy `addLink(context, attrs)` shape; v6 only takes `addLink(otel.Link)`.
+  const { context, attributes } = isOtelLink(link) || DD_MAJOR >= 6
     ? link
     : { context: link, attributes: attrs ?? {} }
 
@@ -230,7 +231,7 @@ function recordException (ddSpan, exception, timeInput) {
     [ERROR_TYPE]: exception.name,
     [ERROR_MESSAGE]: exception.message,
     [ERROR_STACK]: exception.stack,
-    [IGNORE_OTEL_ERROR]: ddSpan.context()._tags[IGNORE_OTEL_ERROR] ?? true,
+    [IGNORE_OTEL_ERROR]: ddSpan.context().getTag(IGNORE_OTEL_ERROR) ?? true,
   })
 
   const attributes = {}

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

@@ -216,7 +216,7 @@ class Span extends BridgeSpanBase {
       'ptr.hash': ptrHash,
       'link.kind': 'span-pointer',
     }
-    return this.addLink(zeroContext, attributes)
+    return this.addLink({ context: zeroContext, attributes })
   }
 
   /**

package/packages/dd-trace/src/opentracing/propagation/log.js

@@ -11,20 +11,31 @@ class LogPropagator {
   inject (spanContext, carrier) {
     if (!carrier) return
 
-    carrier.dd = {}
+    const dd = {}
+    let hasField = false
 
     if (spanContext) {
-      carrier.dd.trace_id = this._config.traceId128BitGenerationEnabled &&
+      dd.trace_id = this._config.traceId128BitGenerationEnabled &&
         this._config.traceId128BitLoggingEnabled && spanContext._trace.tags['_dd.p.tid']
         ? spanContext.toTraceId(true)
         : spanContext.toTraceId()
-
-      carrier.dd.span_id = spanContext.toSpanId()
+      dd.span_id = spanContext.toSpanId()
+      hasField = true
+    }
+    if (this._config.service) {
+      dd.service = this._config.service
+      hasField = true
+    }
+    if (this._config.version) {
+      dd.version = this._config.version
+      hasField = true
+    }
+    if (this._config.env) {
+      dd.env = this._config.env
+      hasField = true
     }
 
-    if (this._config.service) carrier.dd.service = this._config.service
-    if (this._config.version) carrier.dd.version = this._config.version
-    if (this._config.env) carrier.dd.env = this._config.env
+    if (hasField) carrier.dd = dd
   }
 
   extract (carrier) {