datadog 2.8.0 → 2.39.0

data/lib/datadog/kit/tracing/method_tracer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Needed since this file can be loaded without core
+require_relative "../../ruby_version"
+
+module Datadog
+  module Kit
+    module Tracing
+      # Trace methods easily
+      #
+      # Use as DSL module:
+      #
+      #     class MyClass
+      #       extend Datadog::Kit::Tracing::MethodTracer
+      #
+      #       def foo; 'hello'; end
+      #
+      #       trace_method :foo, span_name: 'optional_span_name'
+      #
+      #       def self.bar; 'hi'; end
+      #
+      #       trace_singleton_class_method :bar, span_name: 'optional_span_name'
+      #     end
+      #
+      # Or directly:
+      #
+      #     Datadog::Kit::Tracing::MethodTracer.trace_method(MyClass, :foo, span_name: 'optional_span_name')
+      #     Datadog::Kit::Tracing::MethodTracer.trace_method(MyClass.singleton_class, :bar, span_name: 'optional_span_name')
+      #
+      # Class argument is implicit via DSL usage; it is required otherwise, and
+      # can accept dynamic classes or modules.
+      #
+      # Span name is optional and defaults to 'Class#method' (or `Class.method`
+      # for singleton class methods) but is required if the class or module
+      # name is `nil`.
+      #
+      # Traced methods are only traced if already within a trace (i.e they do
+      # not create traces by themselves).
+      #
+      # Regular methods must be defined before `trace_method` can be called.
+      # Dynamic methods (e.g via `method_missing` or defined later) can be
+      # traced via `dynamic: true`, which relaxes method existence sanity
+      # checks, but will prevent preserving method visibility.
+      #
+      # Note that this uses `Module#prepend`, so do not use on methods that
+      # have been alias method chained or you risk an infinite recusion crash.
+      #
+      # @public_api
+      module MethodTracer
+        class << self
+          # Trace an instance method by module and name
+          #
+          # @param mod [Module] module or class containing the method to trace
+          # @param method_name [Symbol] name of the method to trace
+          # @param span_name [String, nil] optional span name (defaults to "Module#method")
+          # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+          # @return [void]
+          def trace_method(mod, method_name, span_name: nil, dynamic: false)
+            raise ArgumentError, "mod is not a module" unless mod.is_a?(Module)
+            raise ArgumentError, "ambiguous span name: provide one or define mod.name" if mod.name.nil? && span_name.nil?
+
+            is_private = mod.private_method_defined?(method_name)
+            is_protected = mod.protected_method_defined?(method_name)
+            is_defined = is_private || mod.method_defined?(method_name)
+
+            unless is_defined || dynamic
+              raise NoMethodError, "undefined method #{method_name.inspect} for class #{mod}"
+            end
+
+            hook_point = "#{mod.name}##{method_name}"
+            custom_span_name = span_name
+            span_name ||= hook_point
+
+            unless span_name.is_a?(String)
+              raise ArgumentError, "span name is not a String"
+            end
+
+            args = RubyVersion.is?(">= 2.7") ? "..." : "*args, &block"
+
+            hook_module = Module.new do
+              define_singleton_method(:inspect) do
+                suffix = custom_span_name ? ", #{custom_span_name.inspect}" : ""
+                name || "#<Datadog::Tracing::Kit::MethodTracer(#{method_name.inspect}#{suffix})>"
+              end
+
+              define_singleton_method(:to_s) do
+                suffix = custom_span_name ? ", #{custom_span_name.inspect}" : ""
+                name || "#<Datadog::Tracing::Kit::MethodTracer(#{method_name.inspect}#{suffix})>"
+              end
+
+              # this `eval` is safe:
+              # - `args` is static
+              # - `method_name` is validated by the `method_defined?` check
+              # - `span_name` is validated to be a String and inspected to be quoted
+              eval(<<-RUBY, nil, __FILE__, __LINE__ + 1) # standard:disable Security/Eval
+              def #{method_name}(#{args})
+                return super(#{args}) unless ::Datadog::Tracing.active_trace
+
+                ::Datadog::Tracing.trace(#{span_name.inspect}) { super(#{args}) }
+              end
+              RUBY
+
+              private method_name if is_private
+              protected method_name if is_protected
+            end
+
+            mod.prepend(hook_module)
+          end
+        end
+
+        # Trace a method by name in a module context
+        #
+        # @param method_name [Symbol] name of the method to trace
+        # @param span_name [String, nil] optional span name (defaults to "Module#method")
+        # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+        # @return [void]
+        def trace_method(method_name, span_name: nil, dynamic: false)
+          MethodTracer.trace_method(self, method_name, span_name: span_name, dynamic: dynamic)
+        end
+
+        # Trace a method by name in a module's singleton context (a.k.a "class method")
+        #
+        # @param method_name [Symbol] name of the method to trace
+        # @param span_name [String, nil] optional span name (defaults to "Module.method")
+        # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+        # @return [void]
+        def trace_singleton_class_method(method_name, span_name: nil, dynamic: false)
+          span_name ||= "#{name}.#{method_name}" if respond_to?(:name)
+
+          MethodTracer.trace_method(singleton_class, method_name, span_name: span_name, dynamic: dynamic)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/kit.rb

@@ -8,4 +8,4 @@ module Datadog
   end
 end
 
-require_relative 'kit/identity'
+require_relative "kit/identity"

data/lib/datadog/open_feature/component.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "evaluation_engine"
+require_relative "exposures/buffer"
+require_relative "exposures/worker"
+require_relative "exposures/deduplicator"
+require_relative "exposures/reporter"
+require_relative "metrics/flag_eval_metrics"
+require_relative "flag_evaluation/writer"
+require_relative "hooks/flag_eval_metrics_hook"
+require_relative "hooks/flag_eval_evp_hook"
+require_relative "hooks/span_enrichment_hook"
+
+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
+
+        unless settings.respond_to?(:remote) && settings.remote.enabled
+          message = "OpenFeature could not be enabled as Remote Configuration is currently disabled. " \
+            "To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/."
+
+          logger.warn(message)
+          return
+        end
+
+        if RUBY_ENGINE != "ruby"
+          message = "OpenFeature could not be enabled as MRI is required, " \
+            "but running on #{RUBY_ENGINE.inspect}"
+
+          logger.warn(message)
+          return
+        end
+
+        if (libdatadog_api_failure = Core::LIBDATADOG_API_FAILURE)
+          message = "OpenFeature could not be enabled as `libdatadog` is not loaded: " \
+            "#{libdatadog_api_failure.inspect}. For help solving this issue, " \
+            "please contact Datadog support at https://docs.datadoghq.com/help/."
+
+          logger.warn(message)
+          return
+        end
+
+        new(settings, agent_settings, logger: logger, telemetry: telemetry)
+      end
+
+      def initialize(settings, agent_settings, logger:, telemetry:)
+        transport = Transport::HTTP.build(agent_settings: agent_settings, logger: logger)
+        @worker = Exposures::Worker.new(settings: settings, transport: transport, telemetry: telemetry, logger: logger)
+
+        reporter = Exposures::Reporter.new(@worker, telemetry: telemetry, logger: logger)
+        @engine = EvaluationEngine.new(reporter, telemetry: telemetry, logger: logger)
+
+        @telemetry = telemetry
+        @logger = logger
+        @settings = settings
+        @agent_settings = agent_settings
+        @flag_eval_metrics_hook = create_flag_eval_metrics_hook
+        @flag_eval_evp_hook = create_flag_eval_evp_hook
+        @span_enrichment_hook = create_span_enrichment_hook
+      end
+
+      def shutdown!
+        @worker.graceful_shutdown
+        @flag_eval_evp_writer&.stop
+        # Symmetric teardown: drop any accumulated span-enrichment state and
+        # subscriptions (Ruby CLAUDE.md mandates closing resources).
+        @span_enrichment_hook&.shutdown
+      end
+
+      private
+
+      def create_flag_eval_metrics_hook
+        return unless Hooks::FlagEvalMetricsHook.available?
+
+        metrics = Metrics::FlagEvalMetrics.new(telemetry: @telemetry, logger: @logger)
+        Hooks::FlagEvalMetricsHook.new(metrics)
+      end
+
+      # Killswitch: DD_FLAGGING_EVALUATION_COUNTS_ENABLED (default on) gates only the EVP path.
+      # Read through the datadog config registry, not raw ENV.
+      def create_flag_eval_evp_hook
+        return unless @settings.open_feature.evaluation_counts_enabled
+        return unless Hooks::FlagEvalEVPHook.available?
+
+        evp_transport = Transport::HTTP.build_flagevaluations(
+          agent_settings: @agent_settings,
+          logger: @logger,
+        )
+        @flag_eval_evp_writer = FlagEvaluation::Writer.new(transport: evp_transport, logger: @logger, telemetry: @telemetry)
+        Hooks::FlagEvalEVPHook.new(@flag_eval_evp_writer)
+      end
+
+      # Construct the span-enrichment hook only when the opt-in gate is on, so
+      # there is no idle per-span overhead when disabled.
+      def create_span_enrichment_hook
+        return unless @settings.open_feature.span_enrichment_enabled
+
+        store = Hooks::SpanEnrichmentHook::SpanEnrichmentStateStore.new
+        Hooks::SpanEnrichmentHook.new(store, logger: @logger)
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Configuration
+      # A settings class for the OpenFeature component.
+      module Settings
+        def self.extended(base)
+          base = base.singleton_class unless base.is_a?(Class)
+          add_settings!(base)
+        end
+
+        def self.add_settings!(base)
+          base.class_eval do
+            # Steep does not update `self` for this `class_eval` block.
+            # @type self: Datadog::Core::Configuration::Base::_DslContext
+            settings :open_feature do
+              option :enabled do |o|
+                o.type :bool
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED"
+                o.default false
+              end
+
+              # 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
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "ext"
+require_relative "noop_evaluator"
+require_relative "native_evaluator"
+require_relative "resolution_details"
+
+module Datadog
+  module OpenFeature
+    # This class performs the evaluation of the feature flag
+    class EvaluationEngine
+      # Steep: https://github.com/soutaro/steep/issues/1880
+      ReconfigurationError = Class.new(StandardError) # steep:ignore IncompatibleAssignment
+
+      ALLOWED_TYPES = %i[boolean string number float integer object].freeze
+
+      def initialize(reporter, telemetry:, logger:)
+        @reporter = reporter
+        @telemetry = telemetry
+        @logger = logger
+
+        @evaluator = NoopEvaluator.new(nil)
+      end
+
+      def fetch_value(flag_key, default_value:, expected_type:, evaluation_context: nil)
+        unless ALLOWED_TYPES.include?(expected_type)
+          message = "unknown type #{expected_type.inspect}, allowed types #{ALLOWED_TYPES.join(", ")}"
+          return ResolutionDetails.build_error(
+            value: default_value, error_code: Ext::UNKNOWN_TYPE, error_message: message
+          )
+        end
+
+        context = evaluation_context&.fields.to_h
+        result = @evaluator.get_assignment(
+          flag_key, default_value: default_value, context: context, expected_type: expected_type
+        )
+
+        @reporter.report(result, flag_key: flag_key, context: evaluation_context)
+
+        result
+      rescue => e
+        @telemetry.report(e, description: "OpenFeature: Failed to fetch flag value")
+
+        ResolutionDetails.build_error(
+          value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
+        )
+      end
+
+      # NOTE: In a currect implementation configuration is expected to be a raw
+      #       JSON string containing feature flags (straight from the remote config)
+      #       in the format expected by `libdatadog` without any modifications
+      def reconfigure!(configuration)
+        if configuration.nil?
+          @logger.debug("OpenFeature: Removing configuration")
+
+          return @evaluator = NoopEvaluator.new(configuration)
+        end
+
+        @evaluator = NativeEvaluator.new(configuration)
+      rescue => e
+        message = "OpenFeature: Failed to reconfigure, reverting to the previous configuration"
+
+        @logger.error("#{message}, #{e.class}: #{e.message}")
+        @telemetry.report(e, description: "#{message} (#{e.class})")
+
+        raise ReconfigurationError, "#{e.class}: #{e.message}"
+      end
+    end
+  end
+end

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

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

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

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

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

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

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

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

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

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