datadog 2.39.0 → 2.47.0

data/lib/datadog/open_feature/component.rb

@@ -2,6 +2,8 @@
 
 require_relative "transport"
 require_relative "evaluation_engine"
+require_relative "../core/utils/time"
+require_relative "configuration/source"
 require_relative "exposures/buffer"
 require_relative "exposures/worker"
 require_relative "exposures/deduplicator"
@@ -16,20 +18,18 @@ 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, :span_enrichment_hook
-
-      def self.build(settings, agent_settings, logger:, telemetry:)
-        return unless settings.respond_to?(:open_feature) && settings.open_feature.enabled
+      CONFIGURATION_READY = :ready
+      CONFIGURATION_TIMEOUT = :timeout
+      CONFIGURATION_SHUTDOWN = :shutdown
+      CONFIGURATION_CHANGED = :changed
+      CONFIGURATION_LOST = :lost
 
-        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/."
+      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_hook, :span_enrichment_hook
 
-          logger.warn(message)
-          return
-        end
+      def self.build(settings, agent_settings, resolution:, on_configuration_change:, logger:, telemetry:)
+        return unless resolution.enabled?
 
-        if RUBY_ENGINE != "ruby"
+        unless ["ruby", "truffleruby"].include?(RUBY_ENGINE)
           message = "OpenFeature could not be enabled as MRI is required, " \
             "but running on #{RUBY_ENGINE.inspect}"
 
@@ -46,10 +46,16 @@ module Datadog
           return
         end
 
-        new(settings, agent_settings, logger: logger, telemetry: telemetry)
+        new(
+          settings,
+          agent_settings,
+          on_configuration_change: on_configuration_change,
+          logger: logger,
+          telemetry: telemetry,
+        )
       end
 
-      def initialize(settings, agent_settings, logger:, telemetry:)
+      def initialize(settings, agent_settings, logger:, telemetry:, on_configuration_change: nil)
         transport = Transport::HTTP.build(agent_settings: agent_settings, logger: logger)
         @worker = Exposures::Worker.new(settings: settings, transport: transport, telemetry: telemetry, logger: logger)
 
@@ -60,12 +66,74 @@ module Datadog
         @logger = logger
         @settings = settings
         @agent_settings = agent_settings
+        @on_configuration_change = on_configuration_change
         @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
+
+        @configuration_mutex = Mutex.new
+        @reconfiguration_mutex = Mutex.new
+        @configuration_condition = ConditionVariable.new
+        @configuration_received = false
+        @configuration_shutdown = false
+      end
+
+      def reconfigure!(configuration)
+        event = @reconfiguration_mutex.synchronize do
+          return if configuration_shutdown?
+
+          @engine.reconfigure!(configuration)
+
+          @configuration_mutex.synchronize do
+            return if @configuration_shutdown
+
+            previously_received = @configuration_received
+            @configuration_received = !configuration.nil?
+            @configuration_condition.broadcast
+
+            if @configuration_received
+              previously_received ? CONFIGURATION_CHANGED : CONFIGURATION_READY
+            elsif previously_received
+              CONFIGURATION_LOST
+            end
+          end
+        end
+
+        @on_configuration_change&.call(event) if event
+      end
+
+      def wait_for_configuration(&cancelled)
+        timeout_seconds = @settings.feature_flags.initialization_timeout_ms / 1000.0
+        deadline = Core::Utils::Time.get_time + timeout_seconds
+
+        @configuration_mutex.synchronize do
+          loop do
+            return CONFIGURATION_SHUTDOWN if @configuration_shutdown || cancelled&.call
+            return CONFIGURATION_READY if @configuration_received
+
+            remaining = deadline - Core::Utils::Time.get_time
+            return CONFIGURATION_TIMEOUT unless remaining.positive?
+
+            @configuration_condition.wait(@configuration_mutex, remaining)
+          end
+        end
+      end
+
+      def wake_configuration_waiters
+        @configuration_mutex.synchronize { @configuration_condition.broadcast }
+        nil
+      end
+
+      def configuration_received?
+        @configuration_mutex.synchronize { @configuration_received }
       end
 
       def shutdown!
+        @configuration_mutex.synchronize do
+          @configuration_shutdown = true
+          @configuration_condition.broadcast
+        end
+
         @worker.graceful_shutdown
         @flag_eval_evp_writer&.stop
         # Symmetric teardown: drop any accumulated span-enrichment state and
@@ -75,6 +143,10 @@ module Datadog
 
       private
 
+      def configuration_shutdown?
+        @configuration_mutex.synchronize { @configuration_shutdown }
+      end
+
       def create_flag_eval_metrics_hook
         return unless Hooks::FlagEvalMetricsHook.available?
 

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      # Validated endpoint for agentless Feature Flags configuration delivery.
+      class AgentlessEndpoint
+        DEFAULT_SITE = "datadoghq.com"
+        AGENTLESS_SUBDOMAIN = "ufc-server.ff-cdn"
+        CONFIGURATION_PATH = "/api/v2/feature-flagging/config/rules-based/server"
+        INVALID_SITE_CHARACTERS = /[\s\/?#@:]/
+        INTERNAL_WHITESPACE = /\s/
+
+        class << self
+          def build(site:, environment:, base_url: nil, logger: Datadog.logger)
+            if base_url
+              build_custom(base_url, logger)
+            else
+              build_managed(site, environment, logger)
+            end
+          end
+
+          private
+
+          def build_custom(base_url, logger)
+            unless base_url.ascii_only?
+              logger.warn("Feature Flags agentless base URL is invalid; agentless delivery is disabled")
+              return
+            end
+
+            if base_url.match?(INTERNAL_WHITESPACE)
+              logger.warn("Feature Flags agentless base URL contains whitespace; agentless delivery is disabled")
+              return
+            end
+
+            uri = URI.parse(base_url)
+            unless uri.is_a?(URI::HTTP) && uri.absolute? && uri.host
+              logger.warn("Feature Flags agentless base URL must be an absolute HTTP or HTTPS URL; agentless delivery is disabled")
+              return
+            end
+
+            uri.path = CONFIGURATION_PATH if uri.path.to_s.empty? || uri.path == "/"
+            new(uri, managed: false)
+          rescue URI::InvalidURIError
+            logger.warn("Feature Flags agentless base URL is invalid; agentless delivery is disabled")
+            nil
+          end
+
+          def build_managed(site, environment, logger)
+            string_site = site.to_s
+            unless string_site.ascii_only?
+              logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+              return
+            end
+
+            normalized_site = string_site.strip.downcase
+            normalized_site = DEFAULT_SITE if normalized_site.empty?
+            if normalized_site.match?(INVALID_SITE_CHARACTERS)
+              logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+              return
+            end
+
+            uri = URI::HTTPS.build(
+              host: "#{AGENTLESS_SUBDOMAIN}.#{normalized_site}",
+              path: CONFIGURATION_PATH,
+              query: environment.nil? ? nil : URI.encode_www_form(dd_env: environment),
+            )
+            new(uri, managed: true)
+          rescue URI::InvalidComponentError
+            logger.warn("Feature Flags site is invalid; agentless delivery is disabled")
+            nil
+          end
+        end
+
+        attr_reader :uri
+
+        def initialize(uri, managed:)
+          @uri = uri
+          @managed = managed
+        end
+
+        def managed?
+          @managed
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      module Source
+        class Resolution
+          attr_reader :source
+
+          def initialize(source, enabled:)
+            @source = source
+            @enabled = enabled
+          end
+
+          def enabled?
+            @enabled
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,25 @@ module Datadog
     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)
@@ -15,10 +34,19 @@ module Datadog
             # 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,
@@ -42,6 +70,102 @@ module Datadog
                 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 :evaluation_telemetry_per_subject_opt_out_enabled do |o|
+                o.type :bool
+                o.env "DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED"
+                o.default false
+              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

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -23,27 +23,42 @@ module Datadog
       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(", ")}"
-          return ResolutionDetails.build_error(
+          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(
+        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")
 
-        ResolutionDetails.build_error(
+        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
@@ -65,6 +80,17 @@ module Datadog
 
         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

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

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

@@ -15,27 +15,34 @@ module Datadog
             "#{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.allocation_key}:#{result.variant}:#{result.serial_id}"
           end
 
           def build(result, flag_key:, context:)
-            {
+            event = {
               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)
-              }
-            }.freeze
+                attributes: extract_attributes(context),
+              },
+            }
+
+            serial_id = result.serial_id
+            event[:serial_id] = serial_id unless serial_id.nil?
+
+            event.freeze
           end
 
           private

data/lib/datadog/open_feature/ext.rb

@@ -11,11 +11,30 @@ module Datadog
       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