datadog 2.4.0 → 2.44.0

data/lib/datadog/open_feature/configuration/source.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "source/resolution"
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      module Source
+        AGENTLESS = "agentless"
+        REMOTE_CONFIG = "remote_config"
+        OFFLINE = "offline"
+
+        class << self
+          def resolve(settings, logger: Datadog.logger)
+            feature_flags = settings.feature_flags
+            source = resolve_source(feature_flags, legacy: settings.open_feature, logger: logger)
+            enabled = feature_flags.enabled && source != OFFLINE
+
+            Resolution.new(source, enabled: enabled)
+          end
+
+          private
+
+          def resolve_source(settings, legacy:, logger:)
+            configured_source = settings.configuration_source
+            if !settings.using_default?(:configuration_source) && !configured_source.empty?
+              return configured_source if configured_source == AGENTLESS ||
+                configured_source == REMOTE_CONFIG ||
+                configured_source == OFFLINE
+
+              logger.warn("Unsupported Feature Flags configuration source; Feature Flags are disabled")
+              OFFLINE
+            elsif !legacy.using_default?(:enabled)
+              legacy.enabled ? REMOTE_CONFIG : OFFLINE
+            else
+              AGENTLESS
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/configuration.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      # A settings class for the OpenFeature component.
+      module Settings
+        DEFAULT_POLL_INTERVAL_SECONDS = 30
+        DEFAULT_REQUEST_TIMEOUT_SECONDS = 5
+        DEFAULT_INITIALIZATION_TIMEOUT_MS = 30_000
+
+        MAX_REQUEST_TIMEOUT_SECONDS = 300
+        MAX_INITIALIZATION_TIMEOUT_MS = 2_147_483_647
+
+        def self.configure_integer_option(option, environment_variable:, default:, setting_name:)
+          option.type :int
+          option.env environment_variable
+          option.env_parser do |value|
+            Integer(value, 10)
+          rescue ArgumentError
+            Datadog.logger.warn("#{setting_name} must be an integer; using the default")
+            default
+          end
+          option.default default
+        end
+
+        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
+              # Deprecated switch retained for existing Remote Configuration adopters.
+              option :enabled do |o|
+                o.type :bool
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED"
+                o.default false
+                o.after_set do |_, _, precedence|
+                  next if precedence == Core::Configuration::Option::Precedence::DEFAULT
+
+                  Datadog.logger.warn(
+                    "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED is deprecated; use " \
+                    "DD_FEATURE_FLAGS_ENABLED and DD_FEATURE_FLAGS_CONFIGURATION_SOURCE instead"
+                  )
+                end
+              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
+
+            settings :feature_flags do
+              option :enabled do |o|
+                o.type :bool
+                o.env "DD_FEATURE_FLAGS_ENABLED"
+                o.default true
+              end
+
+              option :configuration_source do |o|
+                o.type :string
+                o.env "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE"
+                o.default "agentless"
+                o.setter do |value|
+                  value.to_s.strip.downcase
+                end
+              end
+
+              settings :agentless do
+                option :base_url do |o|
+                  o.type :string, nilable: true
+                  o.env "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL"
+                  o.skip_telemetry true
+                  o.setter do |value|
+                    next unless value
+
+                    stripped_value = value.to_s.strip
+                    stripped_value.empty? ? nil : stripped_value
+                  end
+                end
+
+                option :poll_interval_seconds do |o|
+                  Settings.configure_integer_option(
+                    o,
+                    environment_variable: "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS",
+                    default: Settings::DEFAULT_POLL_INTERVAL_SECONDS,
+                    setting_name: "Feature Flags agentless poll interval",
+                  )
+                  o.setter do |value|
+                    if value.is_a?(Integer) && value > 0
+                      value
+                    else
+                      Datadog.logger.warn(
+                        "Feature Flags agentless poll interval must be positive; using the default"
+                      )
+                      Settings::DEFAULT_POLL_INTERVAL_SECONDS
+                    end
+                  end
+                end
+
+                option :request_timeout_seconds do |o|
+                  Settings.configure_integer_option(
+                    o,
+                    environment_variable: "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS",
+                    default: Settings::DEFAULT_REQUEST_TIMEOUT_SECONDS,
+                    setting_name: "Feature Flags agentless request timeout",
+                  )
+                  o.setter do |value|
+                    if value.is_a?(Integer) && value > 0 && value <= Settings::MAX_REQUEST_TIMEOUT_SECONDS
+                      value
+                    else
+                      Datadog.logger.warn(
+                        "Feature Flags agentless request timeout must be within (0, " \
+                        "#{Settings::MAX_REQUEST_TIMEOUT_SECONDS}]; using the default"
+                      )
+                      Settings::DEFAULT_REQUEST_TIMEOUT_SECONDS
+                    end
+                  end
+                end
+              end
+
+              option :initialization_timeout_ms do |o|
+                Settings.configure_integer_option(
+                  o,
+                  environment_variable: "DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS",
+                  default: Settings::DEFAULT_INITIALIZATION_TIMEOUT_MS,
+                  setting_name: "Feature Flags provider initialization timeout",
+                )
+                o.setter do |value|
+                  if value.is_a?(Integer) && value > 0 && value <= Settings::MAX_INITIALIZATION_TIMEOUT_MS
+                    value
+                  else
+                    Datadog.logger.warn(
+                      "Feature Flags provider initialization timeout must be within (0, " \
+                      "#{Settings::MAX_INITIALIZATION_TIMEOUT_MS}]; using the default"
+                    )
+                    Settings::DEFAULT_INITIALIZATION_TIMEOUT_MS
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -0,0 +1,96 @@
+# 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)
+        # Pre-bound to the safe default so the rescue below can still read it if the
+        # evaluator read itself raises.
+        observe_full_evaluation_data = false
+        # Snapshot the evaluator once: a concurrent reconfigure! must not retroactively
+        # apply a different environment's full-evaluation-data policy to this evaluation.
+        evaluator = @evaluator
+        observe_full_evaluation_data = evaluator.observe_full_evaluation_data == true
+
+        unless ALLOWED_TYPES.include?(expected_type)
+          message = "unknown type #{expected_type.inspect}, allowed types #{ALLOWED_TYPES.join(", ")}"
+          result = ResolutionDetails.build_error(
+            value: default_value, error_code: Ext::UNKNOWN_TYPE, error_message: message
+          )
+
+          return with_observe_full_evaluation_data(result, observe_full_evaluation_data)
+        end
+
+        context = evaluation_context&.fields.to_h
+        result = evaluator.get_assignment(
+          flag_key, default_value: default_value, context: context, expected_type: expected_type
+        )
+
+        result = with_observe_full_evaluation_data(result, observe_full_evaluation_data)
+
+        @reporter.report(result, flag_key: flag_key, context: evaluation_context)
+
+        result
+      rescue => e
+        @telemetry.report(e, description: "OpenFeature: Failed to fetch flag value")
+
+        result = ResolutionDetails.build_error(
+          value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
+        )
+        # `== true` is load-bearing: Steep types this local as `(nil | bool)` in a rescue
+        # body, and coercing at the use site is what narrows it to `bool`.
+        with_observe_full_evaluation_data(result, observe_full_evaluation_data == true)
+      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
+
+      private
+
+      # Stamps observe_full_evaluation_data onto the result metadata so the hook
+      # reads it from the event, not live config.
+      def with_observe_full_evaluation_data(result, observe_full_evaluation_data)
+        result = result.dup if result.frozen?
+        metadata = result.flag_metadata ||= {}
+        metadata[Ext::METADATA_OBSERVE_FULL_EVALUATION_DATA] = observe_full_evaluation_data
+        result
+      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,67 @@
+# 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
+
+          # NOTE: The serial id is part of the value because it can appear or change on a
+          #       configuration refresh while the allocation and the variant stay the same.
+          def cache_value(result, flag_key:, context:)
+            "#{result.allocation_key}:#{result.variant}:#{result.serial_id}"
+          end
+
+          def build(result, flag_key:, context:)
+            event = {
+              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),
+              },
+            }
+
+            serial_id = result.serial_id
+            event[:serial_id] = serial_id unless serial_id.nil?
+
+            event.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,40 @@
+# 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"
+      FLAG_NOT_FOUND = "FLAG_NOT_FOUND"
+      TYPE_MISMATCH = "TYPE_MISMATCH"
+      TARGETING_KEY_MISSING = "TARGETING_KEY_MISSING"
+      INVALID_CONTEXT = "INVALID_CONTEXT"
+
+      STANDARD_ERROR_CODES = [
+        PROVIDER_NOT_READY,
+        FLAG_NOT_FOUND,
+        PARSE_ERROR,
+        TYPE_MISMATCH,
+        TARGETING_KEY_MISSING,
+        INVALID_CONTEXT,
+        PROVIDER_FATAL,
+        GENERAL,
+      ].freeze
+
+      # 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"
+
+      # Stamped from the UFC the evaluation ran against; the hook reads only this
+      # key, never live config.
+      METADATA_OBSERVE_FULL_EVALUATION_DATA = "__dd_observe_full_evaluation_data"
+    end
+  end
+end