feat(otel): otel sampling support in distributed tracing

packages/dd-trace/src/knuth_hash.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const UINT64_MODULO = 2n ** 64n
+
+// Knuth's factor for the sampling algorithm shared across Datadog tracers.
+const SAMPLING_KNUTH_FACTOR = 1_111_111_111_111_111_111n
+
+/**
+ * Hashes the lower 64 bits of a trace ID for deterministic trace sampling.
+ *
+ * @param {bigint} traceId
+ * @returns {bigint}
+ */
+function knuthHash (traceId) {
+  return (traceId * SAMPLING_KNUTH_FACTOR) % UINT64_MODULO
+}
+
+module.exports = knuthHash

packages/dd-trace/src/opentracing/propagation/text_map.js

@@ -37,6 +37,7 @@ const {
 const id = require('../../id')
 const DatadogSpanContext = require('../span_context')
 const log = require('../../log')
+const { buildOtelMember } = require('../../otel_sampling')
 const tags = require('../../../../../ext/tags')
 const { getConfiguredEnvName } = require('../../config/helper')
 const { setAllBaggageItems, getAllBaggageItems, removeAllBaggageItems } = require('../../baggage')
@@ -394,6 +395,18 @@ class TextMapPropagator {
 
     writeTraceparent(carrier, spanContext.toTraceparent())
 
+    const otelMember = ts.get('ot')
+    if (otelMember !== undefined ||
+      spanContext._sampling.probabilityRate !== undefined ||
+      spanContext._sampling.isProbabilityDecision === false) {
+      const rebuiltOtelMember = buildOtelMember(spanContext, otelMember)
+      if (rebuiltOtelMember === undefined) {
+        ts.delete('ot')
+      } else {
+        ts.set('ot', rebuiltOtelMember)
+      }
+    }
+
     ts.forVendor('dd', state => {
       if (!spanContext._isRemote) {
         // SpanContext was created by a ddtrace span.

packages/dd-trace/src/opentracing/propagation/tracestate.js

@@ -3,6 +3,7 @@
 // W3C Trace Context §3.3.1.2: max 32 list-members.
 // https://www.w3.org/TR/trace-context/#tracestate-header-field-values
 const MAX_LIST_MEMBERS = 32
+const MAX_TRACESTATE_BYTES = 512
 const WHITESPACE = /[ \t]/
 
 /**
@@ -56,6 +57,32 @@ function toString (map, pairSeparator, fieldSeparator) {
   return result
 }
 
+/**
+ * Keeps complete leftmost members within the W3C count and byte limits.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function limitTraceState (value) {
+  let byteLength = 0
+  let end = 0
+  let members = 0
+  let start = 0
+
+  while (start < value.length && members < MAX_LIST_MEMBERS) {
+    let next = value.indexOf(',', start)
+    if (next === -1) next = value.length
+    const memberLength = Buffer.byteLength(value.slice(start, next)) + (members === 0 ? 0 : 1)
+    if (byteLength + memberLength > MAX_TRACESTATE_BYTES) break
+    byteLength += memberLength
+    end = next
+    members++
+    start = next + 1
+  }
+
+  return value.slice(0, end)
+}
+
 class TraceStateData {
   #map
   changed = false
@@ -162,7 +189,12 @@ class TraceState {
   }
 
   toString () {
-    return toString(this, '=', ',')
+    const value = toString(this, '=', ',')
+    if (this.size <= MAX_LIST_MEMBERS &&
+      (value.length <= MAX_TRACESTATE_BYTES / 4 || Buffer.byteLength(value) <= MAX_TRACESTATE_BYTES)) {
+      return value
+    }
+    return limitTraceState(value)
   }
 }
 

packages/dd-trace/src/opentracing/span.js

@@ -204,8 +204,8 @@ class DatadogSpan {
   setTag (key, value) {
     this._spanContext.setTag(key, value)
 
-    if (isSamplingPriorityTag(key) && this._spanContext._sampling.priority === undefined) {
-      this._prioritySampler.sample(this, false)
+    if (isSamplingPriorityTag(key)) {
+      this._prioritySampler.setPriorityFromTag(this, key, value)
     }
 
     if (tagsUpdateCh.hasSubscribers) {
@@ -223,9 +223,11 @@ class DatadogSpan {
     // `options.tags` callers that pass `'key:val,key:val'` strings.
     const tags = this._spanContext.getTags()
     let mayChangeSamplingPriority
+    let samplingTags
 
     if (keyValueMap !== null && typeof keyValueMap === 'object' && !Array.isArray(keyValueMap)) {
       Object.assign(tags, keyValueMap)
+      samplingTags = keyValueMap
       mayChangeSamplingPriority =
         MANUAL_KEEP in keyValueMap ||
         MANUAL_DROP in keyValueMap ||
@@ -234,14 +236,15 @@ class DatadogSpan {
       /* istanbul ignore if: v5 fallback, master ships 6.0.0-pre */
       if (DD_MAJOR < 6 && (typeof keyValueMap === 'string' || Array.isArray(keyValueMap))) {
         tagger.add(tags, keyValueMap)
+        samplingTags = tags
         mayChangeSamplingPriority = true
       } else {
         return this
       }
     }
 
-    if (mayChangeSamplingPriority && this._spanContext._sampling.priority === undefined) {
-      this._prioritySampler.sample(this, false)
+    if (mayChangeSamplingPriority) {
+      this._prioritySampler.setPriorityFromTags(this, samplingTags)
     }
 
     if (tagsUpdateCh.hasSubscribers) {

packages/dd-trace/src/otel_sampling.js

@@ -0,0 +1,158 @@
+'use strict'
+
+const { AUTO_KEEP } = require('../../../ext/priority')
+const knuthHash = require('./knuth_hash')
+
+const MAX_OTEL_VALUE_BYTES = 256
+const MAX_THRESHOLD = 2n ** 56n
+const MAX_ENCODABLE_THRESHOLD = MAX_THRESHOLD - 1n
+const UINT64_MASK = 2n ** 64n - 1n
+const validRandomValue = /^[0-9a-f]{14}$/
+const validThreshold = /^[0-9a-f]{1,14}$/
+
+/**
+ * Derives the OTel 56-bit random value from Datadog's sampling hash.
+ *
+ * @param {bigint} traceId
+ * @returns {bigint}
+ */
+function randomValueFor (traceId) {
+  return ((~knuthHash(traceId)) & UINT64_MASK) >> 8n
+}
+
+/**
+ * Converts a sample rate to an OTel 56-bit rejection threshold.
+ *
+ * @param {number} sampleRate
+ * @returns {bigint}
+ */
+function thresholdFor (sampleRate) {
+  if (sampleRate === 1) return 0n
+  if (sampleRate === 0) return MAX_ENCODABLE_THRESHOLD
+
+  const threshold = BigInt(Math.round((1 - sampleRate) * Number(MAX_THRESHOLD)))
+  if (threshold < 0n) return 0n
+  if (threshold > MAX_ENCODABLE_THRESHOLD) return MAX_ENCODABLE_THRESHOLD
+  return threshold
+}
+
+/**
+ * Formats an OTel threshold with trailing zero nibbles removed.
+ *
+ * @param {bigint} threshold
+ * @returns {string}
+ */
+function formatThreshold (threshold) {
+  return threshold.toString(16).padStart(14, '0').replace(/0+$/, '') || '0'
+}
+
+/**
+ * Generates OTel sampling fields for a local probability decision.
+ *
+ * @param {import('./opentracing/span_context')} context
+ * @returns {{ randomValue: string, threshold: string } | undefined}
+ */
+function generateFields (context) {
+  const { priority, probabilityRate } = context._sampling
+  if (priority === undefined || probabilityRate === undefined) return
+
+  const thresholdValue = thresholdFor(probabilityRate)
+  let randomValue = randomValueFor(context._traceId.toBigInt())
+  const kept = priority >= AUTO_KEEP
+
+  if (kept && randomValue < thresholdValue) {
+    randomValue = thresholdValue
+  } else if (!kept && randomValue >= thresholdValue) {
+    randomValue = thresholdValue > 0n ? thresholdValue - 1n : 0n
+  }
+
+  return {
+    randomValue: randomValue.toString(16).padStart(14, '0'),
+    threshold: formatThreshold(thresholdValue),
+  }
+}
+
+/**
+ * Adds a complete sub-field while the OTel member remains within its byte cap.
+ *
+ * @param {string[]} fields
+ * @param {string} field
+ * @param {number} byteLength
+ * @returns {number}
+ */
+function addField (fields, field, byteLength) {
+  const fieldLength = Buffer.byteLength(field) + (fields.length === 0 ? 0 : 1)
+  if (byteLength + fieldLength <= MAX_OTEL_VALUE_BYTES) {
+    fields.push(field)
+    return byteLength + fieldLength
+  }
+  return byteLength
+}
+
+/**
+ * Parses and rebuilds the OTel tracestate member, preserving unknown sub-fields.
+ *
+ * @param {import('./opentracing/span_context')} context
+ * @param {string | undefined} member
+ * @returns {string | undefined}
+ */
+function buildOtelMember (context, member) {
+  if (member === undefined) {
+    if (context._sampling.isProbabilityDecision === false) return
+    const generated = generateFields(context)
+    if (!generated) return
+    return `rv:${generated.randomValue};th:${generated.threshold}`
+  }
+
+  let randomValue
+  let threshold
+  const unknownFields = []
+  let start = 0
+
+  while (start <= member.length) {
+    let end = member.indexOf(';', start)
+    if (end === -1) end = member.length
+    const field = member.slice(start, end)
+    if (field) {
+      const separator = field.indexOf(':')
+      const key = separator === -1 ? field : field.slice(0, separator)
+      const value = separator === -1 ? undefined : field.slice(separator + 1)
+      if (key === 'rv') {
+        randomValue = value
+      } else if (key === 'th') {
+        threshold = value
+      } else {
+        unknownFields.push(field)
+      }
+    }
+    if (end === member.length) break
+    start = end + 1
+  }
+
+  if (!validRandomValue.test(randomValue)) randomValue = undefined
+  if (!validThreshold.test(threshold)) threshold = undefined
+
+  if (context._sampling.isProbabilityDecision === false) {
+    threshold = undefined
+  } else if (randomValue === undefined && threshold === undefined) {
+    const generated = generateFields(context)
+    if (generated) {
+      randomValue = generated.randomValue
+      threshold = generated.threshold
+    }
+  }
+
+  const fields = []
+  let byteLength = 0
+  if (randomValue !== undefined) byteLength = addField(fields, `rv:${randomValue}`, byteLength)
+  if (threshold !== undefined) byteLength = addField(fields, `th:${threshold}`, byteLength)
+  for (const field of unknownFields) {
+    byteLength = addField(fields, field, byteLength)
+  }
+
+  return fields.length === 0 ? undefined : fields.join(';')
+}
+
+module.exports = {
+  buildOtelMember,
+}