datadog 2.46.0 → 2.48.0

data/lib/datadog/kit/appsec/events/v2.rb

@@ -50,7 +50,7 @@ module Datadog
 
               if trace.nil? || span.nil?
                 return Datadog.logger.warn(
-                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events",
                 )
               end
 
@@ -69,7 +69,7 @@ module Datadog
               record_event_telemetry_metric(LOGIN_SUCCESS_EVENT)
               ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", LOGIN_SUCCESS_EVENT)
 
-              return Kit::Identity.set_user(trace, span, **user_attributes) if user_attributes.key?(:id)
+              return Kit::Identity.set_user(trace, span, **user_attributes) if user_attributes.key?(:id) # steep:ignore InsufficientKeywordArguments
 
               # NOTE: This is a fallback for the case when we don't have an ID,
               #       but need to trigger WAF.
@@ -102,7 +102,7 @@ module Datadog
 
               if trace.nil? || span.nil?
                 return Datadog.logger.warn(
-                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events",
                 )
               end
 
@@ -155,7 +155,7 @@ module Datadog
 
               if trace.nil? || span.nil?
                 return Datadog.logger.warn(
-                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events",
                 )
               end
 
@@ -174,7 +174,7 @@ module Datadog
               record_event_telemetry_metric(SIGNUP_EVENT)
 
               if user_attributes.key?(:id)
-                Kit::Identity.set_user(trace, span, **user_attributes)
+                Kit::Identity.set_user(trace, span, **user_attributes) # steep:ignore InsufficientKeywordArguments
               else
                 # NOTE: {Datadog::Kit::Identity.set_user} requires an ID,
                 #       but WAF can evaluate login alone
@@ -235,7 +235,7 @@ module Datadog
 
               if telemetry.nil?
                 return Datadog.logger.debug(
-                  "Kit::AppSec: Telemetry component is unavailable. Skip recording SDK metrics"
+                  "Kit::AppSec: Telemetry component is unavailable. Skip recording SDK metrics",
                 )
               end
 

data/lib/datadog/kit/appsec/events.rb

@@ -160,7 +160,7 @@ module Datadog
             unless trace && span
               Datadog.logger.debug(
                 "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}" \
-                " to track this events"
+                " to track this events",
               )
               return
             end

data/lib/datadog/kit/enable_core_dumps.rb

@@ -31,7 +31,7 @@ module Datadog
         rescue => e
           Kernel.warn(
             "[datadog] Failed to enable core dumps. Cause: #{e.class}: #{e.message} " \
-            "Location: #{Array(e.backtrace).first}"
+            "Location: #{Array(e.backtrace).first}",
           )
           return
         end

data/lib/datadog/kit/identity.rb

@@ -96,7 +96,7 @@ module Datadog
           unless trace && span
             Datadog.logger.debug(
               "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}" \
-              " to track this events"
+              " to track this events",
             )
             return
           end

data/lib/datadog/open_feature/activation.rb

@@ -100,6 +100,7 @@ module Datadog
           return unless @providers.empty?
           if @delivery_source == Configuration::Source::REMOTE_CONFIG && @delivery_started
             # Remote Configuration is process-scoped and may already hold configuration needed by the next provider.
+            @logger.debug { "Feature Flags: provider detached; process-scoped Remote Configuration remains active" }
             [nil, nil]
           else
             previous_source = @configuration_source
@@ -149,9 +150,14 @@ module Datadog
         @activated = true
         unless resolution.enabled?
           @failure = "Feature Flags are disabled"
+          @logger.debug do
+            reason = @settings.feature_flags.enabled ? "the resolved configuration source is offline" : "feature_flags.enabled is false"
+            "Feature Flags: disabled because #{reason}"
+          end
           return
         end
 
+        @logger.debug { "Feature Flags: configuration source is #{resolution.source}" }
         component = Component.build(
           @settings,
           @agent_settings,
@@ -230,6 +236,20 @@ module Datadog
         end
 
         @configuration_source = configuration_source
+
+        @logger.debug do
+          agentless = @settings.feature_flags.agentless
+          sdk_env = @settings.env ? "sdk_env=#{@settings.env.inspect}" : "sdk_env is unset"
+          requested_env = if endpoint.managed?
+            @settings.env ? "requested_env=#{@settings.env.inspect}" : "requested_env is unset"
+          else
+            "requested_env is not sent (custom endpoint)"
+          end
+          "Feature Flags: starting agentless configuration source at #{endpoint.origin} " \
+            "(#{sdk_env}, #{requested_env}, " \
+            "poll interval #{agentless.poll_interval_seconds}s, request timeout #{agentless.request_timeout_seconds}s)"
+        end
+
         started = configuration_source.start
         @failure = "Feature Flags agentless delivery could not start" unless started
         started
@@ -241,7 +261,7 @@ module Datadog
           @failure = "Feature Flags Remote Configuration is unavailable"
           @logger.warn(
             "#{@failure}. To enable Remote Configuration, " \
-              "see https://docs.datadoghq.com/remote_configuration/."
+              "see https://docs.datadoghq.com/remote_configuration/.",
           )
           return false
         end
@@ -249,6 +269,7 @@ module Datadog
         receivers = @remote_receivers ||= Remote.receivers(
           @telemetry,
           component_provider: -> { @mutex.synchronize { @component } },
+          logger: @logger,
         )
         remote.register(
           capabilities: Remote.capabilities,
@@ -256,6 +277,10 @@ module Datadog
           receivers: receivers,
         )
         remote.start
+        @logger.debug do
+          sdk_env = @settings.env ? "sdk_env=#{@settings.env.inspect}" : "sdk_env is unset"
+          "Feature Flags: started Remote Configuration source (#{sdk_env}) using Datadog Agent"
+        end
         true
       end
 

data/lib/datadog/open_feature/agentless/configuration_source.rb

@@ -61,6 +61,7 @@ module Datadog
           @retry_wait = retry_wait || ->(delay) { wait_for_retry(delay) }
           @etag = nil
           @warned = {}
+          @failed_polls = 0
           @lifecycle_mutex = Mutex.new
           @started = false
           @stopped = false
@@ -91,6 +92,7 @@ module Datadog
           end
 
           super
+          @logger.debug { "Feature Flags: stopped agentless configuration polling" }
           true
         end
 
@@ -110,6 +112,7 @@ module Datadog
             return if stopped?
 
             response = @transport.get(@etag)
+            log_poll_attempt(response, attempt)
             unless retryable?(response)
               apply_response(response)
               return
@@ -120,7 +123,9 @@ module Datadog
               return
             end
 
-            return if wait_before_retry(retry_delay(attempt))
+            delay = retry_delay(attempt)
+            @logger.debug { "Feature Flags: retrying agentless configuration poll in #{delay.round(1)}s" }
+            return if wait_before_retry(delay)
 
             attempt += 1
           end
@@ -131,6 +136,7 @@ module Datadog
         def after_fork
           # The child must report its own failures, while the inherited ETag still matches its configuration.
           @warned = {}
+          @failed_polls = 0
           nil
         end
 
@@ -140,6 +146,53 @@ module Datadog
           @lifecycle_mutex.synchronize { @stopped }
         end
 
+        def log_poll_attempt(response, attempt)
+          @logger.debug do
+            status = response.status
+            outcome = case status
+            when nil
+              "failed: #{request_error_class(response)}"
+            when 304
+              "configuration unchanged (HTTP 304)"
+            when 200
+              etag = response.etag.to_s.strip
+              etag.empty? ? "configuration received (HTTP 200)" : "configuration received (ETag #{etag}; HTTP 200)"
+            else
+              "#{http_failure_reason(status)} (HTTP #{status})"
+            end
+            "Feature Flags: agentless configuration poll attempt #{attempt}/#{MAX_ATTEMPTS}: #{outcome}"
+          end
+        end
+
+        def http_failure_reason(status)
+          case status
+          when 400
+            "configuration request rejected as invalid"
+          when 401
+            "configuration request lacks valid authentication credentials"
+          when 403
+            "access to the configuration endpoint is forbidden"
+          when 404
+            "configuration endpoint not found"
+          when 408
+            "configuration request timed out"
+          when 429
+            "configuration request rate limited"
+          when 500
+            "configuration endpoint encountered an internal error"
+          when 502
+            "configuration endpoint received an invalid upstream response"
+          when 503
+            "configuration endpoint is temporarily unavailable"
+          when 504
+            "configuration endpoint timed out waiting for an upstream response"
+          when 500..599
+            "configuration endpoint reported a server error"
+          else
+            "unexpected response from the configuration endpoint"
+          end
+        end
+
         def retryable?(response)
           status = response.status
           return true unless status
@@ -181,17 +234,18 @@ module Datadog
         end
 
         def apply_response(response)
-          case response.status
+          status = response.status
+          case status
           when 200
+            log_recovery
             apply_configuration(response)
           when 304
-            nil
+            log_recovery
           when 401, 403
-            warn_once(:authentication) do
-              @logger.warn(
-                "Feature Flags agentless endpoint returned HTTP #{response.status}; verify endpoint authentication"
-              )
-            end
+            report_poll_failure(
+              :authentication,
+              "Feature Flags agentless #{http_failure_reason(status)}; verify endpoint authentication (HTTP #{status})",
+            )
           else
             warn_failure(response, 1)
           end
@@ -203,6 +257,9 @@ module Datadog
             warn_once(:malformed) do
               @logger.error("Feature Flags agentless endpoint returned malformed UFC payload")
             end
+            @logger.debug do
+              "Feature Flags: ignoring malformed agentless configuration payload"
+            end
             return
           end
 
@@ -224,16 +281,38 @@ module Datadog
           else
             :http_unexpected
           end
-          warn_once(category) do
-            if status
-              @logger.warn("Feature Flags agentless endpoint returned HTTP #{status} after #{attempts} attempt(s)")
-            else
-              error_class = response.error ? response.error.class : StandardError
-              @logger.warn("Feature Flags agentless request failed after #{attempts} attempt(s): #{error_class}")
-            end
+          refresh = (attempts == MAX_ATTEMPTS) ? "; next poll in #{@poll_interval_seconds}s" : ""
+          message = if status
+            "Feature Flags agentless #{http_failure_reason(status)} after #{attempts} attempt(s) (HTTP #{status})#{refresh}"
+          else
+            "Feature Flags agentless request failed after #{attempts} attempt(s): #{request_error_class(response)}#{refresh}"
+          end
+          report_poll_failure(category, message)
+        end
+
+        # Repeats are debug-only so a persistent outage does not flood warnings.
+        def report_poll_failure(category, message)
+          @failed_polls += 1
+          if @warned[category]
+            @logger.debug { message }
+          else
+            warn_once(category) { @logger.warn(message) }
           end
         end
 
+        def log_recovery
+          return if @failed_polls.zero?
+
+          failed_polls = @failed_polls
+          @failed_polls = 0
+          @logger.debug { "Feature Flags: agentless configuration delivery recovered after #{failed_polls} failed poll(s)" }
+        end
+
+        # Class only: transport error messages can embed endpoint details.
+        def request_error_class(response)
+          response.error ? response.error.class : StandardError
+        end
+
         def warn_once(category)
           return if @warned[category]
 

data/lib/datadog/open_feature/component.rb

@@ -13,6 +13,7 @@ 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"
+require_relative "hooks/debug_logging_hook"
 
 module Datadog
   module OpenFeature
@@ -70,12 +71,15 @@ module Datadog
         @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
+        @debug_logging_hook = nil
 
         @configuration_mutex = Mutex.new
         @reconfiguration_mutex = Mutex.new
         @configuration_condition = ConditionVariable.new
         @configuration_received = false
         @configuration_shutdown = false
+
+        @engine.warn_raw_data_logging
       end
 
       def reconfigure!(configuration)
@@ -102,9 +106,19 @@ module Datadog
         @on_configuration_change&.call(event) if event
       end
 
+      # Checked per evaluation so the SDK skips hook dispatch unless debug logging is on. Built lazily
+      # because Remote Configuration can build this component before the OpenFeature SDK loads.
+      def debug_logging_hook
+        return unless @logger.debug?
+
+        @engine.warn_raw_data_logging
+        @debug_logging_hook ||= create_debug_logging_hook
+      end
+
       def wait_for_configuration(&cancelled)
-        timeout_seconds = @settings.feature_flags.initialization_timeout_ms / 1000.0
-        deadline = Core::Utils::Time.get_time + timeout_seconds
+        timeout_ms = @settings.feature_flags.initialization_timeout_ms
+        @logger.debug { "Feature Flags: waiting up to #{timeout_ms}ms for configuration" }
+        deadline = Core::Utils::Time.get_time + timeout_ms / 1000.0
 
         @configuration_mutex.synchronize do
           loop do
@@ -176,6 +190,12 @@ module Datadog
         store = Hooks::SpanEnrichmentHook::SpanEnrichmentStateStore.new
         Hooks::SpanEnrichmentHook.new(store, logger: @logger)
       end
+
+      def create_debug_logging_hook
+        return unless Hooks::DebugLoggingHook.available?
+
+        Hooks::DebugLoggingHook.new(@logger)
+      end
     end
   end
 end

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

@@ -84,6 +84,12 @@ module Datadog
         def managed?
           @managed
         end
+
+        # Excludes userinfo, path, and query, which may carry credentials.
+        def origin
+          origin = "#{uri.scheme}://#{uri.host}"
+          (uri.port == uri.default_port) ? origin : "#{origin}:#{uri.port}"
+        end
       end
     end
   end

data/lib/datadog/open_feature/configuration.rb

@@ -44,7 +44,7 @@ module Datadog
 
                   Datadog.logger.warn(
                     "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED is deprecated; use " \
-                    "DD_FEATURE_FLAGS_ENABLED and DD_FEATURE_FLAGS_CONFIGURATION_SOURCE instead"
+                    "DD_FEATURE_FLAGS_ENABLED and DD_FEATURE_FLAGS_CONFIGURATION_SOURCE instead",
                   )
                 end
               end
@@ -78,6 +78,12 @@ module Datadog
                 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"
@@ -112,7 +118,7 @@ module Datadog
                       value
                     else
                       Datadog.logger.warn(
-                        "Feature Flags agentless poll interval must be positive; using the default"
+                        "Feature Flags agentless poll interval must be positive; using the default",
                       )
                       Settings::DEFAULT_POLL_INTERVAL_SECONDS
                     end
@@ -132,7 +138,7 @@ module Datadog
                     else
                       Datadog.logger.warn(
                         "Feature Flags agentless request timeout must be within (0, " \
-                        "#{Settings::MAX_REQUEST_TIMEOUT_SECONDS}]; using the default"
+                        "#{Settings::MAX_REQUEST_TIMEOUT_SECONDS}]; using the default",
                       )
                       Settings::DEFAULT_REQUEST_TIMEOUT_SECONDS
                     end
@@ -153,7 +159,7 @@ module Datadog
                   else
                     Datadog.logger.warn(
                       "Feature Flags provider initialization timeout must be within (0, " \
-                      "#{Settings::MAX_INITIALIZATION_TIMEOUT_MS}]; using the default"
+                      "#{Settings::MAX_INITIALIZATION_TIMEOUT_MS}]; using the default",
                     )
                     Settings::DEFAULT_INITIALIZATION_TIMEOUT_MS
                   end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require "json"
+
 require_relative "ext"
 require_relative "noop_evaluator"
 require_relative "native_evaluator"
 require_relative "resolution_details"
+require_relative "../core/utils/only_once"
 
 module Datadog
   module OpenFeature
@@ -14,10 +17,15 @@ module Datadog
 
       ALLOWED_TYPES = %i[boolean string number float integer object].freeze
 
+      RAW_DATA_WARNING = "Feature Flags: debug logging is enabled, so feature flag logs include raw evaluation data " \
+        "(targeting keys, evaluation context attributes, flag values, and default values) that may contain " \
+        "personal or sensitive information. Unset DD_TRACE_DEBUG when you no longer need it."
+
       def initialize(reporter, telemetry:, logger:)
         @reporter = reporter
         @telemetry = telemetry
         @logger = logger
+        @raw_data_warning = Core::Utils::OnlyOnce.new
 
         @evaluator = NoopEvaluator.new(nil)
       end
@@ -34,7 +42,7 @@ module Datadog
         unless ALLOWED_TYPES.include?(expected_type)
           message = "unknown type #{expected_type.inspect}, allowed types #{ALLOWED_TYPES.join(", ")}"
           result = ResolutionDetails.build_error(
-            value: default_value, error_code: Ext::UNKNOWN_TYPE, error_message: message
+            value: default_value, error_code: Ext::UNKNOWN_TYPE, error_message: message,
           )
 
           return with_observe_full_evaluation_data(result, observe_full_evaluation_data)
@@ -42,19 +50,21 @@ module Datadog
 
         context = evaluation_context&.fields.to_h
         result = evaluator.get_assignment(
-          flag_key, default_value: default_value, context: context, expected_type: expected_type
+          flag_key, default_value: default_value, context: context, expected_type: expected_type,
         )
 
         result = with_observe_full_evaluation_data(result, observe_full_evaluation_data)
+        log_resolution(flag_key, expected_type, result)
 
         @reporter.report(result, flag_key: flag_key, context: evaluation_context)
 
         result
       rescue => e
         @telemetry.report(e, description: "OpenFeature: Failed to fetch flag value")
+        log_resolution_failure(flag_key, e)
 
         result = ResolutionDetails.build_error(
-          value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
+          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`.
@@ -66,12 +76,13 @@ module Datadog
       #       in the format expected by `libdatadog` without any modifications
       def reconfigure!(configuration)
         if configuration.nil?
-          @logger.debug("OpenFeature: Removing configuration")
+          @logger.debug("Feature Flags: configuration removed")
 
           return @evaluator = NoopEvaluator.new(configuration)
         end
 
         @evaluator = NativeEvaluator.new(configuration)
+        @logger.debug { "Feature Flags: configuration applied; #{configuration_summary(configuration)}" }
       rescue => e
         message = "OpenFeature: Failed to reconfigure, reverting to the previous configuration"
 
@@ -81,8 +92,55 @@ module Datadog
         raise ReconfigurationError, "#{e.class}: #{e.message}"
       end
 
+      # Public so Component can warn before handing out DebugLoggingHook, which logs raw data.
+      def warn_raw_data_logging
+        return unless @logger.debug?
+
+        @raw_data_warning.run { @logger.warn(RAW_DATA_WARNING) }
+      end
+
       private
 
+      # The SDK can still replace this result, for example on a type mismatch; DebugLoggingHook logs the final one.
+      def log_resolution(flag_key, expected_type, result)
+        @logger.debug do
+          warn_raw_data_logging
+          "Feature Flags: provider resolved #{flag_key.inspect}: type=#{expected_type}, " \
+            "value=#{result.value.inspect}, variant=#{result.variant.inspect}, reason=#{result.reason.inspect}, " \
+            "allocation=#{result.allocation_key.inspect}, serial_id=#{result.serial_id.inspect}, " \
+            "error_code=#{result.error_code.inspect}, error_message=#{result.error_message.inspect}"
+        end
+      end
+
+      def log_resolution_failure(flag_key, error)
+        @logger.debug do
+          warn_raw_data_logging
+          "Feature Flags: provider failed to resolve #{flag_key.inspect}: #{error.class}: #{error.message}; " \
+            "returning the default value"
+        end
+      end
+
+      def configuration_summary(configuration)
+        payload = begin
+          JSON.parse(configuration)
+        rescue JSON::NestingError
+          # Native parsing accepts deeper JSON than Ruby's default nesting limit.
+          return "received payload metadata unavailable: JSON nesting exceeds the diagnostic parser limit"
+        end
+        return "received payload metadata unavailable: expected a JSON object" unless payload.is_a?(Hash)
+
+        flags = payload["flags"]
+        environment = payload["environment"]
+        environment_name = environment["name"] if environment.is_a?(Hash)
+        flag_count = flags.is_a?(Hash) ? "flag_count=#{flags.size}" : "flag_count is not specified"
+        environment_summary = environment_name ? "environment=#{environment_name.inspect}" : "environment is not specified"
+        created_at = payload["createdAt"]
+        creation_summary = created_at ? "created_at=#{created_at.inspect}" : "created_at is not specified"
+
+        "received payload: #{flag_count}, #{environment_summary}, #{creation_summary}; " \
+          "individual flags may still fail evaluation"
+      end
+
       # 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)

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

@@ -21,6 +21,10 @@ module Datadog
           super
         end
 
+        def pending_dropped_count
+          @dropped
+        end
+
         protected
 
         def drain!

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

@@ -19,21 +19,34 @@ module Datadog
         #       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?
+          return skip(flag_key, "no evaluation context") if context.nil?
+          return skip(flag_key, "the evaluation result is not marked for exposure logging") 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)
+          return skip(flag_key, "duplicate of the last exposure for this subject") if @deduplicator.duplicate?(key, value)
 
           event = Event.build(result, flag_key: flag_key, context: context)
-          @worker.enqueue(event)
+          return false unless @worker.enqueue(event)
+
+          @logger.debug do
+            "Feature Flags: queued exposure for #{flag_key.inspect} (allocation=#{result.allocation_key.inspect}, " \
+              "variant=#{result.variant.inspect}, targeting_key=#{context.targeting_key.inspect})"
+          end
+          true
         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
+
+        private
+
+        def skip(flag_key, reason)
+          @logger.debug { "Feature Flags: exposure for #{flag_key.inspect} not recorded: #{reason}" }
+          false
+        end
       end
     end
   end