feat(openfeature): add span enrichment

Author: dd-oleksii

ddtrace/tracer/span.go

@@ -34,6 +34,7 @@ import (
 	"github.com/DataDog/dd-trace-go/v2/internal/locking"
 	"github.com/DataDog/dd-trace-go/v2/internal/locking/assert"
 	"github.com/DataDog/dd-trace-go/v2/internal/log"
+	iof "github.com/DataDog/dd-trace-go/v2/internal/openfeature"
 	"github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
 	"github.com/DataDog/dd-trace-go/v2/internal/samplernames"
 	"github.com/DataDog/dd-trace-go/v2/internal/stacktrace"
@@ -180,6 +181,9 @@ type Span struct {
 
 	// +checklocks:mu
 	taskEnd func() // ends execution tracer (runtime/trace) task, if started
+
+	// +checklocks:mu
+	ffeEvaluations *iof.SpanEnrichment `msg:"-"`
 }
 
 func (s *Span) clear() {
@@ -956,6 +960,40 @@ func (s *Span) serializeSpanEvents() {
 	s.meta.Set("events", string(b))
 }
 
+// recordFFEEvaluation records a feature flag evaluation in span enrichment.
+// Used by github.com/DataDog/dd-trace-go/v2/openfeature via go:linkname.
+func recordFFEEvaluation(s *Span, eval *iof.FeatureFlagEvaluation) {
+	if s == nil || eval == nil {
+		return
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.finished {
+		return
+	}
+
+	if s.ffeEvaluations == nil {
+		s.ffeEvaluations = iof.NewSpanEnrichment()
+	}
+	s.ffeEvaluations.AddEvaluation(eval)
+}
+
+// serializeFFEEvaluations sets the openfeature feature flag evaluation tags.
+// +checklocks:s.mu
+func (s *Span) serializeFFEEvaluations() {
+	assert.RWMutexLocked(&s.mu)
+	if s.ffeEvaluations == nil {
+		return
+	}
+	tags := s.ffeEvaluations.GetSpanTags()
+	for tag, value := range tags {
+		s.meta.Set(tag, value)
+	}
+	s.ffeEvaluations = nil
+}
+
 // Finish closes this Span (but not its children) providing the duration
 // of its part of the tracing session.
 func (s *Span) Finish(opts ...FinishOption) {
@@ -1060,6 +1098,7 @@ func (s *Span) finish(finishTime int64) {
 
 	s.serializeSpanLinksInMeta()
 	s.serializeSpanEvents()
+	s.serializeFFEEvaluations()
 	s.enrichServiceSource()
 
 	if s.duration == 0 {

internal/env/supported_configurations.gen.go

@@ -392,6 +392,13 @@
         "default": "false"
       }
     ],
+    "DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "false"
+      }
+    ],
     "DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED": [
       {
         "implementation": "B",

internal/env/supported_configurations.json

@@ -0,0 +1,179 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2026 Datadog, Inc.
+
+package openfeature
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"slices"
+	"sync"
+
+	"github.com/DataDog/dd-trace-go/v2/internal/log"
+)
+
+// FeatureFlagEvaluation represents a single feature flag evaluation to be
+// recorded in span enrichment.
+type FeatureFlagEvaluation struct {
+	FlagKey string
+	// SerialId is the optional serial ID from flag metadata. Nil for runtime defaults.
+	SerialID *uint32
+	// Subject is the targeting key / subject of experiment. Non-empty only when evaluation
+	// should be logged (doLog=true).
+	Subject string
+	// DefaultValue is the default value used. Non-nil only when a runtime default was used.
+	DefaultValue any
+}
+
+const (
+	spanEnrichmentMaxSerialIDs           = 200
+	spanEnrichmentMaxSubjects            = 10
+	spanEnrichmentMaxSerialIDsPerSubject = 20
+	spanEnrichmentMaxRuntimeDefaults     = 5
+	spanEnrichmentMaxDefaultValueLen     = 64
+)
+
+// SpanEnrichment accumulates feature flag evaluations to be encoded as span tags.
+type SpanEnrichment struct {
+	mu              sync.Mutex
+	serialIDs       map[uint32]struct{}
+	subjects        map[string]map[uint32]struct{}
+	runtimeDefaults map[string]string
+}
+
+func NewSpanEnrichment() *SpanEnrichment {
+	return &SpanEnrichment{
+		serialIDs:       make(map[uint32]struct{}, spanEnrichmentMaxSerialIDs),
+		subjects:        make(map[string]map[uint32]struct{}, spanEnrichmentMaxSubjects),
+		runtimeDefaults: make(map[string]string, spanEnrichmentMaxRuntimeDefaults),
+	}
+}
+
+func (se *SpanEnrichment) AddEvaluation(eval *FeatureFlagEvaluation) {
+	if eval == nil {
+		return
+	}
+
+	se.mu.Lock()
+	defer se.mu.Unlock()
+
+	if eval.SerialID != nil {
+		se.addSerialID(*eval.SerialID)
+		if eval.Subject != "" {
+			se.addSubject(eval.Subject, *eval.SerialID)
+		}
+	} else if eval.DefaultValue != nil {
+		se.addRuntimeDefault(eval.FlagKey, eval.DefaultValue)
+	}
+}
+
+// Must be called with se.mu held.
+func (se *SpanEnrichment) addSerialID(sid uint32) {
+	if _, exists := se.serialIDs[sid]; !exists {
+		if len(se.serialIDs) >= spanEnrichmentMaxSerialIDs {
+			log.Debug("openfeature: span enrichment: too many flag serial IDs, dropping (max %d)", spanEnrichmentMaxSerialIDs)
+			return
+		}
+		se.serialIDs[sid] = struct{}{}
+	}
+}
+
+// Must be called with se.mu held.
+func (se *SpanEnrichment) addSubject(subject string, sid uint32) {
+	subjectIDs, ok := se.subjects[subject]
+	if !ok {
+		if len(se.subjects) >= spanEnrichmentMaxSubjects {
+			log.Debug("openfeature: span enrichment: too many targeting keys, dropping (max %d)", spanEnrichmentMaxSubjects)
+			return
+		}
+		subjectIDs = make(map[uint32]struct{}, spanEnrichmentMaxSerialIDsPerSubject)
+		se.subjects[subject] = subjectIDs
+	}
+	if len(subjectIDs) >= spanEnrichmentMaxSerialIDsPerSubject {
+		log.Debug("openfeature: span enrichment: too many experiments for subject %q, dropping (max %d)", subject, spanEnrichmentMaxSerialIDsPerSubject)
+		return
+	}
+	subjectIDs[sid] = struct{}{}
+}
+
+// Must be called with se.mu held.
+func (se *SpanEnrichment) addRuntimeDefault(flagKey string, defaultValue any) {
+	if _, exists := se.runtimeDefaults[flagKey]; exists {
+		return
+	}
+	if len(se.runtimeDefaults) >= spanEnrichmentMaxRuntimeDefaults {
+		log.Debug("openfeature: span enrichment: too many runtime defaults, dropping (max %d)", spanEnrichmentMaxRuntimeDefaults)
+		return
+	}
+	var valueStr string
+	if v, ok := defaultValue.(string); ok {
+		valueStr = v
+	} else if b, err := json.Marshal(defaultValue); err == nil {
+		valueStr = string(b)
+	} else {
+		log.Debug("openfeature: span enrichment: failed to marshal runtime default value for key %q: %v", flagKey, err.Error())
+		return
+	}
+	if len(valueStr) > spanEnrichmentMaxDefaultValueLen {
+		log.Debug("openfeature: span enrichment: runtime default value for key %q exceeds max length (%d), truncating", flagKey, spanEnrichmentMaxDefaultValueLen)
+		valueStr = valueStr[:spanEnrichmentMaxDefaultValueLen]
+	}
+	se.runtimeDefaults[flagKey] = valueStr
+}
+
+// GetSpanTags returns span tags encoding accumulated feature flag evaluations.
+func (se *SpanEnrichment) GetSpanTags() map[string]string {
+	se.mu.Lock()
+	defer se.mu.Unlock()
+
+	tags := make(map[string]string, 3)
+
+	tags["ffe_flags_enc"] = encodeSerialIDs(se.serialIDs)
+
+	subjects := make(map[string]string, len(se.subjects))
+	for key, ids := range se.subjects {
+		subjects[key] = encodeSerialIDs(ids)
+	}
+	if b, err := json.Marshal(subjects); err == nil {
+		tags["ffe_subjects_enc"] = string(b)
+	} else {
+		log.Debug("openfeature: span enrichment: failed to marshal subjects: %v", err.Error())
+	}
+
+	defaults := se.runtimeDefaults
+	if b, err := json.Marshal(defaults); err == nil {
+		tags["ffe_runtime_defaults"] = string(b)
+	} else {
+		log.Debug("openfeature: span enrichment: failed to marshal runtime defaults: %v", err.Error())
+	}
+
+	return tags
+}
+
+// Encode a set of serial ids using unsigned LEB128 delta encoding, wrapped in base64.
+func encodeSerialIDs(ids map[uint32]struct{}) string {
+	seq := make([]uint32, 0, len(ids))
+	for id := range ids {
+		seq = append(seq, id)
+	}
+
+	slices.Sort(seq)
+
+	b := make([]byte, 0, 5*len(seq)) // 5 bytes is absolute max to encode an id
+	var prevID uint32 = 0
+	for _, id := range seq {
+		diff := id - prevID
+		prevID = id
+
+		// Unsigned LEB128 encoding.
+		for diff > 0x7f {
+			b = append(b, byte((diff&0x7f)|0x80))
+			diff >>= 7
+		}
+		b = append(b, byte(diff&0x7f))
+	}
+
+	return base64.StdEncoding.EncodeToString(b)
+}

internal/openfeature/span_enrichment.go

@@ -0,0 +1,103 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2026 Datadog, Inc.
+
+package openfeature
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSpanEnrichment_GetSpanTags(t *testing.T) {
+	se := NewSpanEnrichment()
+
+	sid42 := uint32(42)
+	sid101 := uint32(101)
+	se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: "experiment-b", SerialID: &sid101})
+	se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: "experiment-a", SerialID: &sid42, Subject: "user-123"})
+	se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: "experiment-a-dup", SerialID: &sid42, Subject: "user-123"})
+	se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: "default-flag", DefaultValue: "default-val"})
+
+	tags := se.GetSpanTags()
+	assert.Equal(t, []uint32{42, 101}, decodeSerialIDs(t, tags["ffe_flags_enc"]))
+
+	var subjects map[string]string
+	require.NoError(t, json.Unmarshal([]byte(tags["ffe_subjects_enc"]), &subjects))
+	assert.Equal(t, map[string]string{"user-123": encodeSerialIDs(map[uint32]struct{}{42: {}})}, subjects)
+
+	var defaults map[string]string
+	require.NoError(t, json.Unmarshal([]byte(tags["ffe_runtime_defaults"]), &defaults))
+	assert.Equal(t, map[string]string{"default-flag": "default-val"}, defaults)
+}
+
+func TestSpanEnrichment_Limits(t *testing.T) {
+	t.Run("serial ids", func(t *testing.T) {
+		se := NewSpanEnrichment()
+		for i := range spanEnrichmentMaxSerialIDs + 1 {
+			sid := uint32(i + 1)
+			se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: fmt.Sprintf("flag-%d", i), SerialID: &sid})
+		}
+
+		ids := decodeSerialIDs(t, se.GetSpanTags()["ffe_flags_enc"])
+		require.Len(t, ids, spanEnrichmentMaxSerialIDs)
+		assert.Equal(t, uint32(spanEnrichmentMaxSerialIDs), ids[len(ids)-1])
+	})
+
+	t.Run("subjects", func(t *testing.T) {
+		se := NewSpanEnrichment()
+		for i := range spanEnrichmentMaxSubjects + 1 {
+			sid := uint32(i + 1)
+			se.AddEvaluation(&FeatureFlagEvaluation{
+				FlagKey:  fmt.Sprintf("flag-%d", i),
+				SerialID: &sid,
+				Subject:  fmt.Sprintf("user-%d", i),
+			})
+		}
+
+		var subjects map[string]string
+		require.NoError(t, json.Unmarshal([]byte(se.GetSpanTags()["ffe_subjects_enc"]), &subjects))
+		require.Len(t, subjects, spanEnrichmentMaxSubjects)
+	})
+
+	t.Run("runtime defaults", func(t *testing.T) {
+		se := NewSpanEnrichment()
+		for i := range spanEnrichmentMaxRuntimeDefaults + 1 {
+			se.AddEvaluation(&FeatureFlagEvaluation{FlagKey: fmt.Sprintf("flag-%d", i), DefaultValue: []int{i}})
+		}
+
+		var defaults map[string]string
+		require.NoError(t, json.Unmarshal([]byte(se.GetSpanTags()["ffe_runtime_defaults"]), &defaults))
+		require.Len(t, defaults, spanEnrichmentMaxRuntimeDefaults)
+	})
+}
+
+func decodeSerialIDs(t *testing.T, enc string) []uint32 {
+	t.Helper()
+
+	b, err := base64.StdEncoding.DecodeString(enc)
+	require.NoError(t, err)
+
+	ids := make([]uint32, 0)
+	var id uint32
+	var shift uint
+	var diff uint32
+	for _, v := range b {
+		diff |= uint32(v&0x7f) << shift
+		if v&0x80 != 0 {
+			shift += 7
+			continue
+		}
+		id += diff
+		ids = append(ids, id)
+		diff = 0
+		shift = 0
+	}
+	return ids
+}

internal/openfeature/span_enrichment_test.go

@@ -34,6 +34,12 @@ type evaluationResult struct {
 	Metadata map[string]any
 }
 
+const (
+	metadataAllocationKey = "dd.allocation.key"
+	metadataDoLogKey      = "dd.doLog"
+	metadataSerialIDKey   = "dd.serialId"
+)
+
 // evaluateFlag evaluates a feature flag with the given context.
 // It returns the variant value, reason, and any error that occurred.
 func evaluateFlag(flag *flag, defaultValue any, context map[string]any) evaluationResult {
@@ -90,6 +96,10 @@ func evaluateFlag(flag *flag, defaultValue any, context map[string]any) evaluati
 			}
 			metadata[metadataDoLogKey] = doLog
 
+			if split.SerialID != nil {
+				metadata[metadataSerialIDKey] = *split.SerialID
+			}
+
 			// Determine reason:
 			//   rules matched           → TARGETING_MATCH
 			//   no rules, shards used   → SPLIT