datadog 2.38.0 → 2.47.0

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,9 +34,31 @@ 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.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
 
@@ -25,10 +66,106 @@ module Datadog
               # 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.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 :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

@@ -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
@@ -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')
+        @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
@@ -51,20 +66,31 @@ 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.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/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
@@ -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/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,14 +3,38 @@
 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'
+      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