datadog 2.28.0 → 2.41.0

data/lib/datadog/open_feature/component.rb

@@ -1,31 +1,36 @@
 # frozen_string_literal: true
 
-require_relative 'transport'
-require_relative 'evaluation_engine'
-require_relative 'exposures/buffer'
-require_relative 'exposures/worker'
-require_relative 'exposures/deduplicator'
-require_relative 'exposures/reporter'
+require_relative "transport"
+require_relative "evaluation_engine"
+require_relative "exposures/buffer"
+require_relative "exposures/worker"
+require_relative "exposures/deduplicator"
+require_relative "exposures/reporter"
+require_relative "metrics/flag_eval_metrics"
+require_relative "flag_evaluation/writer"
+require_relative "hooks/flag_eval_metrics_hook"
+require_relative "hooks/flag_eval_evp_hook"
+require_relative "hooks/span_enrichment_hook"
 
 module Datadog
   module OpenFeature
     # This class is the entry point for the OpenFeature component
     class Component
-      attr_reader :engine
+      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_hook, :span_enrichment_hook
 
       def self.build(settings, agent_settings, logger:, telemetry:)
         return unless settings.respond_to?(:open_feature) && settings.open_feature.enabled
 
         unless settings.respond_to?(:remote) && settings.remote.enabled
-          message = 'OpenFeature could not be enabled as Remote Configuration is currently disabled. ' \
-            'To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/.'
+          message = "OpenFeature could not be enabled as Remote Configuration is currently disabled. " \
+            "To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/."
 
           logger.warn(message)
           return
         end
 
-        if RUBY_ENGINE != 'ruby'
-          message = 'OpenFeature could not be enabled as MRI is required, ' \
+        if RUBY_ENGINE != "ruby"
+          message = "OpenFeature could not be enabled as MRI is required, " \
             "but running on #{RUBY_ENGINE.inspect}"
 
           logger.warn(message)
@@ -33,9 +38,9 @@ module Datadog
         end
 
         if (libdatadog_api_failure = Core::LIBDATADOG_API_FAILURE)
-          message = 'OpenFeature could not be enabled as `libdatadog` is not loaded: ' \
+          message = "OpenFeature could not be enabled as `libdatadog` is not loaded: " \
             "#{libdatadog_api_failure.inspect}. For help solving this issue, " \
-            'please contact Datadog support at https://docs.datadoghq.com/help/.'
+            "please contact Datadog support at https://docs.datadoghq.com/help/."
 
           logger.warn(message)
           return
@@ -50,10 +55,54 @@ module Datadog
 
         reporter = Exposures::Reporter.new(@worker, telemetry: telemetry, logger: logger)
         @engine = EvaluationEngine.new(reporter, telemetry: telemetry, logger: logger)
+
+        @telemetry = telemetry
+        @logger = logger
+        @settings = settings
+        @agent_settings = agent_settings
+        @flag_eval_metrics_hook = create_flag_eval_metrics_hook
+        @flag_eval_evp_hook = create_flag_eval_evp_hook
+        @span_enrichment_hook = create_span_enrichment_hook
       end
 
       def shutdown!
         @worker.graceful_shutdown
+        @flag_eval_evp_writer&.stop
+        # Symmetric teardown: drop any accumulated span-enrichment state and
+        # subscriptions (Ruby CLAUDE.md mandates closing resources).
+        @span_enrichment_hook&.shutdown
+      end
+
+      private
+
+      def create_flag_eval_metrics_hook
+        return unless Hooks::FlagEvalMetricsHook.available?
+
+        metrics = Metrics::FlagEvalMetrics.new(telemetry: @telemetry, logger: @logger)
+        Hooks::FlagEvalMetricsHook.new(metrics)
+      end
+
+      # Killswitch: DD_FLAGGING_EVALUATION_COUNTS_ENABLED (default on) gates only the EVP path.
+      # Read through the datadog config registry, not raw ENV.
+      def create_flag_eval_evp_hook
+        return unless @settings.open_feature.evaluation_counts_enabled
+        return unless Hooks::FlagEvalEVPHook.available?
+
+        evp_transport = Transport::HTTP.build_flagevaluations(
+          agent_settings: @agent_settings,
+          logger: @logger,
+        )
+        @flag_eval_evp_writer = FlagEvaluation::Writer.new(transport: evp_transport, logger: @logger, telemetry: @telemetry)
+        Hooks::FlagEvalEVPHook.new(@flag_eval_evp_writer)
+      end
+
+      # Construct the span-enrichment hook only when the opt-in gate is on, so
+      # there is no idle per-span overhead when disabled.
+      def create_span_enrichment_hook
+        return unless @settings.open_feature.span_enrichment_enabled
+
+        store = Hooks::SpanEnrichmentHook::SpanEnrichmentStateStore.new
+        Hooks::SpanEnrichmentHook.new(store, logger: @logger)
       end
     end
   end

data/lib/datadog/open_feature/configuration.rb

@@ -12,12 +12,35 @@ module Datadog
 
         def self.add_settings!(base)
           base.class_eval do
+            # Steep does not update `self` for this `class_eval` block.
+            # @type self: Datadog::Core::Configuration::Base::_DslContext
             settings :open_feature do
               option :enabled do |o|
                 o.type :bool
-                o.env 'DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED'
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED"
                 o.default false
               end
+
+              # Opt-in gate for APM feature-flag span enrichment. When enabled,
+              # the provider attaches `ffe_*` tags to the local root APM span on
+              # finish. Distinct from `:enabled` (the provider gate) and off by
+              # default so it can be rolled out independently.
+              #
+              # TODO: benchmark the per-span-finish overhead on a high-span-count
+              # trace with this gate on before enabling it by default.
+              option :span_enrichment_enabled do |o|
+                o.type :bool
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED"
+                o.default false
+              end
+
+              # Killswitch for the EVP `flagevaluation` emission path only. Default on; when
+              # disabled the existing OTel `feature_flag.evaluations` metric is unaffected.
+              option :evaluation_counts_enabled do |o|
+                o.type :bool
+                o.env "DD_FLAGGING_EVALUATION_COUNTS_ENABLED"
+                o.default true
+              end
             end
           end
         end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require_relative 'noop_evaluator'
-require_relative 'native_evaluator'
-require_relative 'resolution_details'
+require_relative "ext"
+require_relative "noop_evaluator"
+require_relative "native_evaluator"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
@@ -39,10 +39,10 @@ module Datadog
 
         result
       rescue => e
-        @telemetry.report(e, description: 'OpenFeature: Failed to fetch flag value')
+        @telemetry.report(e, description: "OpenFeature: Failed to fetch flag value")
 
         ResolutionDetails.build_error(
-          value: default_value, error_code: Ext::GENERAL, error_message: e.message
+          value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
         )
       end
 
@@ -51,19 +51,19 @@ module Datadog
       #       in the format expected by `libdatadog` without any modifications
       def reconfigure!(configuration)
         if configuration.nil?
-          @logger.debug('OpenFeature: Removing configuration')
+          @logger.debug("OpenFeature: Removing configuration")
 
           return @evaluator = NoopEvaluator.new(configuration)
         end
 
         @evaluator = NativeEvaluator.new(configuration)
       rescue => e
-        message = 'OpenFeature: Failed to reconfigure, reverting to the previous configuration'
+        message = "OpenFeature: Failed to reconfigure, reverting to the previous configuration"
 
         @logger.error("#{message}, #{e.class}: #{e.message}")
         @telemetry.report(e, description: "#{message} (#{e.class})")
 
-        raise ReconfigurationError, e.message
+        raise ReconfigurationError, "#{e.class}: #{e.message}"
       end
     end
   end

data/lib/datadog/open_feature/exposures/batch_builder.rb

@@ -12,7 +12,7 @@ module Datadog
         def payload_for(events)
           {
             context: @context,
-            exposures: events
+            exposures: events,
           }
         end
 

data/lib/datadog/open_feature/exposures/buffer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../core/buffer/cruby'
+require_relative "../../core/buffer/cruby"
 
 module Datadog
   module OpenFeature

data/lib/datadog/open_feature/exposures/deduplicator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/lru_cache'
+require_relative "../../core/utils/lru_cache"
 
 module Datadog
   module OpenFeature

data/lib/datadog/open_feature/exposures/event.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/time'
+require_relative "../../core/utils/time"
 
 module Datadog
   module OpenFeature
     module Exposures
       # A data model for an exposure event
       module Event
-        TARGETING_KEY_FIELD = 'targeting_key'
+        TARGETING_KEY_FIELD = "targeting_key"
         ALLOWED_FIELD_TYPES = [String, Integer, Float, TrueClass, FalseClass].freeze
 
         class << self
@@ -23,18 +23,18 @@ module Datadog
             {
               timestamp: current_timestamp_ms,
               allocation: {
-                key: result.allocation_key
+                key: result.allocation_key,
               },
               flag: {
-                key: flag_key
+                key: flag_key,
               },
               variant: {
-                key: result.variant
+                key: result.variant,
               },
               subject: {
                 id: context.targeting_key,
-                attributes: extract_attributes(context)
-              }
+                attributes: extract_attributes(context),
+              },
             }.freeze
           end
 

data/lib/datadog/open_feature/exposures/reporter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'event'
-require_relative 'deduplicator'
+require_relative "event"
+require_relative "deduplicator"
 
 module Datadog
   module OpenFeature
@@ -30,7 +30,7 @@ module Datadog
           @worker.enqueue(event)
         rescue => e
           @logger.debug { "OpenFeature: Failed to report resolution details: #{e.class}: #{e.message}" }
-          @telemetry.report(e, description: 'OpenFeature: Failed to report resolution details')
+          @telemetry.report(e, description: "OpenFeature: Failed to report resolution details")
 
           false
         end

data/lib/datadog/open_feature/exposures/worker.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/time'
-require_relative '../../core/workers/queue'
-require_relative '../../core/workers/polling'
+require_relative "../../core/utils/time"
+require_relative "../../core/workers/queue"
+require_relative "../../core/workers/polling"
 
-require_relative 'buffer'
-require_relative 'batch_builder'
+require_relative "buffer"
+require_relative "batch_builder"
 
 module Datadog
   module OpenFeature
@@ -106,7 +106,7 @@ module Datadog
           response
         rescue => e
           @logger.debug { "OpenFeature: Failed to flush resolution details events: #{e.class}: #{e.message}" }
-          @telemetry.report(e, description: 'OpenFeature: Failed to flush resolution details events')
+          @telemetry.report(e, description: "OpenFeature: Failed to flush resolution details events")
 
           nil
         end

data/lib/datadog/open_feature/ext.rb

@@ -3,12 +3,19 @@
 module Datadog
   module OpenFeature
     module Ext
-      ERROR = 'ERROR'
-      INITIALIZING = 'INITIALIZING'
-      UNKNOWN_TYPE = 'UNKNOWN_TYPE'
-      GENERAL = 'GENERAL'
-      PROVIDER_FATAL = 'PROVIDER_FATAL'
-      PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
+      ERROR = "ERROR"
+      DEFAULT = "DEFAULT"
+      INITIALIZING = "INITIALIZING"
+      UNKNOWN_TYPE = "UNKNOWN_TYPE"
+      PARSE_ERROR = "PARSE_ERROR"
+      GENERAL = "GENERAL"
+      PROVIDER_FATAL = "PROVIDER_FATAL"
+      PROVIDER_NOT_READY = "PROVIDER_NOT_READY"
+
+      # Flag-metadata key under which the provider threads the assignment's
+      # allocation key to the flag-evaluation hooks. The wire string is the
+      # value so the writer (provider) and readers (EVP/metrics hooks) can't drift.
+      METADATA_ALLOCATION_KEY = "__dd_allocation_key"
     end
   end
 end

data/lib/datadog/open_feature/flag_evaluation/aggregator.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module FlagEvaluation
+      # Two-tier aggregation for EVP flagevaluation events.
+      #
+      # Two-tier design:
+      # - full-tier  key: (flag_key, variant, allocation_key, runtime_default, error_message, targeting_key, canonical_context_key)
+      # - degraded-tier key: (flag_key, variant, allocation_key, runtime_default, error_message)
+      # - Drop-and-count when degraded tier is full
+      # - canonical_context_key: sorted type-tagged length-delimited encoding (no hash digest)
+      # - Caps: global_cap=131_072 / per_flag_cap=10_000 / degraded_cap=32_768
+      # - Context pruning: 256 fields / 256 chars (matches flageval-worker backend limits)
+      class Aggregator
+        MAX_CONTEXT_FIELDS = 256
+        MAX_FIELD_LENGTH = 256
+        MAX_CONTEXT_DEPTH = 32
+
+        # Type tags so values of different Ruby types never collide in the canonical key.
+        CTX_TAG_STRING = "s"
+        CTX_TAG_BOOL = "b"
+        CTX_TAG_INTEGER = "i"
+        CTX_TAG_FLOAT = "f"
+        CTX_TAG_OTHER = "o"
+
+        EVAL_SCALE_TARGET_FLAGS = 2_500
+        EVAL_SCALE_FULL_BUCKETS_PER_FLAG = 50
+        EVAL_SCALE_USERS_PER_FLAG = 1_000
+        EVAL_SCALE_PER_FLAG_HEADROOM_MULTIPLIER = 10
+        EVAL_SCALE_DEGRADED_BUCKETS_PER_FLAG = 10
+        EVAL_SCALE_FULL_BUCKET_TARGET = EVAL_SCALE_TARGET_FLAGS * EVAL_SCALE_FULL_BUCKETS_PER_FLAG
+        EVAL_SCALE_PER_FLAG_BUCKET_TARGET = EVAL_SCALE_PER_FLAG_HEADROOM_MULTIPLIER * EVAL_SCALE_USERS_PER_FLAG
+        EVAL_SCALE_DEGRADED_BUCKET_TARGET = EVAL_SCALE_TARGET_FLAGS * EVAL_SCALE_DEGRADED_BUCKETS_PER_FLAG
+
+        DEFAULT_GLOBAL_CAP = 131_072
+        DEFAULT_PER_FLAG_CAP = EVAL_SCALE_PER_FLAG_BUCKET_TARGET
+        DEFAULT_DEGRADED_CAP = 32_768
+
+        attr_reader :dropped_degraded_overflow
+
+        def initialize(
+          global_cap: DEFAULT_GLOBAL_CAP,
+          per_flag_cap: DEFAULT_PER_FLAG_CAP,
+          degraded_cap: DEFAULT_DEGRADED_CAP
+        )
+          @global_cap = global_cap
+          @per_flag_cap = per_flag_cap
+          @degraded_cap = degraded_cap
+
+          @mutex = Mutex.new
+          # full-tier: Array key -> Hash entry
+          @full = {}
+          # degraded-tier: Array key -> Hash entry
+          @degraded = {}
+          # per-flag full-bucket count for per_flag_cap enforcement
+          @per_flag_full = Hash.new(0)
+          @global_count = 0
+          @dropped_degraded_overflow = 0
+        end
+
+        # Record one evaluation event. Thread-safe. Called from the background writer.
+        def record(
+          flag_key:, variant:, allocation_key:, targeting_key:, eval_time_ms:, attrs:, error_message: nil,
+          runtime_default: nil
+        )
+          runtime_default = variant.nil? if runtime_default.nil?
+          runtime_default = !!runtime_default
+
+          # Normalize nil/empty strings
+          variant = variant.to_s
+          allocation_key = allocation_key.to_s
+          error_message = error_message.to_s
+          targeting_key = targeting_key.to_s
+
+          # Context pruning + canonical key (see prune_context and canonical_context_key).
+          # Runs in the background writer so caller eval threads do not pay the flatten/prune cost.
+          pruned_context = prune_context(attrs)
+          context_key = canonical_context_key(pruned_context)
+
+          full_key = [flag_key, variant, allocation_key, runtime_default, error_message, targeting_key, context_key]
+          evaluation_time_ms = eval_time_ms.to_i
+
+          @mutex.synchronize do
+            # --- Full tier ---
+            if (entry = @full[full_key])
+              observe(entry, evaluation_time_ms)
+              return
+            end
+
+            per_flag_count = @per_flag_full[flag_key]
+            if per_flag_count >= @per_flag_cap
+              add_to_degraded(flag_key, variant, allocation_key, runtime_default, error_message, evaluation_time_ms)
+              return
+            end
+
+            # Count the full-tier attempt before checking the global cap so per-flag overflow stays
+            # active even when the global full-tier cap is already saturated.
+            @per_flag_full[flag_key] = per_flag_count + 1
+
+            if @global_count < @global_cap
+              entry = new_entry(
+                evaluation_time_ms,
+                runtime_default: runtime_default,
+                error_message: error_message,
+                targeting_key: targeting_key,
+                context_attrs: pruned_context
+              )
+              @full[full_key] = entry
+              @global_count += 1
+            else
+              # Route to degraded tier
+              add_to_degraded(flag_key, variant, allocation_key, runtime_default, error_message, evaluation_time_ms)
+            end
+          end
+        end
+
+        # Flush aggregation maps, reset state, return snapshot.
+        # Returns { full: Hash, degraded: Hash, dropped_degraded_overflow: Integer }.
+        # The overflow count is included in the snapshot so the caller can EMIT it before it is
+        # reset — the count is never reset-without-emit (backpressure stays observable).
+        def flush_and_reset
+          @mutex.synchronize do
+            full_snapshot = @full
+            degraded_snapshot = @degraded
+            dropped_snapshot = @dropped_degraded_overflow
+
+            @full = {}
+            @degraded = {}
+            @per_flag_full = Hash.new(0)
+            @global_count = 0
+            @dropped_degraded_overflow = 0
+
+            {full: full_snapshot, degraded: degraded_snapshot, dropped_degraded_overflow: dropped_snapshot}
+          end
+        end
+
+        # Prune context: keep first MAX_CONTEXT_FIELDS fields (sorted), skip string values >256 chars.
+        # Keys are sorted before pruning to ensure deterministic subset selection.
+        def prune_context(attrs)
+          self.class.prune_context(attrs)
+        end
+
+        def self.prune_context(attrs)
+          flattened_context = flatten_context(attrs)
+          return {} if flattened_context.empty?
+
+          pruned_context = {}
+          count = 0
+          flattened_context.keys.sort.each do |key|
+            break if count >= MAX_CONTEXT_FIELDS
+
+            value = flattened_context[key]
+            # Skip oversized string values (mirrors flageval-worker pruning behavior).
+            next if value.is_a?(String) && value.length > MAX_FIELD_LENGTH
+
+            pruned_context[key] = value
+            count += 1
+          end
+          pruned_context
+        end
+
+        def self.flatten_context(attrs)
+          return {} unless attrs.is_a?(Hash) && !attrs.empty?
+
+          flattened_context = {}
+          seen = {attrs.object_id => true}
+          attrs.each do |key, value|
+            flatten_value(key.to_s, value, flattened_context, seen, 0)
+          end
+          flattened_context
+        end
+
+        # Canonical context key: sorted type-tagged length-delimited encoding.
+        # Each field is: 8-byte big-endian key length + key bytes + type-tag byte +
+        #                8-byte big-endian value length + value bytes.
+        # No hash digest — the key IS the full encoding (collision-free, no FNV).
+        def canonical_context_key(attrs)
+          return "" if attrs.nil? || attrs.empty?
+
+          buffer = String.new("", encoding: Encoding::BINARY)
+          attrs.keys.sort.each do |key|
+            value = attrs[key]
+            buffer << length_delimited(key.to_s)
+            buffer << context_value_bytes(value)
+          end
+          buffer
+        end
+
+        def self.flatten_value(prefix, value, output, seen, depth)
+          return if depth > MAX_CONTEXT_DEPTH
+
+          case value
+          when Hash
+            object_id = value.object_id
+            return if seen[object_id]
+
+            seen[object_id] = true
+            value.each do |key, child_value|
+              flatten_value("#{prefix}.#{key}", child_value, output, seen, depth + 1)
+            end
+            seen.delete(object_id)
+          when Array
+            object_id = value.object_id
+            return if seen[object_id]
+
+            seen[object_id] = true
+            value.each_with_index do |child_value, index|
+              flatten_value("#{prefix}.#{index}", child_value, output, seen, depth + 1)
+            end
+            seen.delete(object_id)
+          else
+            output[prefix] = value unless value.nil?
+          end
+        end
+        private_class_method :flatten_value
+
+        private
+
+        def context_value_bytes(value)
+          tag, encoded = case value
+          when String then [CTX_TAG_STRING, value.to_s]
+          when TrueClass, FalseClass then [CTX_TAG_BOOL, value.to_s]
+          when Integer then [CTX_TAG_INTEGER, value.to_s]
+          when Float then [CTX_TAG_FLOAT, value.to_s]
+          else [CTX_TAG_OTHER, value.to_s]
+          end
+          String.new(tag, encoding: Encoding::BINARY) + length_delimited(encoded)
+        end
+
+        # 8-byte big-endian length prefix + raw bytes. Unambiguous field boundary.
+        def length_delimited(string)
+          bytes = string.encode(Encoding::BINARY, invalid: :replace, undef: :replace)
+          byte_length = bytes.bytesize
+          # Build 8-byte big-endian length
+          length_bytes = String.new("", encoding: Encoding::BINARY)
+          8.times do |index|
+            length_bytes.prepend(((byte_length >> (8 * index)) & 0xFF).chr(Encoding::BINARY))
+          end
+          length_bytes + bytes
+        end
+
+        def new_entry(evaluation_time_ms, runtime_default:, error_message: nil, targeting_key: nil, context_attrs: nil)
+          {
+            count: 1,
+            first_evaluation: evaluation_time_ms,
+            last_evaluation: evaluation_time_ms,
+            runtime_default: runtime_default,
+            error_message: error_message,
+            targeting_key: targeting_key,
+            context_attrs: context_attrs,
+          }
+        end
+
+        def observe(entry, evaluation_time_ms)
+          entry[:count] += 1
+          entry[:first_evaluation] = evaluation_time_ms if evaluation_time_ms < entry[:first_evaluation]
+          entry[:last_evaluation] = evaluation_time_ms if evaluation_time_ms > entry[:last_evaluation]
+        end
+
+        def add_to_degraded(flag_key, variant, allocation_key, runtime_default, error_message, evaluation_time_ms)
+          degraded_key = [flag_key, variant, allocation_key, runtime_default, error_message]
+
+          if (entry = @degraded[degraded_key])
+            observe(entry, evaluation_time_ms)
+            return
+          end
+
+          # New degraded bucket — check degraded_cap (terminal tier)
+          if @degraded.size >= @degraded_cap
+            # Terminal tier full — drop and count (explicit overflow counter)
+            @dropped_degraded_overflow += 1
+            return
+          end
+
+          # Degraded entry omits targeting_key + context_attrs (schema omitempty fields)
+          @degraded[degraded_key] = new_entry(
+            evaluation_time_ms,
+            runtime_default: runtime_default,
+            error_message: error_message
+          )
+        end
+      end
+    end
+  end
+end