datadog 2.38.0 → 2.47.0

data/lib/datadog/open_feature/hooks/span_enrichment_hook/codec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Encoding/crypto helpers implementing the fixed cross-SDK wire format.
+        module Codec
+          module_function
+
+          # ULEB128 stores 7 bits per byte; the high bit flags that more bytes follow.
+          LOW_7_BITS_MASK = 0x7F
+          CONTINUATION_BIT = 0x80
+
+          # The `bytes` buffer built below MUST be binary (ASCII-8BIT): `String#<<`
+          # with an Integer on a UTF-8 string appends a Unicode *codepoint*, so any
+          # byte >= 0x80 would be re-encoded as a 2-byte UTF-8 sequence and corrupt
+          # the varint (e.g. serial 2312 -> bytes 88 12, but UTF-8 would emit
+          # C2 88 12 = 296002 on decode). `(+'').b` gives a mutable binary string.
+          def encode_varint(value)
+            bytes = (+"").b
+            while value > LOW_7_BITS_MASK
+              bytes << ((value & LOW_7_BITS_MASK) | CONTINUATION_BIT)
+              value >>= 7
+            end
+            bytes << (value & LOW_7_BITS_MASK)
+            bytes
+          end
+
+          # Encode a Set of serial ids as base64(ULEB128 delta-varint).
+          # Empty set -> empty string (the caller omits the tag).
+          def encode_delta_varint(serial_ids)
+            sorted = serial_ids.to_a.sort
+            return "" if sorted.empty?
+
+            bytes = (+"").b
+            prev = 0
+            sorted.each do |id|
+              bytes << encode_varint(id - prev)
+              prev = id
+            end
+            # `pack('m0')` is RFC 4648 base64 with no newlines (== strict_encode64)
+            # and needs no `base64` gem, which stopped being a default gem in Ruby 3.4.
+            [bytes].pack("m0")
+          end
+
+          # Lowercase hex SHA256 of the targeting key: it is hashed before
+          # emission so raw user identifiers never leave the process.
+          def hash_targeting_key(targeting_key)
+            Digest::SHA256.hexdigest(targeting_key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/hooks/span_enrichment_hook/span_enrichment_state.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "set"
+require "json"
+
+require_relative "codec"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Per-root-span state. Enforces the frozen limits, dedupes serial
+        # ids structurally via a Set, and renders the three `ffe_*` tag shapes.
+        #
+        # Not internally synchronized: every method is only ever called while the
+        # owning `SpanEnrichmentHook`'s mutex is held (capture, encode, cleanup),
+        # so the state stays a plain object and the lock provides the
+        # consistent snapshot at encode time.
+        class SpanEnrichmentState
+          def initialize
+            @serial_ids = Set.new
+            @subjects = {} # sha256hex => Set<int>
+            @defaults = {} # flag_key => String
+          end
+
+          def add_serial_id(serial_id)
+            return if @serial_ids.size >= MAX_SERIAL_IDS
+
+            @serial_ids.add(serial_id)
+          end
+
+          # Subject serial ids are NOT required to be a subset of the flag set:
+          # the frozen cross-SDK wire contract does not mandate `subjects ⊆ flags`,
+          # so a subject may reference a serial id that the independent 200-flag cap
+          # dropped from `ffe_flags_enc`. This mirrors the reference implementation
+          # and every other SDK; the caps (200 flags, 10 subjects, 20 experiments)
+          # are applied independently on purpose.
+          def add_subject(targeting_key, serial_id)
+            hashed = Codec.hash_targeting_key(targeting_key)
+            existing = @subjects[hashed]
+
+            if existing
+              return if existing.size >= MAX_EXPERIMENTS_PER_SUBJECT
+
+              existing.add(serial_id)
+            elsif @subjects.size >= MAX_SUBJECTS
+              nil
+            else
+              @subjects[hashed] = Set[serial_id]
+            end
+          end
+
+          # `value` is the flag's resolved runtime-default — any OpenFeature
+          # value type (String, boolean, number, or a structured Hash/Array).
+          # Non-strings are JSON-encoded (not `to_s`) so a structured default is
+          # captured faithfully rather than as Ruby's `inspect` form (e.g.
+          # `{"a"=>1}`, which is not valid JSON). The result is a bounded
+          # diagnostic PREVIEW, not a round-trippable value: it is truncated to
+          # the frozen 64-char cap, so a long JSON string is intentionally left
+          # as a non-parseable prefix. The backend treats this field as a
+          # display string, so a clipped value is acceptable.
+          def add_default(flag_key, value)
+            return if @defaults.key?(flag_key) # first-wins
+            return if @defaults.size >= MAX_DEFAULTS
+
+            value_str = value.is_a?(String) ? value : JSON.generate(value)
+            # Slicing is by codepoint, so a multibyte UTF-8 character is never
+            # split; `|| value_str` keeps the value non-nil for the zero-start slice.
+            @defaults[flag_key] = value_str[0, MAX_DEFAULT_VALUE_LENGTH] || value_str
+          end
+
+          # Subjects are intentionally not checked: a subject is only ever added
+          # alongside a serial id, so serial ids cover that case.
+          def has_data?
+            @serial_ids.any? || @defaults.any?
+          end
+
+          def to_span_tags
+            tags = {}
+            tags[TAG_FLAGS_ENC] = Codec.encode_delta_varint(@serial_ids) if @serial_ids.any?
+
+            if @subjects.any?
+              encoded_subjects = {}
+              @subjects.each { |hashed, ids| encoded_subjects[hashed] = Codec.encode_delta_varint(ids) }
+              tags[TAG_SUBJECTS_ENC] = JSON.generate(encoded_subjects)
+            end
+
+            tags[TAG_RUNTIME_DEFAULTS] = JSON.generate(@defaults) if @defaults.any?
+
+            tags
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/hooks/span_enrichment_hook/span_enrichment_state_store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "span_enrichment_state"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Maps each trace operation to its `SpanEnrichmentState`, keyed WEAKLY by
+        # object identity. Using `ObjectSpace::WeakMap` means an
+        # abandoned trace (root span never finishes) cannot pin its state:
+        # once the trace operation is unreachable the entry is collected. The
+        # state (the WeakMap *value*, which `WeakMap` would otherwise also
+        # collect once no strong ref remains) is kept alive for the trace's
+        # lifetime by the `span_before_finish` subscription closure, which is held
+        # by `trace_op.events`. So state lives exactly as long as the trace and
+        # dies with it.
+        #
+        # All access is serialized by the owning hook's mutex; the WeakMap itself
+        # is not thread-safe under concurrent mutation.
+        class SpanEnrichmentStateStore
+          def initialize
+            @states = ObjectSpace::WeakMap.new
+          end
+
+          def [](trace_op)
+            @states[trace_op]
+          end
+
+          def []=(trace_op, state)
+            @states[trace_op] = state
+          end
+
+          def delete(trace_op)
+            # `ObjectSpace::WeakMap#delete` was only added in Ruby 3.3; this gem
+            # supports Ruby 2.5+, so overwrite the slot with nil instead so a stale
+            # entry is never re-read after the root finishes. The slot itself is
+            # reclaimed when the trace operation is collected.
+            @states[trace_op] = nil
+          end
+
+          def clear!
+            @states = ObjectSpace::WeakMap.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/hooks/span_enrichment_hook.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "span_enrichment_hook/codec"
+require_relative "span_enrichment_hook/span_enrichment_state"
+require_relative "span_enrichment_hook/span_enrichment_state_store"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      # Captures feature-flag evaluation metadata and writes contract-conformant
+      # `ffe_*` tags onto the local root APM span when it finishes.
+      #
+      # The wire format is a fixed cross-SDK contract. The encoding (ULEB128
+      # delta-varint + base64), the per-trace aggregation limits, the runtime-default
+      # detection (missing variant) and the SHA256 subject hashing must be
+      # reproduced exactly so the backend decodes tags identically regardless of
+      # which language SDK emitted them.
+      #
+      # Dispatch:
+      #   Enrichment is driven DIRECTLY from `Provider#evaluate` (see `#capture`),
+      #   not through an OpenFeature hook. This is the only path that works on
+      #   every supported SDK version, so the capture happens on the provider
+      #   evaluation thread rather than a hook callback.
+      #
+      # Lifecycle:
+      #   - `#capture` runs on every evaluation. It resolves the local root span
+      #     off the active trace, lazily creates the per-root `SpanEnrichmentState`,
+      #     and on the first capture for a trace subscribes to that trace's
+      #     `span_before_finish` event. The subscription closure captures the
+      #     state strongly and is held by `trace_op.events`, so the state lives
+      #     exactly as long as the trace operation (the weak store key) — when the
+      #     trace is GC'd both die together (no leak even if the root never finishes).
+      #   - When the local root span is about to finish, the accumulated tags are
+      #     written via `span.set_tag` and the per-root state is deleted.
+      #   - `#shutdown` clears all accumulated state (provider-close cleanup).
+      #
+      # Thread-safety:
+      #   Concurrent evaluations (on different threads) can target the same active
+      #   trace. The GVL does NOT make the compound operations here safe
+      #   (fetch-or-create, subscribe-once, mutate-while-encoding), so all store /
+      #   subscription / state access is serialized through a single
+      #   `Mutex`, and the finish-time encode takes the snapshot under that lock.
+      #
+      # When the gate is off the hook is never constructed (see
+      # `Component#create_span_enrichment_hook`), so there is zero idle per-span
+      # overhead.
+      class SpanEnrichmentHook
+        # Fixed cross-SDK contract limits. No env-var knobs.
+        MAX_SERIAL_IDS = 200
+        MAX_SUBJECTS = 10
+        MAX_EXPERIMENTS_PER_SUBJECT = 20
+        MAX_DEFAULTS = 5
+        MAX_DEFAULT_VALUE_LENGTH = 64
+
+        TAG_FLAGS_ENC = "ffe_flags_enc"
+        TAG_SUBJECTS_ENC = "ffe_subjects_enc"
+        TAG_RUNTIME_DEFAULTS = "ffe_runtime_defaults"
+
+        def initialize(span_enrichment_state_store, logger:)
+          @store = span_enrichment_state_store
+          @mutex = Mutex.new
+          @active = true
+          @logger = logger
+        end
+
+        # Direct dispatch from the Datadog provider evaluation path. Takes only
+        # primitives so it does not depend on any OpenFeature SDK object shape and
+        # works on every supported SDK version. Never raises — flag evaluation and
+        # the trace pipeline must not be broken by enrichment.
+        #
+        # @param flag_key [String] the evaluated flag key
+        # @param variant [String, nil] the resolved variant (nil/empty => runtime default)
+        # @param value [Object] the resolved value (used for runtime-default capture)
+        # @param serial_id [Integer, nil] the split serial id, when assigned
+        # @param do_log [Boolean] whether logging/exposure is authorized for this subject
+        # @param targeting_key [String, nil] the raw targeting key (hashed before emit)
+        def capture(flag_key:, variant:, value:, serial_id:, do_log:, targeting_key:)
+          trace_op = Datadog::Tracing.active_trace
+          return unless trace_op
+
+          @mutex.synchronize do
+            if serial_id.nil?
+              if variant.nil? || variant.empty?
+                # Runtime default: detected by a missing variant (never a reason enum).
+                state_for(trace_op).add_default(flag_key, value)
+              end
+            else
+              state = state_for(trace_op)
+              state.add_serial_id(serial_id)
+              # Skip empty targeting keys: SHA256('') would collide every
+              # anonymous/missing subject under one bogus hash, corrupting
+              # subject-level attribution.
+              state.add_subject(targeting_key, serial_id) if do_log && targeting_key && !targeting_key.empty?
+            end
+          end
+        rescue => e
+          @logger.debug { "Error capturing span enrichment: #{e.class}: #{e.message}" }
+        end
+
+        # Provider-close cleanup: mark the hook inactive and drop all accumulated
+        # state. State is dropped, not flushed, on purpose: each state only
+        # becomes a set of tags when ITS OWN root span finishes, and at
+        # provider-close time those roots are still open — there is no valid
+        # target to flush to, and writing partial tags onto in-flight spans
+        # would emit incomplete data (and double-write once the root finished).
+        # A trace that already subscribed still holds its state via the
+        # `span_before_finish` closure, so clearing `@active` (checked in
+        # `write_tags_on_root`) is what actually prevents a stale write after
+        # shutdown. Per-trace subscriptions die with their trace operations, so
+        # there is nothing else to unsubscribe.
+        def shutdown
+          @mutex.synchronize do
+            @active = false
+            @store.clear!
+          end
+        end
+
+        private
+
+        # Lazily create the per-root state and, on first capture for a trace,
+        # subscribe to that trace's span lifecycle so we can write tags when the
+        # local root span finishes. MUST be called with `@mutex` held.
+        def state_for(trace_op)
+          state = @store[trace_op]
+          return state if state
+
+          state = SpanEnrichmentState.new
+          @store[trace_op] = state
+          subscribe_root_finish(trace_op, state)
+          state
+        end
+
+        # MUST be called with `@mutex` held. The subscription closure captures
+        # `state` strongly; since the closure is retained by
+        # `trace_op.events`, this keeps the WeakMap value alive for the trace's
+        # lifetime (and lets both be collected together when the trace is GC'd).
+        def subscribe_root_finish(trace_op, state)
+          events = trace_op.send(:events)
+          # `span_before_finish` fires `(span_op, trace_op)` while the span can
+          # still be enriched (before it is finalized into an immutable Span).
+          # The block is the tracer-callback boundary and runs long after
+          # `#capture` returns, so it rescues on its own — enrichment must never
+          # raise into the trace pipeline. (Errors setting up the subscription
+          # here propagate to `#capture`'s rescue, since this runs under it.)
+          events.span_before_finish.subscribe do |span_op, finishing_trace_op|
+            # `span_before_finish` fires for EVERY span in the trace, and in any
+            # nested trace the child spans finish before the local root. Only the
+            # local root's finish may write tags AND clean up per-trace state:
+            # acting on a child finish would wipe the state before the root
+            # is written. Guard here so `write_tags_on_root` (and its cleanup) only
+            # ever runs for the local root.
+            next unless span_op.equal?(finishing_trace_op.send(:root_span))
+
+            write_tags_on_root(span_op, finishing_trace_op, state)
+          rescue => e
+            @logger.debug { "Error writing span enrichment tags: #{e.class}: #{e.message}" }
+          end
+        end
+
+        def write_tags_on_root(span_op, trace_op, state)
+          # Snapshot the tags under the lock so a concurrent `#capture` on another
+          # thread cannot mutate the state's Sets/Hashes while we encode.
+          tags = @mutex.synchronize do
+            # After shutdown the store is cleared, but this trace's subscription
+            # closure still holds the state; write only while active so a provider
+            # close/reconfigure never emits stale `ffe_*` tags on an open trace.
+            if @active && state.has_data?
+              state.to_span_tags
+            else
+              {}
+            end
+          ensure
+            # The caller only invokes this on the local root's finish, so cleanup
+            # runs exactly once per trace. In an `ensure` so abandoned state is
+            # still freed if encoding ever raises.
+            @store.delete(trace_op)
+          end
+
+          tags.each { |key, value| span_op.set_tag(key, value) }
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/metrics/flag_eval_metrics.rb

@@ -5,28 +5,28 @@ module Datadog
     module Metrics
       # Records flag evaluation metrics via OpenTelemetry
       class FlagEvalMetrics
-        METER_NAME = 'ddtrace.openfeature'
-        METRIC_NAME = 'feature_flag.evaluations'
-        METRIC_UNIT = '{evaluation}'
-        METRIC_DESCRIPTION = 'Number of feature flag evaluations'
+        METER_NAME = "ddtrace.openfeature"
+        METRIC_NAME = "feature_flag.evaluations"
+        METRIC_UNIT = "{evaluation}"
+        METRIC_DESCRIPTION = "Number of feature flag evaluations"
 
-        ATTR_FLAG_KEY = 'feature_flag.key'
-        ATTR_VARIANT = 'feature_flag.result.variant'
-        ATTR_REASON = 'feature_flag.result.reason'
-        ATTR_ALLOCATION_KEY = 'feature_flag.result.allocation_key'
-        ATTR_ERROR_TYPE = 'error.type'
+        ATTR_FLAG_KEY = "feature_flag.key"
+        ATTR_VARIANT = "feature_flag.result.variant"
+        ATTR_REASON = "feature_flag.result.reason"
+        ATTR_ALLOCATION_KEY = "feature_flag.result.allocation_key"
+        ATTR_ERROR_TYPE = "error.type"
 
-        DEFAULT_ERROR_TYPE = 'general'
+        DEFAULT_ERROR_TYPE = "general"
 
         ERROR_TYPE_MAP = {
-          'FLAG_NOT_FOUND' => 'flag_not_found',
-          'TYPE_MISMATCH' => 'type_mismatch',
-          'PARSE_ERROR' => 'parse_error',
-          'PROVIDER_NOT_READY' => 'provider_not_ready',
-          'TARGETING_KEY_MISSING' => 'targeting_key_missing',
-          'INVALID_CONTEXT' => 'invalid_context',
-          'PROVIDER_FATAL' => 'provider_fatal',
-          'GENERAL' => DEFAULT_ERROR_TYPE,
+          "FLAG_NOT_FOUND" => "flag_not_found",
+          "TYPE_MISMATCH" => "type_mismatch",
+          "PARSE_ERROR" => "parse_error",
+          "PROVIDER_NOT_READY" => "provider_not_ready",
+          "TARGETING_KEY_MISSING" => "targeting_key_missing",
+          "INVALID_CONTEXT" => "invalid_context",
+          "PROVIDER_FATAL" => "provider_fatal",
+          "GENERAL" => DEFAULT_ERROR_TYPE,
         }.freeze
 
         # Reasons that should not include allocation_key in metrics
@@ -40,7 +40,7 @@ module Datadog
           @mutex = Mutex.new
 
           unless @enabled
-            @logger.debug { 'OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled' }
+            @logger.debug { "OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled" }
           end
         end
 
@@ -60,7 +60,7 @@ module Datadog
           counter.add(1, attributes: attributes)
         rescue => e
           @logger.debug { "OpenFeature: Failed to record evaluation metric: #{e.class}: #{e.message}" }
-          @telemetry.report(e, description: 'OpenFeature: Failed to record evaluation metric')
+          @telemetry.report(e, description: "OpenFeature: Failed to record evaluation metric")
         end
 
         private
@@ -92,9 +92,9 @@ module Datadog
           meter_provider = defined?(::OpenTelemetry) ? ::OpenTelemetry.meter_provider : nil
           return meter_provider if sdk_meter_provider?(meter_provider)
 
-          @logger.debug { 'OpenFeature: Initializing OTel meter provider directly' }
-          require 'opentelemetry-metrics-sdk'
-          require 'datadog/opentelemetry/metrics'
+          @logger.debug { "OpenFeature: Initializing OTel meter provider directly" }
+          require "opentelemetry-metrics-sdk"
+          require "datadog/opentelemetry/metrics"
           Datadog::OpenTelemetry::Metrics.initialize!(Datadog.send(:components))
 
           meter_provider = ::OpenTelemetry.meter_provider
@@ -133,7 +133,7 @@ module Datadog
 
         def normalize_reason(reason)
           reason = reason.to_s
-          reason.empty? ? 'unknown' : reason.downcase
+          reason.empty? ? "unknown" : reason.downcase
         end
 
         def normalize_error_type(error_code)

data/lib/datadog/open_feature/native_evaluator.rb

@@ -1,22 +1,25 @@
 # frozen_string_literal: true
 
-require_relative '../core/feature_flags'
-require_relative 'ext'
-require_relative 'resolution_details'
+require_relative "../core/feature_flags"
+require_relative "ext"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
     # This class is an interface of evaluation logic using native extension
     class NativeEvaluator
-      INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE = 'flag configuration is invalid or unsupported'
+      INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE = "flag configuration is invalid or unsupported"
 
       # NOTE: In a currect implementation configuration is expected to be a raw
       #       JSON string containing feature flags (straight from the remote config)
       #       in the format expected by `libdatadog` without any modifications
       def initialize(configuration)
         @configuration = Core::FeatureFlags::Configuration.new(configuration)
+        @observe_full_evaluation_data = @configuration.observe_full_evaluation_data
       end
 
+      attr_reader :observe_full_evaluation_data
+
       # Returns the assignment for a given flag key based on the feature flags
       # configuration
       #
@@ -27,21 +30,32 @@ module Datadog
       # @param context [Hash] The context of the evaluation, containing targeting key
       #                       and other attributes
       #
-      # @return [Core::FeatureFlags::ResolutionDetails] The assignment for the flag
+      # @return [ResolutionDetails] The assignment for the flag
       def get_assignment(flag_key, default_value:, expected_type:, context:)
         result = @configuration.get_assignment(flag_key, expected_type, context)
 
         return invalid_flag_configuration_error(default_value) if invalid_flag_configuration?(result)
 
-        # NOTE: This is a special case when we need to fallback to the default
-        #       value, even tho the evaluation itself doesn't produce an error
-        #       resolution details
-        result.value = default_value if result.variant.nil?
-        result
+        build_resolution_details(result, default_value)
       end
 
       private
 
+      def build_resolution_details(result, default_value)
+        ResolutionDetails.new(
+          value: result.variant.nil? ? default_value : result.value,
+          reason: result.reason,
+          variant: result.variant,
+          error_code: result.error_code,
+          error_message: result.error_message,
+          flag_metadata: result.flag_metadata,
+          allocation_key: result.allocation_key,
+          serial_id: result.serial_id,
+          log?: result.log?,
+          error?: result.error?,
+        )
+      end
+
       def invalid_flag_configuration?(result)
         result.reason == Ext::DEFAULT &&
           result.error_code.nil? &&

data/lib/datadog/open_feature/noop_evaluator.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require_relative 'resolution_details'
+require_relative "ext"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
     # This class is a noop interface of evaluation logic
     class NoopEvaluator
+      # Privacy-preserving default before configuration is present.
+      def observe_full_evaluation_data
+        false
+      end
+
       def initialize(_configuration)
         # no-op
       end
@@ -17,7 +22,7 @@ module Datadog
           log?: false,
           error?: true,
           error_code: Ext::PROVIDER_NOT_READY,
-          error_message: 'Waiting for flags configuration',
+          error_message: "Waiting for flags configuration",
           reason: Ext::ERROR
         )
       end