datadog 2.8.0 → 2.39.0

data/lib/datadog/open_feature/provider.rb

@@ -0,0 +1,226 @@
+# 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
+        [
+          component&.flag_eval_metrics_hook,
+          component&.flag_eval_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
+
+        # Drive APM span enrichment directly from the evaluation path. This is the only reliable
+        # way to attach `ffe_*` tags across all supported OpenFeature SDK versions, since older
+        # SDKs do not dispatch provider hooks. Guarded so enrichment can never break evaluation.
+        enrich_span(flag_key, result, evaluation_context)
+
+        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[Ext::METADATA_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
+
+      # Dispatch span enrichment from the evaluation path in a never-throw
+      # wrapper. Reads the split serial id / do-log flag directly off the Datadog
+      # `ResolutionDetails` struct and the targeting key off the built evaluation
+      # context. A nil hook (gate off or component absent) is a no-op.
+      def enrich_span(flag_key, result, evaluation_context)
+        hook = span_enrichment_hook
+        return unless hook
+
+        # Hook resolved first so the common gate-off path short-circuits without
+        # resolving the tracer. With the gate on but no active trace there is
+        # nowhere to attach tags, so skip before building the capture call.
+        return unless Datadog::Tracing.active_trace
+
+        hook.capture(
+          flag_key: flag_key,
+          variant: result.variant,
+          value: result.value,
+          serial_id: result.serial_id,
+          do_log: result.log? || false,
+          targeting_key: evaluation_context&.targeting_key,
+        )
+      rescue => e
+        Datadog.logger.debug { "OpenFeature: span enrichment dispatch failed: #{e.class}: #{e.message}" }
+      end
+
+      def span_enrichment_hook
+        Datadog.send(:components).open_feature&.span_enrichment_hook
+      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,37 @@
+# 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,
+      :serial_id,
+      :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,
+          serial_id: nil
+        ).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

data/lib/datadog/opentelemetry/api/baggage.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "trace/span"
+require_relative "../../tracing/trace_operation"
+require_relative "../trace"
+
+module Datadog
+  module OpenTelemetry
+    module API
+      # The Baggage module provides an implementation of the OpenTelemetry Baggage API.
+      #
+      # Baggage is a set of name/value pairs describing user-defined properties that can be
+      # propagated through a distributed trace. This implementation follows the W3C Baggage
+      # specification and the OpenTelemetry Baggage API.
+      #
+      # @see https://www.w3.org/TR/baggage/
+      # @see https://opentelemetry.io/docs/specs/otel/baggage/api/
+      module Baggage
+        def initialize(trace: nil)
+          @trace = trace
+        end
+
+        # Returns a new context with empty baggage
+        #
+        # @param [optional Context] context Context to clear baggage from. Defaults
+        # to ::OpenTelemetry::Context.current
+        # @return [Context]
+        def clear(context: ::OpenTelemetry::Context.current)
+          context.ensure_trace&.baggage&.clear
+          context
+        end
+
+        # Returns the corresponding value for key
+        #
+        # @param [String] key The lookup key
+        # @param [optional Context] context The context from which to retrieve
+        # the key. Defaults to ::OpenTelemetry::Context.current
+        # @return [String, nil]
+        def value(key, context: ::OpenTelemetry::Context.current)
+          trace = context.ensure_trace
+          return nil if trace.nil?
+
+          trace.baggage && trace.baggage[key]
+        end
+
+        # Returns all baggage values
+        #
+        # @param [optional Context] context The context from which to retrieve
+        # the baggage. Defaults to ::OpenTelemetry::Context.current
+        # @return [Hash<String, String>]
+        def values(context: ::OpenTelemetry::Context.current)
+          trace = context.ensure_trace
+          return {} if trace.nil?
+
+          trace.baggage ? trace.baggage.dup : {}
+        end
+
+        # Returns a new context with new key-value pair
+        #
+        # @param [String] key The key to store this value under
+        # @param [String] value String value to be stored under key
+        # @param [optional String] metadata This is here to store properties
+        # received from other W3C Baggage implementations but is not exposed in
+        # OpenTelemetry. This is considered private API and not for use by
+        # end-users.
+        # @param [optional Context] context The context to update with new
+        # value. Defaults to ::OpenTelemetry::Context.current
+        # @return [Context]
+        def set_value(key, value, metadata: nil, context: ::OpenTelemetry::Context.current)
+          # Delegate to the context to set the value because an active trace is not guaranteed
+          # set_values handles this logic
+          context.set_values({::OpenTelemetry::Baggage.const_get(:BAGGAGE_KEY) => {key => value}})
+        end
+
+        # Returns a new context with value at key removed
+        #
+        # @param [String] key The key to remove
+        # @param [optional Context] context The context to remove baggage
+        # from. Defaults to ::OpenTelemetry::Context.current
+        # @return [Context]
+        def remove_value(key, context: ::OpenTelemetry::Context.current)
+          # Delegate to the context to remove the value because an active trace is not guaranteed
+          # set_values handles this logic
+          context.set_values({Context::BAGGAGE_REMOVE_KEY => key})
+        end
+        ::OpenTelemetry::Baggage.singleton_class.prepend(self)
+      end
+    end
+  end
+end

data/lib/datadog/opentelemetry/api/context.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'trace/span'
-require_relative '../../tracing/trace_operation'
-require_relative '../trace'
+require_relative "trace/span"
+require_relative "../../tracing/trace_operation"
+require_relative "../trace"
 
 module Datadog
   module OpenTelemetry
@@ -21,11 +21,13 @@ module Datadog
       module Context
         CURRENT_SPAN_KEY = ::OpenTelemetry::Trace.const_get(:CURRENT_SPAN_KEY)
         private_constant :CURRENT_SPAN_KEY
+        BAGGAGE_REMOVE_KEY = Object.new # sentinel object to indicate the deletion of a value in baggage
 
-        def initialize(entries, trace: nil)
+        def initialize(entries, trace: nil, baggage: nil)
           @trace = trace || ::Datadog::Tracing.send(:tracer).send(:start_trace)
           @trace.otel_values.merge!(entries) if entries
           @trace.otel_context ||= self
+          @trace.baggage = baggage if baggage
         end
 
         # Because Context can be reused, we have to make sure we have
@@ -48,7 +50,8 @@ module Datadog
           @trace.otel_value(key)
         end
 
-        alias [] value
+        # `alias` performed to match {::OpenTelemetry::Context} aliasing upstream
+        alias [] value # rubocop:disable Style/Alias
 
         # Returns a new Context where entries contains the newly added key and value
         #
@@ -78,9 +81,21 @@ module Datadog
             )
           end
 
-          existing_values = @trace && @trace.otel_values || {}
+          existing_values = @trace&.otel_values || {}
+          existing_baggage = @trace&.baggage || {}
 
-          ::OpenTelemetry::Context.new(existing_values.merge(values), trace: trace)
+          # Retrieve the baggage removal sentinel and remove it from the values hash
+          existing_baggage.delete(values[BAGGAGE_REMOVE_KEY]) if values.key?(BAGGAGE_REMOVE_KEY)
+
+          # If the values hash contains a BAGGAGE_KEY, merge its contents with existing baggage
+          # Otherwise, keep the existing baggage unchanged
+          new_baggage = if values.key?(::OpenTelemetry::Baggage.const_get(:BAGGAGE_KEY))
+            existing_baggage.merge(values[::OpenTelemetry::Baggage.const_get(:BAGGAGE_KEY)])
+          else
+            existing_baggage
+          end
+
+          ::OpenTelemetry::Context.new(existing_values.merge(values), trace: trace, baggage: new_baggage)
         end
 
         # The Datadog {TraceOperation} associated with this {Context}.
@@ -111,7 +126,7 @@ module Datadog
             previous_trace = Tracing.active_trace
             continue_trace!(context)
 
-            stack.push(previous_trace && previous_trace.otel_context || ::OpenTelemetry::Context::ROOT)
+            stack.push(previous_trace&.otel_context || ::OpenTelemetry::Context::ROOT)
             stack.size
           end
 
@@ -128,7 +143,7 @@ module Datadog
             unless calls_matched
               ::OpenTelemetry.handle_error(
                 exception: ::OpenTelemetry::Context::DetachError.new(
-                  'calls to detach should match corresponding calls to attach.'
+                  "calls to detach should match corresponding calls to attach."
                 )
               )
             end
@@ -154,7 +169,7 @@ module Datadog
 
           def continue_trace!(context, &block)
             call_context = Tracing.send(:tracer).send(:call_context)
-            if context && context.trace
+            if context&.trace
               call_context.activate!(context.ensure_trace, &block)
             else
               call_context.activate!(nil)