datadog 2.17.0 → 2.37.0

data/lib/datadog/open_feature/component.rb

@@ -0,0 +1,100 @@
+# 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 'metrics/flag_eval_metrics'
+
+module Datadog
+  module OpenFeature
+    # This class is the entry point for the OpenFeature component
+    class Component
+      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_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/.'
+
+          logger.warn(message)
+          return
+        end
+
+        if RUBY_ENGINE != 'ruby'
+          message = 'OpenFeature could not be enabled as MRI is required, ' \
+            "but running on #{RUBY_ENGINE.inspect}"
+
+          logger.warn(message)
+          return
+        end
+
+        if (libdatadog_api_failure = Core::LIBDATADOG_API_FAILURE)
+          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/.'
+
+          logger.warn(message)
+          return
+        end
+
+        new(settings, agent_settings, logger: logger, telemetry: telemetry)
+      end
+
+      def initialize(settings, agent_settings, logger:, telemetry:)
+        transport = Transport::HTTP.build(agent_settings: agent_settings, logger: logger)
+        @worker = Exposures::Worker.new(settings: settings, transport: transport, telemetry: telemetry, logger: logger)
+
+        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
+      end
+
+      def shutdown!
+        @worker.graceful_shutdown
+        @flag_eval_evp_writer&.stop
+      end
+
+      private
+
+      def create_flag_eval_metrics_hook
+        require_relative 'hooks/flag_eval_metrics_hook'
+        return unless Hooks::FlagEvalMetricsHook.available?
+
+        metrics = Metrics::FlagEvalMetrics.new(telemetry: @telemetry, logger: @logger)
+        Hooks::FlagEvalMetricsHook.new(metrics)
+      rescue LoadError
+        nil
+      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
+
+        require_relative 'hooks/flag_eval_evp_hook'
+        return unless Hooks::FlagEvalEVPHook.available?
+
+        evp_transport = Transport::HTTP.build_flagevaluations(
+          agent_settings: @agent_settings,
+          logger: @logger,
+        )
+        require_relative 'flag_evaluation/writer'
+        @flag_eval_evp_writer = FlagEvaluation::Writer.new(transport: evp_transport, logger: @logger, telemetry: @telemetry)
+        Hooks::FlagEvalEVPHook.new(@flag_eval_evp_writer)
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      # A settings class for the OpenFeature component.
+      module Settings
+        def self.extended(base)
+          base = base.singleton_class unless base.is_a?(Class)
+          add_settings!(base)
+        end
+
+        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.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
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+require_relative 'noop_evaluator'
+require_relative 'native_evaluator'
+require_relative 'resolution_details'
+
+module Datadog
+  module OpenFeature
+    # This class performs the evaluation of the feature flag
+    class EvaluationEngine
+      # Steep: https://github.com/soutaro/steep/issues/1880
+      ReconfigurationError = Class.new(StandardError) # steep:ignore IncompatibleAssignment
+
+      ALLOWED_TYPES = %i[boolean string number float integer object].freeze
+
+      def initialize(reporter, telemetry:, logger:)
+        @reporter = reporter
+        @telemetry = telemetry
+        @logger = logger
+
+        @evaluator = NoopEvaluator.new(nil)
+      end
+
+      def fetch_value(flag_key, default_value:, expected_type:, evaluation_context: nil)
+        unless ALLOWED_TYPES.include?(expected_type)
+          message = "unknown type #{expected_type.inspect}, allowed types #{ALLOWED_TYPES.join(", ")}"
+          return ResolutionDetails.build_error(
+            value: default_value, error_code: Ext::UNKNOWN_TYPE, error_message: message
+          )
+        end
+
+        context = evaluation_context&.fields.to_h
+        result = @evaluator.get_assignment(
+          flag_key, default_value: default_value, context: context, expected_type: expected_type
+        )
+
+        @reporter.report(result, flag_key: flag_key, context: evaluation_context)
+
+        result
+      rescue => e
+        @telemetry.report(e, description: 'OpenFeature: Failed to fetch flag value')
+
+        ResolutionDetails.build_error(
+          value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
+        )
+      end
+
+      # 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 reconfigure!(configuration)
+        if configuration.nil?
+          @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'
+
+        @logger.error("#{message}, #{e.class}: #{e.message}")
+        @telemetry.report(e, description: "#{message} (#{e.class})")
+
+        raise ReconfigurationError, "#{e.class}: #{e.message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Exposures
+      # This class builds a batch of exposures and context to be sent to the Agent
+      class BatchBuilder
+        def initialize(settings)
+          @context = build_context(settings)
+        end
+
+        def payload_for(events)
+          {
+            context: @context,
+            exposures: events
+          }
+        end
+
+        private
+
+        def build_context(settings)
+          context = {}
+          context[:env] = settings.env if settings.env
+          context[:service] = settings.service if settings.service
+          context[:version] = settings.version if settings.version
+
+          context
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../../core/buffer/cruby'
+
+module Datadog
+  module OpenFeature
+    module Exposures
+      # This class is a buffer for exposure events that evicts at random and
+      # keeps track of the number of dropped events
+      #
+      # WARNING: This class does not work as intended on JRuby
+      class Buffer < Core::Buffer::CRuby
+        DEFAULT_LIMIT = 1_000
+
+        attr_reader :dropped_count
+
+        def initialize(limit = DEFAULT_LIMIT)
+          @dropped = 0
+          @dropped_count = 0
+
+          super
+        end
+
+        protected
+
+        def drain!
+          drained = super
+
+          @dropped_count = @dropped
+          @dropped = 0
+
+          drained
+        end
+
+        def replace!(item)
+          @dropped += 1
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../../core/utils/lru_cache'
+
+module Datadog
+  module OpenFeature
+    module Exposures
+      # This class is a deduplication buffer based on LRU cache for exposure events
+      class Deduplicator
+        DEFAULT_CACHE_LIMIT = 1_000
+
+        def initialize(limit: DEFAULT_CACHE_LIMIT)
+          @cache = Datadog::Core::Utils::LRUCache.new(limit)
+          @mutex = Mutex.new
+        end
+
+        def duplicate?(key, value)
+          @mutex.synchronize do
+            stored = @cache[key]
+            return true if stored == value
+
+            @cache[key] = value
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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'
+        ALLOWED_FIELD_TYPES = [String, Integer, Float, TrueClass, FalseClass].freeze
+
+        class << self
+          def cache_key(result, flag_key:, context:)
+            "#{flag_key}:#{context.targeting_key}"
+          end
+
+          def cache_value(result, flag_key:, context:)
+            "#{result.allocation_key}:#{result.variant}"
+          end
+
+          def build(result, flag_key:, context:)
+            {
+              timestamp: current_timestamp_ms,
+              allocation: {
+                key: result.allocation_key
+              },
+              flag: {
+                key: flag_key
+              },
+              variant: {
+                key: result.variant
+              },
+              subject: {
+                id: context.targeting_key,
+                attributes: extract_attributes(context)
+              }
+            }.freeze
+          end
+
+          private
+
+          # NOTE: We take all filds of the context that does not support nesting
+          #       and will ignore targeting key as it will be set as `subject.id`
+          def extract_attributes(context)
+            context.fields.select do |key, value|
+              next false if key == TARGETING_KEY_FIELD
+
+              ALLOWED_FIELD_TYPES.include?(value.class)
+            end
+          end
+
+          def current_timestamp_ms
+            (Datadog::Core::Utils::Time.now.to_f * 1000).to_i
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'deduplicator'
+
+module Datadog
+  module OpenFeature
+    module Exposures
+      # This class is responsible for reporting exposures to the Agent
+      class Reporter
+        def initialize(worker, telemetry:, logger:)
+          @worker = worker
+          @logger = logger
+          @telemetry = telemetry
+          @deduplicator = Deduplicator.new
+        end
+
+        # NOTE: Reporting expects evaluation context to be always present, but it
+        #       might be missing depending on the customer way of using flags evaluation API.
+        #       In addition to that the evaluation result must be marked for reporting.
+        def report(result, flag_key:, context:)
+          return false if context.nil?
+          return false unless result.log?
+
+          key = Event.cache_key(result, flag_key: flag_key, context: context)
+          value = Event.cache_value(result, flag_key: flag_key, context: context)
+          return false if @deduplicator.duplicate?(key, value)
+
+          event = Event.build(result, flag_key: flag_key, context: context)
+          @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')
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative '../../core/utils/time'
+require_relative '../../core/workers/queue'
+require_relative '../../core/workers/polling'
+
+require_relative 'buffer'
+require_relative 'batch_builder'
+
+module Datadog
+  module OpenFeature
+    module Exposures
+      # This class is responsible for sending exposures to the Agent
+      class Worker
+        include Core::Workers::Queue
+        include Core::Workers::Polling
+
+        GRACEFUL_SHUTDOWN_EXTRA_SECONDS = 5
+        GRACEFUL_SHUTDOWN_WAIT_INTERVAL_SECONDS = 0.5
+
+        DEFAULT_FLUSH_INTERVAL_SECONDS = 30
+        DEFAULT_BUFFER_LIMIT = Buffer::DEFAULT_LIMIT
+
+        def initialize(
+          settings:,
+          transport:,
+          telemetry:,
+          logger:,
+          flush_interval_seconds: DEFAULT_FLUSH_INTERVAL_SECONDS,
+          buffer_limit: DEFAULT_BUFFER_LIMIT
+        )
+          @logger = logger
+          @transport = transport
+          @telemetry = telemetry
+          @batch_builder = BatchBuilder.new(settings)
+          @buffer_limit = buffer_limit
+
+          self.buffer = Buffer.new(buffer_limit)
+          self.fork_policy = Core::Workers::Async::Thread::FORK_POLICY_RESTART
+          self.loop_base_interval = flush_interval_seconds
+          self.enabled = true
+        end
+
+        def start
+          return if !enabled? || running?
+
+          perform
+        end
+
+        def stop(force_stop = false, timeout = Core::Workers::Polling::DEFAULT_SHUTDOWN_TIMEOUT)
+          buffer.close if running?
+
+          super
+        end
+
+        def enqueue(event)
+          buffer.push(event)
+          start unless running?
+
+          true
+        end
+
+        def dequeue
+          [buffer.pop, buffer.dropped_count]
+        end
+
+        def perform(*args)
+          events, dropped = args
+          send_events(Array(events), dropped.to_i)
+        end
+
+        def graceful_shutdown
+          return false unless enabled? || !run_loop?
+
+          self.enabled = false
+
+          started = Core::Utils::Time.get_time
+          wait_time = loop_base_interval + GRACEFUL_SHUTDOWN_EXTRA_SECONDS
+
+          loop do
+            break if buffer.empty? && !in_iteration?
+
+            sleep(GRACEFUL_SHUTDOWN_WAIT_INTERVAL_SECONDS)
+            break if Core::Utils::Time.get_time - started > wait_time
+          end
+
+          stop(true)
+        end
+
+        private
+
+        def send_events(events, dropped)
+          return if events.empty?
+
+          if dropped.positive?
+            @logger.debug { "OpenFeature: Resolution details worker dropped #{dropped} event(s) due to full buffer" }
+          end
+
+          payload = @batch_builder.payload_for(events)
+          response = @transport.send_exposures(payload)
+
+          unless response&.ok?
+            @logger.debug { "OpenFeature: Resolution details upload response was not OK: #{response.inspect}" }
+          end
+
+          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')
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/ext.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Ext
+      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'
+    end
+  end
+end