datadog 2.17.0 → 2.37.0

data/lib/datadog/open_feature/metrics/flag_eval_metrics.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Metrics
+      # Records flag evaluation metrics via OpenTelemetry
+      class FlagEvalMetrics
+        METER_NAME = 'ddtrace.openfeature'
+        METRIC_NAME = 'feature_flag.evaluations'
+        METRIC_UNIT = '{evaluation}'
+        METRIC_DESCRIPTION = 'Number of feature flag evaluations'
+
+        ATTR_FLAG_KEY = 'feature_flag.key'
+        ATTR_VARIANT = 'feature_flag.result.variant'
+        ATTR_REASON = 'feature_flag.result.reason'
+        ATTR_ALLOCATION_KEY = 'feature_flag.result.allocation_key'
+        ATTR_ERROR_TYPE = 'error.type'
+
+        DEFAULT_ERROR_TYPE = 'general'
+
+        ERROR_TYPE_MAP = {
+          'FLAG_NOT_FOUND' => 'flag_not_found',
+          'TYPE_MISMATCH' => 'type_mismatch',
+          'PARSE_ERROR' => 'parse_error',
+          'PROVIDER_NOT_READY' => 'provider_not_ready',
+          'TARGETING_KEY_MISSING' => 'targeting_key_missing',
+          'INVALID_CONTEXT' => 'invalid_context',
+          'PROVIDER_FATAL' => 'provider_fatal',
+          'GENERAL' => DEFAULT_ERROR_TYPE,
+        }.freeze
+
+        # Reasons that should not include allocation_key in metrics
+        EXCLUDE_ALLOCATION_KEY_REASONS = %w[error default disabled].freeze
+
+        def initialize(telemetry:, logger:)
+          @telemetry = telemetry
+          @logger = logger
+          @enabled = Datadog.configuration.opentelemetry.metrics.enabled
+          @counter = nil
+          @mutex = Mutex.new
+
+          unless @enabled
+            @logger.debug { 'OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled' }
+          end
+        end
+
+        def record(flag_key, variant:, reason:, error_code: nil, allocation_key: nil)
+          return unless @enabled
+
+          counter = get_or_create_counter
+          return unless counter
+
+          attributes = build_attributes(
+            flag_key,
+            variant: variant,
+            reason: reason,
+            error_code: error_code,
+            allocation_key: allocation_key,
+          )
+          counter.add(1, attributes: attributes)
+        rescue => e
+          @logger.debug { "OpenFeature: Failed to record evaluation metric: #{e.class}: #{e.message}" }
+          @telemetry.report(e, description: 'OpenFeature: Failed to record evaluation metric')
+        end
+
+        private
+
+        # Counter is created lazily because OTel SDK may not be initialized
+        # when the OpenFeature component is created.
+        def get_or_create_counter
+          @mutex.synchronize do
+            return @counter if @counter
+
+            meter_provider = get_or_initialize_meter_provider
+            return unless meter_provider
+
+            meter = meter_provider.meter(METER_NAME)
+            @counter = meter.create_counter(
+              METRIC_NAME,
+              unit: METRIC_UNIT,
+              description: METRIC_DESCRIPTION
+            )
+          end
+        rescue => e
+          @logger.debug { "OpenFeature: Failed to create metrics counter: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # Fetch an available OTel meter provider, initializing if needed.
+        # Returns the meter provider if available, nil otherwise.
+        def get_or_initialize_meter_provider
+          meter_provider = defined?(::OpenTelemetry) ? ::OpenTelemetry.meter_provider : nil
+          return meter_provider if sdk_meter_provider?(meter_provider)
+
+          @logger.debug { 'OpenFeature: Initializing OTel meter provider directly' }
+          require 'opentelemetry-metrics-sdk'
+          require 'datadog/opentelemetry/metrics'
+          Datadog::OpenTelemetry::Metrics.initialize!(Datadog.send(:components))
+
+          meter_provider = ::OpenTelemetry.meter_provider
+          sdk_meter_provider?(meter_provider) ? meter_provider : nil
+        rescue LoadError => e
+          @logger.debug { "OpenFeature: Failed to initialize OTel metrics: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        def sdk_meter_provider?(meter_provider)
+          return false if meter_provider.nil?
+          return false unless defined?(::OpenTelemetry::SDK::Metrics::MeterProvider)
+
+          meter_provider.is_a?(::OpenTelemetry::SDK::Metrics::MeterProvider)
+        end
+
+        def build_attributes(flag_key, variant:, reason:, error_code:, allocation_key:)
+          reason_downcase = normalize_reason(reason)
+
+          attrs = {
+            ATTR_FLAG_KEY => flag_key,
+            ATTR_VARIANT => variant.to_s,
+            ATTR_REASON => reason_downcase,
+          }
+
+          if allocation_key && !allocation_key.empty? && !exclude_allocation_key?(reason_downcase)
+            attrs[ATTR_ALLOCATION_KEY] = allocation_key
+          end
+
+          if error_code
+            attrs[ATTR_ERROR_TYPE] = normalize_error_type(error_code)
+          end
+
+          attrs
+        end
+
+        def normalize_reason(reason)
+          reason = reason.to_s
+          reason.empty? ? 'unknown' : reason.downcase
+        end
+
+        def normalize_error_type(error_code)
+          ERROR_TYPE_MAP.fetch(error_code.to_s, DEFAULT_ERROR_TYPE)
+        end
+
+        def exclude_allocation_key?(reason_downcase)
+          EXCLUDE_ALLOCATION_KEY_REASONS.include?(reason_downcase)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/native_evaluator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../core/feature_flags'
+require_relative 'ext'
+require_relative 'resolution_details'
+
+module Datadog
+  module OpenFeature
+    # This class is an interface of evaluation logic using native extension
+    class NativeEvaluator
+      INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE = 'flag configuration is invalid or unsupported'
+
+      # 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 initialize(configuration)
+        @configuration = Core::FeatureFlags::Configuration.new(configuration)
+      end
+
+      # Returns the assignment for a given flag key based on the feature flags
+      # configuration
+      #
+      # @param flag_key [String] The key of the feature flag
+      # @param default_value [Object] The default value to return if the flag is
+      #                              not found or evaluation itself fails
+      # @param expected_type [Symbol] The expected type of the flag
+      # @param context [Hash] The context of the evaluation, containing targeting key
+      #                       and other attributes
+      #
+      # @return [Core::FeatureFlags::ResolutionDetails] The assignment for the flag
+      def get_assignment(flag_key, default_value:, expected_type:, context:)
+        result = @configuration.get_assignment(flag_key, expected_type, context)
+
+        return invalid_flag_configuration_error(default_value) if invalid_flag_configuration?(result)
+
+        # NOTE: This is a special case when we need to fallback to the default
+        #       value, even tho the evaluation itself doesn't produce an error
+        #       resolution details
+        result.value = default_value if result.variant.nil?
+        result
+      end
+
+      private
+
+      def invalid_flag_configuration?(result)
+        result.reason == Ext::DEFAULT &&
+          result.error_code.nil? &&
+          result.error_message == INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE
+      end
+
+      def invalid_flag_configuration_error(default_value)
+        ResolutionDetails.build_error(
+          value: default_value,
+          error_code: Ext::PARSE_ERROR,
+          error_message: INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE
+        )
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/noop_evaluator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+require_relative 'resolution_details'
+
+module Datadog
+  module OpenFeature
+    # This class is a noop interface of evaluation logic
+    class NoopEvaluator
+      def initialize(_configuration)
+        # no-op
+      end
+
+      def get_assignment(_flag_key, default_value:, context:, expected_type:)
+        ResolutionDetails.new(
+          value: default_value,
+          log?: false,
+          error?: true,
+          error_code: Ext::PROVIDER_NOT_READY,
+          error_message: 'Waiting for flags configuration',
+          reason: Ext::ERROR
+        )
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/provider.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+require_relative '../core/utils/time'
+require 'open_feature/sdk'
+
+module Datadog
+  module OpenFeature
+    # OpenFeature feature flagging provider backed by Datadog Remote Configuration.
+    #
+    # Requires openfeature-sdk >= 0.5.1 for flag evaluation metrics and EVP hook support.
+    #
+    # Hook lifecycle note: FlagEvalEVPHook is returned from #hooks so EVP uses the SDK-final
+    # EvaluationDetails. This matches FlagEvalMetricsHook and records defaults/errors produced
+    # by OpenFeature hook failures or post-provider type validation.
+    #
+    # Implementation follows the OpenFeature contract of Provider SDK.
+    # For details see:
+    #   - https://github.com/open-feature/ruby-sdk/blob/v0.4.1/README.md#develop-a-provider
+    #   - https://github.com/open-feature/ruby-sdk/blob/v0.4.1/lib/open_feature/sdk/provider/no_op_provider.rb
+    #
+    # In the example below you can see how to configure the OpenFeature SDK
+    # https://github.com/open-feature/ruby-sdk to use the Datadog feature flags provider.
+    #
+    # Example:
+    #
+    #   Make sure to enable Remote Configuration and OpenFeature in the Datadog configuration.
+    #
+    #   ```ruby
+    #   # FILE: initializers/datadog.rb
+    #   Datadog.configure do |config|
+    #     config.remote.enabled = true
+    #     config.open_feature.enabled = true
+    #   end
+    #   ```
+    #
+    #   And configure the OpenFeature SDK to use the Datadog feature flagging provider.
+    #
+    #   ```ruby
+    #   # FILE: initializers/open_feature.rb
+    #   require 'open_feature/sdk'
+    #   require 'datadog/open_feature/provider'
+    #
+    #   OpenFeature::SDK.configure do |config|
+    #     config.set_provider(Datadog::OpenFeature::Provider.new)
+    #   end
+    #   ```
+    #
+    #   Now you can create OpenFeature SDK client and use it to fetch feature flag values.
+    #
+    #   ```ruby
+    #   client = OpenFeature::SDK.build_client
+    #   context = OpenFeature::SDK::EvaluationContext.new('email' => 'john.doe@gmail.com')
+    #
+    #   client.fetch_string_value(
+    #     flag_key: 'banner', default_value: 'Greetings!', evaluation_context: context
+    #   )
+    #   # => 'Welcome back!'
+    #   ```
+    class Provider
+      NAME = 'Datadog Feature Flagging Provider'
+
+      attr_reader :metadata
+
+      def initialize
+        @metadata = ::OpenFeature::SDK::Provider::ProviderMetadata.new(name: NAME).freeze
+      end
+
+      def init
+        # no-op
+      end
+
+      def shutdown
+        # no-op
+      end
+
+      def hooks
+        component = Datadog.send(:components).open_feature
+        otel_hook = component&.flag_eval_metrics_hook
+        evp_hook = component&.flag_eval_evp_hook
+        [otel_hook, evp_hook].compact
+      end
+
+      def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :boolean, evaluation_context: evaluation_context)
+      end
+
+      def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :string, evaluation_context: evaluation_context)
+      end
+
+      def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :number, evaluation_context: evaluation_context)
+      end
+
+      def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :integer, evaluation_context: evaluation_context)
+      end
+
+      def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :float, evaluation_context: evaluation_context)
+      end
+
+      def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+        evaluate(flag_key, default_value: default_value, expected_type: :object, evaluation_context: evaluation_context)
+      end
+
+      private
+
+      def evaluate(flag_key, default_value:, expected_type:, evaluation_context:)
+        # Stamp evaluation entry time once, here on the eval thread. The EVP path uses this for
+        # accurate first/last_evaluation bounds instead of a later hook-fire clock read.
+        eval_time_ms = (Core::Utils::Time.now.to_f * 1000).to_i
+
+        engine = OpenFeature.engine
+        return component_not_configured_default(default_value, eval_time_ms) if engine.nil?
+
+        result = fetch_engine_value(engine, flag_key, default_value, expected_type, evaluation_context)
+
+        # Build metadata before branching so provider-returned details carry eval-entry time.
+        flag_meta = build_flag_metadata(result, eval_time_ms)
+
+        if result.error?
+          return sdk_error_details(default_value, result.error_code, result.error_message, result.reason, flag_meta)
+        end
+
+        sdk_success_details(result, flag_meta)
+      rescue => e
+        error_message = "#{e.class}: #{e.message}"
+        error_result = Datadog::OpenFeature::ResolutionDetails.build_error(
+          value: default_value,
+          error_code: Ext::GENERAL,
+          error_message: error_message
+        )
+        error_flag_meta = build_flag_metadata(error_result, eval_time_ms || (Core::Utils::Time.now.to_f * 1000).to_i)
+
+        sdk_error_details(default_value, Ext::GENERAL, error_message, Ext::ERROR, error_flag_meta)
+      end
+
+      def fetch_engine_value(engine, flag_key, default_value, expected_type, evaluation_context)
+        engine.fetch_value(
+          flag_key,
+          default_value: default_value,
+          expected_type: expected_type,
+          evaluation_context: evaluation_context
+        )
+      end
+
+      def sdk_success_details(result, flag_meta)
+        ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: result.value,
+          variant: result.variant,
+          reason: result.reason,
+          flag_metadata: flag_meta,
+        )
+      end
+
+      def sdk_error_details(default_value, error_code, error_message, reason, flag_meta = {})
+        ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: default_value,
+          error_code: error_code,
+          error_message: error_message,
+          reason: reason,
+          flag_metadata: flag_meta
+        )
+      end
+
+      def build_flag_metadata(result, eval_time_ms)
+        metadata = result.flag_metadata&.dup || {}
+        allocation_key = result.allocation_key
+        metadata['__dd_allocation_key'] = allocation_key if allocation_key && !allocation_key.empty?
+
+        # Eval-time stamped at provider entry; the EVP hook reads 'dd.eval.timestamp_ms' for
+        # accurate first/last_evaluation bounds (it falls back to hook-fire time when absent).
+        metadata['dd.eval.timestamp_ms'] = eval_time_ms
+
+        metadata
+      end
+
+      def component_not_configured_default(value, eval_time_ms)
+        ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+          value: value,
+          error_code: Ext::PROVIDER_FATAL,
+          error_message: "Datadog's OpenFeature component must be configured",
+          reason: Ext::ERROR,
+          flag_metadata: {'dd.eval.timestamp_ms' => eval_time_ms}
+        )
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/remote.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../core/remote/dispatcher'
+
+module Datadog
+  module OpenFeature
+    # This module contains the remote configuration functionality for OpenFeature
+    module Remote
+      class << self
+        FFE_FLAG_CONFIGURATION_RULES = 1 << 46
+        FFE_PRODUCTS = ['FFE_FLAGS'].freeze
+        FFE_CAPABILITIES = [FFE_FLAG_CONFIGURATION_RULES].freeze
+
+        def capabilities
+          FFE_CAPABILITIES
+        end
+
+        def products
+          FFE_PRODUCTS
+        end
+
+        def receivers(telemetry)
+          matcher = Core::Remote::Dispatcher::Matcher::Product.new(FFE_PRODUCTS)
+          receiver = Core::Remote::Dispatcher::Receiver.new(matcher) do |repository, changes|
+            engine = OpenFeature.engine
+            next unless engine
+
+            changes.each do |change|
+              content = repository[change.path]
+
+              unless content || change.type == :delete
+                next telemetry.error("OpenFeature: Remote Configuration change is not present on #{change.type}")
+              end
+
+              # NOTE: In the current RC implementation we immediately apply the configuration,
+              #       but that might change if we need to apply patches instead.
+              case change.type
+              when :insert, :update
+                begin
+                  # @type var content: Core::Remote::Configuration::Content
+                  engine.reconfigure!(read_content(content))
+                  content.applied
+                rescue EvaluationEngine::ReconfigurationError => e
+                  content.errored("Error applying OpenFeature configuration: #{e.class}: #{e.message}")
+                end
+              when :delete
+                # NOTE: For now, we treat deletion as clearing the configuration
+                #       In a multi-config scenario, we might track configs per path
+                engine.reconfigure!(nil)
+              end
+            end
+          end
+
+          [receiver]
+        end
+
+        private
+
+        def read_content(content)
+          # Unlike all of the other remotes, this one does not JSON-parse
+          # the data.
+          content.data
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/resolution_details.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+
+module Datadog
+  module OpenFeature
+    # This class is based on the `OpenFeature::SDK::Provider::ResolutionDetails` class
+    #
+    # See: https://github.com/open-feature/ruby-sdk/blob/v0.4.1/lib/open_feature/sdk/provider/resolution_details.rb
+    class ResolutionDetails < Struct.new(
+      :value,
+      :reason,
+      :variant,
+      :error_code,
+      :error_message,
+      :flag_metadata,
+      :allocation_key,
+      :extra_logging,
+      :log?,
+      :error?,
+      keyword_init: true
+    )
+      def self.build_error(value:, error_code:, error_message:, reason: Ext::ERROR)
+        new(
+          value: value,
+          error_code: error_code,
+          error_message: error_message,
+          reason: reason,
+          error?: true,
+          log?: false
+        ).freeze
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/transport.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative '../core/encoding'
+require_relative '../core/evp'
+require_relative '../core/transport/http'
+require_relative '../core/transport/http/env'
+require_relative '../core/transport/http/api/endpoint'
+require_relative '../core/transport/http/api/instance'
+require_relative '../core/transport/parcel'
+require_relative '../core/transport/request'
+
+module Datadog
+  module OpenFeature
+    module Transport
+      class HTTP
+        # API spec for the EVP exposures endpoint.
+        class Spec
+          def initialize
+            @endpoint = Core::Transport::HTTP::API::Endpoint.new(
+              :post, '/evp_proxy/v2/api/v2/exposures'
+            )
+          end
+
+          # TODO rename to send_request?
+          def call(env, &block)
+            @endpoint.call(env) do |request_env|
+              request_env.headers['Content-Type'] = env.request.parcel.content_type
+              request_env.headers[Core::EVP::SUBDOMAIN_HEADER_NAME] =
+                Core::EVP::EVENT_PLATFORM_INTAKE_SUBDOMAIN
+              request_env.body = env.request.parcel.data
+
+              block.call(request_env)
+            end
+          end
+        end
+
+        # API spec for the EVP flagevaluation endpoint.
+        # Path: /evp_proxy/v2/api/v2/flagevaluation
+        # Header: X-Datadog-EVP-Subdomain: event-platform-intake (same as exposures)
+        class FlagevaluationsSpec
+          def initialize
+            @endpoint = Core::Transport::HTTP::API::Endpoint.new(
+              :post, '/evp_proxy/v2/api/v2/flagevaluation'
+            )
+          end
+
+          def call(env, &block)
+            @endpoint.call(env) do |request_env|
+              request_env.headers['Content-Type'] = env.request.parcel.content_type
+              request_env.headers[Core::EVP::SUBDOMAIN_HEADER_NAME] =
+                Core::EVP::EVENT_PLATFORM_INTAKE_SUBDOMAIN
+              request_env.body = env.request.parcel.data
+
+              block.call(request_env)
+            end
+          end
+        end
+
+        def self.build(agent_settings:, logger:)
+          Core::Transport::HTTP.build(
+            agent_settings: agent_settings,
+            logger: logger
+          ) { |t| t.api('exposures', HTTP::Spec.new) }.to_transport(self)
+        end
+
+        # Build a transport instance for the flagevaluation EVP endpoint.
+        def self.build_flagevaluations(agent_settings:, logger:)
+          Core::Transport::HTTP.build(
+            agent_settings: agent_settings,
+            logger: logger
+          ) { |t| t.api('flagevaluations', HTTP::FlagevaluationsSpec.new) }.to_transport(self)
+        end
+
+        def initialize(apis, default_api, logger:)
+          @api = apis[default_api]
+          @logger = logger
+        end
+
+        def send_exposures(payload)
+          encoder = Core::Encoding::JSONEncoder
+          parcel = Core::Transport::Parcel.new(
+            encoder.encode(payload),
+            content_type: encoder.content_type
+          )
+          request = Core::Transport::Request.new(parcel)
+
+          @api.endpoint.call(Core::Transport::HTTP::Env.new(request)) do |env|
+            @api.call(env)
+          end
+        rescue => e
+          message = "Internal error during request. Cause: #{e.class}: #{e.message} " \
+                    "Location: #{Array(e.backtrace).first}"
+          @logger.debug(message)
+
+          Core::Transport::InternalErrorResponse.new(e)
+        end
+
+        # POST a flag evaluations batch to /evp_proxy/v2/api/v2/flagevaluation.
+        # Mirrors send_exposures; uses the FlagevaluationsSpec endpoint.
+        def send_flag_evaluations(payload)
+          encoder = Core::Encoding::JSONEncoder
+          parcel = Core::Transport::Parcel.new(
+            encoder.encode(payload),
+            content_type: encoder.content_type
+          )
+          request = Core::Transport::Request.new(parcel)
+
+          @api.endpoint.call(Core::Transport::HTTP::Env.new(request)) do |env|
+            @api.call(env)
+          end
+        rescue => e
+          message = "Internal error during request. Cause: #{e.class}: #{e.message} " \
+                    "Location: #{Array(e.backtrace).first}"
+          @logger.debug(message)
+
+          Core::Transport::InternalErrorResponse.new(e)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'core/configuration'
+require_relative 'open_feature/configuration'
+
+module Datadog
+  # A namespace for the OpenFeature component.
+  module OpenFeature
+    Core::Configuration::Settings.extend(Configuration::Settings)
+
+    def self.enabled?
+      Datadog.configuration.open_feature.enabled
+    end
+
+    def self.engine
+      Datadog.send(:components).open_feature&.engine
+    end
+  end
+end