dd-trace 5.104.0 → 5.106.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/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/opentelemetry/trace/otlp_transformer.js

@@ -16,6 +16,11 @@ const SPAN_KIND_CONSUMER = protoSpanKind.values.SPAN_KIND_CONSUMER
 // Cached zero Identifier used to detect zero IDs without re-allocating per span.
 const ZERO_ID = id('0')
 
+// DD propagation tag carrying the upper 64 bits of a 128-bit trace ID as 16 hex chars.
+// span_format.js#extractChunkTags only copies this onto the first-in-chunk span, so the
+// transformer scans the batch to find it and applies it to every span's traceId.
+const TRACE_ID_128 = '_dd.p.tid'
+
 /**
  * @typedef {import('../../id').Identifier} Identifier
  *
@@ -65,6 +70,7 @@ const STATUS_CODE_ERROR = 2
 const EXCLUDED_META_KEYS = new Set([
   '_dd.span_links',
   'span.kind',
+  TRACE_ID_128,
 ])
 
 /**
@@ -113,6 +119,18 @@ class OtlpTraceTransformer extends OtlpTransformerBase {
    * @returns {object[]} Array of scope span objects
    */
   #transformScopeSpans (spans) {
+    let traceKey
+    let traceIdHigh
+    const otlpSpans = spans.map((span) => {
+      // `_dd.p.tid` lives only on the first-in-chunk span of each trace.
+      // Reset at each trace boundary for batching of multiple traces.
+      const key = span.trace_id.toString(16)
+      if (key !== traceKey) {
+        traceKey = key
+        traceIdHigh = span.meta?.[TRACE_ID_128]?.toLowerCase()
+      }
+      return this.#transformSpan(span, traceIdHigh)
+    })
     return [{
       scope: {
         name: 'dd-trace-js',
@@ -121,7 +139,7 @@ class OtlpTraceTransformer extends OtlpTransformerBase {
         droppedAttributesCount: 0,
       },
       schemaUrl: '',
-      spans: spans.map(span => this.#transformSpan(span)),
+      spans: otlpSpans,
     }]
   }
 
@@ -129,14 +147,15 @@ class OtlpTraceTransformer extends OtlpTransformerBase {
    * Transforms a single DD-formatted span to an OTLP Span object.
    *
    * @param {DDFormattedSpan} span - DD-formatted span to transform
+   * @param {string | undefined} traceIdHigh - 16-char hex of the upper 64 bits of the trace ID
    * @returns {object} OTLP Span object
    */
-  #transformSpan (span) {
+  #transformSpan (span, traceIdHigh) {
     const parentId = span.parent_id
     const links = this.#extractLinks(span.meta?.['_dd.span_links'])
 
     return {
-      traceId: this.#idToBytes(span.trace_id, 16),
+      traceId: span.trace_id.toTraceIdHex(traceIdHigh).padStart(32, '0'),
       spanId: this.#idToBytes(span.span_id, 8),
       parentSpanId: (parentId && !parentId.equals(ZERO_ID)) ? this.#idToBytes(parentId, 8) : undefined,
       name: span.resource,

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) {