datadog 2.29.0 → 2.31.0

data/lib/datadog/core/telemetry/worker.rb

@@ -27,6 +27,9 @@ module Datadog
           metrics_manager:,
           dependency_collection:,
           logger:,
+          settings:,
+          agent_settings:,
+          extended_heartbeat_interval_seconds:,
           enabled: true,
           shutdown_timeout: Workers::Polling::DEFAULT_SHUTDOWN_TIMEOUT,
           buffer_size: DEFAULT_BUFFER_MAX_SIZE
@@ -35,8 +38,11 @@ module Datadog
           @metrics_manager = metrics_manager
           @dependency_collection = dependency_collection
           @logger = logger
+          @settings = settings
+          @agent_settings = agent_settings
 
           @ticks_per_heartbeat = (heartbeat_interval_seconds / metrics_aggregation_interval_seconds).to_i
+          @ticks_per_extended_heartbeat = (extended_heartbeat_interval_seconds / metrics_aggregation_interval_seconds).to_i
           @current_ticks = 0
 
           # Workers::Polling settings
@@ -63,6 +69,7 @@ module Datadog
           self.buffer = buffer_klass.new(@buffer_size)
 
           @initial_event_once = Utils::OnlyOnceSuccessful.new(APP_STARTED_EVENT_RETRIES)
+          @extended_heartbeat_ticks = 0
         end
 
         attr_reader :logger
@@ -151,6 +158,13 @@ module Datadog
           end
 
           @current_ticks += 1
+          @extended_heartbeat_ticks += 1
+
+          if @extended_heartbeat_ticks >= @ticks_per_extended_heartbeat
+            @extended_heartbeat_ticks = 0
+            extended_heartbeat!
+          end
+
           return if @current_ticks < @ticks_per_heartbeat
 
           @current_ticks = 0
@@ -170,6 +184,12 @@ module Datadog
           send_event(Event::AppHeartbeat.new)
         end
 
+        def extended_heartbeat!
+          return if !enabled? || !sent_initial_event?
+
+          send_event(Event::AppExtendedHeartbeat.new(settings: @settings, agent_settings: @agent_settings))
+        end
+
         def started!
           return unless enabled?
 

data/lib/datadog/core/utils/base64.rb

@@ -14,7 +14,7 @@ module Datadog
         end
 
         def self.strict_decode64(str)
-          str.unpack1('m0')
+          str.unpack1('m0') #: String # 'm0' format always returns a String
         end
       end
     end

data/lib/datadog/core/utils/only_once.rb

@@ -3,7 +3,7 @@
 module Datadog
   module Core
     module Utils
-      # Helper class to execute something only once such as not repeating warning logs, and instrumenting classes
+      # Helper class to execute something only once, such as not repeating warning logs and instrumenting classes
       # only once.
       #
       # Thread-safe when used correctly (e.g. be careful of races when lazily initializing instances of this class).

data/lib/datadog/core/utils/spawn_monkey_patch.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Core
+    module Utils
+      module SpawnMonkeyPatch
+        # @param lineage_envs_provider [#call] returns a Hash of env vars to merge into the child process
+        def self.apply!(lineage_envs_provider:)
+          @lineage_envs_provider = lineage_envs_provider
+          ::Process.singleton_class.prepend(ProcessSpawnPatch)
+          true
+        end
+
+        module ProcessSpawnPatch
+          def spawn(*args, **opts)
+            args.replace(SpawnMonkeyPatch.inject_lineage_envs(args))
+            super
+          end
+        end
+
+        # Process.spawn(env?, cmd, ...): env is optional first arg (Hash). When present, merge
+        # runtime_ids into it; when absent, prepend full ENV + runtime_ids so the child inherits both.
+        def self.inject_lineage_envs(args)
+          runtime_ids = @lineage_envs_provider.call
+          env_provided = Hash === args.first
+
+          base_env = env_provided ? args.first : DATADOG_ENV.to_h
+          env = base_env.merge(runtime_ids)
+          rest = env_provided ? args.drop(1) : args
+
+          [env, *rest]
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/workers/async.rb

@@ -168,7 +168,7 @@ module Datadog
             rescue Exception => e
               @error = e
               Datadog.logger.debug(
-                "Worker thread error. Cause: #{e.class.name} #{e.message} Location: #{Array(e.backtrace).first}"
+                "Worker thread error. Cause: #{e.class}: #{e} Location: #{Array(e.backtrace).first}"
               )
               raise
 

data/lib/datadog/core/workers/interval_loop.rb

@@ -70,16 +70,23 @@ module Datadog
           true
         end
 
-        # TODO This overwrites Queue's +work_pending?+ method with an
-        # implementation that, to me, is at leat questionable semantically:
-        # the Queue's idea of pending work is if the buffer is not empty,
-        # but this module says that work is pending if the work processing
-        # loop is scheduled to run (in other words, as long as the background
-        # thread is running, there is always pending work).
+        # TODO: This method carries two semantics today:
+        # 1. Is there work available to process?
+        # 2. Should the main loop keep running?
+        # Things get messy when `Queue` is mixed in,
+        # wanting to override semantic 1 but not 2.
+        # This should probably be split into two methods:
+        # `work_pending?` (semantic 1) and `continue_loop?` (semantic 2).
+        # Today, `run_loop?` performs semantic 2, but should probably be
+        # renamed to `continue_loop?`, since that would make it clear that
+        # we're just checking if we can "keep going inside the loop",
+        # and not checking if we should run the loop right now.
+        # Clean up {Workers::Queue} after this.
         def work_pending?
           run_loop?
         end
 
+        # TODO: Probably should be renamed to `continue_loop?`, see `work_pending?` TODO.
         def run_loop?
           return false unless instance_variable_defined?(:@run_loop)
 

data/lib/datadog/core/workers/queue.rb

@@ -130,10 +130,6 @@ module Datadog
           # they all override +perform+ and the correct behavior depends on
           # placing IntervalLoop after Queue.
           #
-          # The TraceWriter worker then defines +work_pending?+ to be the
-          # same as Queue implementation here... Essentially, it demands
-          # the behavior that perhaps should be applied to all workers.
-          #
           # Until this mess is untangled, call +buffer.empty?+ here.
           buffer.empty? && !in_iteration?
         end

data/lib/datadog/core/workers/runtime_metrics.rb

@@ -21,7 +21,15 @@ module Datadog
           :metrics
 
         def initialize(telemetry:, **options)
-          @metrics = options.fetch(:metrics) { Core::Runtime::Metrics.new(logger: options[:logger], telemetry: telemetry) }
+          @metrics = options.fetch(:metrics) do
+            Core::Runtime::Metrics.new(
+              logger: options[:logger],
+              telemetry: telemetry,
+              experimental_propagate_process_tags_enabled: options.fetch(:propagate_process_tags_enabled) do
+                options.fetch(:experimental_propagate_process_tags_enabled)
+              end
+            )
+          end
 
           # Workers::Async::Thread settings
           self.fork_policy = options.fetch(:fork_policy, Workers::Async::Thread::FORK_POLICY_STOP)

data/lib/datadog/core.rb

@@ -22,7 +22,6 @@ module Datadog
       end
   end
 
-  DATADOG_ENV = Core::Configuration::ConfigHelper.new
   extend Core::Extensions
 
   # Add shutdown hook:

data/lib/datadog/data_streams/pathway_context.rb

@@ -46,7 +46,7 @@ module Datadog
           decode(binary_data)
         rescue ArgumentError => e
           # Invalid base64 encoding - may indicate version mismatch or corruption
-          Datadog.logger.debug("Failed to decode DSM pathway context: #{e.message}")
+          Datadog.logger.debug { "Failed to decode DSM pathway context: #{e.class}: #{e}" }
           nil
         end
       end

data/lib/datadog/data_streams/processor.rb

@@ -316,6 +316,7 @@ module Datadog
         end
 
         payload = {
+          'Env' => @settings.env || 'none',
           'Service' => @settings.service,
           'TracerVersion' => Datadog::VERSION::STRING,
           'Lang' => 'ruby',

data/lib/datadog/di/boot.rb

@@ -12,13 +12,13 @@ require_relative 'probe_builder'
 require_relative 'probe_manager'
 require_relative 'probe_notification_builder'
 require_relative 'probe_notifier_worker'
+require_relative 'probe_repository'
 require_relative 'redactor'
 require_relative 'serializer'
 require_relative 'transport/http'
 require_relative 'utils'
 
-# Steep: https://github.com/ruby/rbs/pull/2715
-if %w[1 true yes].include?(Datadog::DATADOG_ENV['DD_DYNAMIC_INSTRUMENTATION_ENABLED']) # steep:ignore ArgumentTypeMismatch
+if %w[1 true yes].include?(Datadog::DATADOG_ENV['DD_DYNAMIC_INSTRUMENTATION_ENABLED'])
 
   # For initial release of Dynamic Instrumentation, activate code tracking
   # only if DI is explicitly requested in the environment.
@@ -36,8 +36,7 @@ require_relative 'contrib'
 
 Datadog::DI::Contrib.load_now_or_later
 
-# Steep: https://github.com/ruby/rbs/pull/2715
-if %w[1 true yes].include?(Datadog::DATADOG_ENV['DD_DYNAMIC_INSTRUMENTATION_ENABLED']) # steep:ignore ArgumentTypeMismatch
+if %w[1 true yes].include?(Datadog::DATADOG_ENV['DD_DYNAMIC_INSTRUMENTATION_ENABLED'])
   if Datadog::DATADOG_ENV['DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE']
     require_relative 'probe_file_loader'
     Datadog::DI::ProbeFileLoader.load_now_or_later

data/lib/datadog/di/component.rb

@@ -49,6 +49,10 @@ module Datadog
             logger.warn("di: cannot enable dynamic instrumentation: Ruby 2.6+ is required, but running on #{RUBY_VERSION}")
             return false
           end
+          unless DI.respond_to?(:exception_message)
+            logger.warn("di: cannot enable dynamic instrumentation: C extension is not available")
+            return false
+          end
           true
         end
       end
@@ -63,9 +67,19 @@ module Datadog
         @redactor = Redactor.new(settings)
         @serializer = Serializer.new(settings, redactor, telemetry: telemetry)
         @instrumenter = Instrumenter.new(settings, serializer, logger, code_tracker: code_tracker, telemetry: telemetry)
-        @probe_notifier_worker = ProbeNotifierWorker.new(settings, logger, agent_settings: agent_settings, telemetry: telemetry)
+        @probe_repository = ProbeRepository.new
         @probe_notification_builder = ProbeNotificationBuilder.new(settings, serializer)
-        @probe_manager = ProbeManager.new(settings, instrumenter, probe_notification_builder, probe_notifier_worker, logger, telemetry: telemetry)
+        @probe_notifier_worker = ProbeNotifierWorker.new(
+          settings, logger,
+          agent_settings: agent_settings,
+          probe_repository: probe_repository,
+          probe_notification_builder: probe_notification_builder,
+          telemetry: telemetry,
+        )
+        @probe_manager = ProbeManager.new(
+          settings, instrumenter, probe_notification_builder, probe_notifier_worker, logger, probe_repository,
+          telemetry: telemetry,
+        )
         probe_notifier_worker.start
       end
 
@@ -75,6 +89,7 @@ module Datadog
       attr_reader :telemetry
       attr_reader :code_tracker
       attr_reader :instrumenter
+      attr_reader :probe_repository
       attr_reader :probe_notifier_worker
       attr_reader :probe_notification_builder
       attr_reader :probe_manager
@@ -106,8 +121,9 @@ module Datadog
           )
           payload = probe_notification_builder.build_errored(probe, exc)
           probe_notifier_worker.add_status(payload)
-        rescue # standard:disable Lint/UselessRescue
-          # TODO report via instrumentation telemetry?
+        rescue => nested_exc
+          logger.debug { "di: failed to build error notification: #{nested_exc.class}: #{nested_exc}" }
+          telemetry&.report(nested_exc, description: 'Error building probe error notification')
           raise
         end
 

data/lib/datadog/di/instrumenter.rb

@@ -147,17 +147,19 @@ module Datadog
                     # the probe notifier builder requires a context.
                     begin
                       responder.probe_condition_evaluation_failed_callback(context, exc)
-                    rescue
+                    rescue => nested_exc
                       raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-                      # TODO log / report via telemetry?
+                      instrumenter.logger.debug { "di: error in probe condition evaluation failed callback: #{nested_exc.class}: #{nested_exc}" }
+                      instrumenter.telemetry&.report(nested_exc, description: "Error in probe condition evaluation failed callback")
                     end
                   else
                     _ = 42 # stop standard from wrecking this code
 
                     raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-                    # TODO log / report via telemetry?
+                    instrumenter.logger.debug { "di: error evaluating condition without context (tracer bug?): #{exc.class}: #{exc}" }
+                    instrumenter.telemetry&.report(exc, description: "Error evaluating condition without context")
                     # If execution gets here, there is probably a bug in the tracer.
                   end
 
@@ -227,8 +229,7 @@ module Datadog
                 # that location here.
                 []
               end
-              # Steep: https://github.com/ruby/rbs/pull/2745
-              caller_locs = method_frame + caller_locations # steep:ignore ArgumentTypeMismatch
+              caller_locs = method_frame + caller_locations
               # TODO capture arguments at exit
 
               context = Context.new(locals: nil, target_self: self,
@@ -237,9 +238,16 @@ module Datadog
                 caller_locations: caller_locs,
                 return_value: rv, duration: duration, exception: exc,)
 
-              responder.probe_executed_callback(context)
+              begin
+                responder.probe_executed_callback(context)
+
+                instrumenter.send(:check_and_disable_if_exceeded, probe, responder, di_start_time, di_duration)
+              rescue => di_exc
+                raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-              instrumenter.send(:check_and_disable_if_exceeded, probe, responder, di_start_time, di_duration)
+                instrumenter.logger.debug { "di: unhandled exception in method probe: #{di_exc.class}: #{di_exc}" }
+                instrumenter.telemetry&.report(di_exc, description: "Unhandled exception in method probe")
+              end
 
               if exc
                 raise exc
@@ -525,10 +533,11 @@ module Datadog
               # the probe notifier builder requires a context.
               begin
                 responder.probe_condition_evaluation_failed_callback(context, condition, exc)
-              rescue
+              rescue => nested_exc
                 raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-                # TODO log / report via telemetry?
+                logger.debug { "di: error in probe condition evaluation failed callback: #{nested_exc.class}: #{nested_exc}" }
+                telemetry&.report(nested_exc, description: "Error in probe condition evaluation failed callback")
               end
 
               return
@@ -537,7 +546,8 @@ module Datadog
 
               raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-              # TODO log / report via telemetry?
+              logger.debug { "di: error evaluating condition without context (tracer bug?): #{exc.class}: #{exc}" }
+              telemetry&.report(exc, description: "Error evaluating condition without context")
               # If execution gets here, there is probably a bug in the tracer.
             end
           end

data/lib/datadog/di/probe_manager.rb

@@ -2,10 +2,11 @@
 
 # rubocop:disable Lint/AssignmentInCondition
 
-require 'monitor'
-
 module Datadog
   module DI
+    # Orchestrates probe lifecycle: installation, removal, and execution callbacks.
+    # Delegates probe storage to ProbeRepository.
+    #
     # Stores probes received from remote config (that we can parse, in other
     # words, whose type/attributes we support), requests needed instrumentation
     # for the probes via Instrumenter, and stores pending probes (those which
@@ -16,17 +17,14 @@ module Datadog
     # @api private
     class ProbeManager
       def initialize(settings, instrumenter, probe_notification_builder,
-        probe_notifier_worker, logger, telemetry: nil)
+        probe_notifier_worker, logger, probe_repository, telemetry: nil)
         @settings = settings
         @instrumenter = instrumenter
         @probe_notification_builder = probe_notification_builder
         @probe_notifier_worker = probe_notifier_worker
         @logger = logger
         @telemetry = telemetry
-        @installed_probes = {}
-        @pending_probes = {}
-        @failed_probes = {}
-        @lock = Monitor.new
+        @probe_repository = probe_repository
 
         @definition_trace_point = TracePoint.trace(:end) do |tp|
           install_pending_method_probes(tp.self)
@@ -40,7 +38,15 @@ module Datadog
 
       attr_reader :logger
       attr_reader :telemetry
+      attr_reader :probe_repository
 
+      # Shuts down the probe manager and releases all resources.
+      #
+      # Disables the class definition trace point and removes all installed
+      # probe instrumentation. Called during component teardown.
+      #
+      # @return [void]
+      #
       # TODO test that close is called during component teardown and
       # the trace point is cleared
       def close
@@ -48,13 +54,16 @@ module Datadog
         clear_hooks
       end
 
+      # Removes all installed probe instrumentation and clears the probe repository.
+      #
+      # Iterates through all installed probes, unhooks their instrumentation,
+      # and clears all probe collections (installed, pending, failed).
+      # Called during component shutdown to clean up resources.
+      #
+      # @return [void]
       def clear_hooks
-        @lock.synchronize do
-          @pending_probes.clear
-          @installed_probes.each do |probe_id, probe|
-            instrumenter.unhook(probe)
-          end
-          @installed_probes.clear
+        probe_repository.clear_all do |probe|
+          instrumenter.unhook(probe)
         end
       end
 
@@ -63,27 +72,6 @@ module Datadog
       attr_reader :probe_notification_builder
       attr_reader :probe_notifier_worker
 
-      def installed_probes
-        @lock.synchronize do
-          @installed_probes
-        end
-      end
-
-      def pending_probes
-        @lock.synchronize do
-          @pending_probes
-        end
-      end
-
-      # Probes that failed to instrument for reasons other than the target is
-      # not yet loaded are added to this collection, so that we do not try
-      # to instrument them every time remote configuration is processed.
-      def failed_probes
-        @lock.synchronize do
-          @failed_probes
-        end
-      end
-
       # Requests to install the specified probe.
       #
       # If the target of the probe does not exist, assume the relevant
@@ -92,9 +80,18 @@ module Datadog
       # defined, or files loaded, the probe will be checked against the
       # newly defined classes/loaded files, and will be installed if it
       # matches.
+      #
+      # On successful installation, sends INSTALLED status to the backend.
+      # On failure, sends ERROR status to the backend before re-raising.
+      #
+      # @param probe [Probe] the probe to install
+      # @return [Boolean] true if installed, false if pending
+      # @raise [Error::AlreadyInstrumented] if a probe with the same ID is already installed
+      # @raise [Error::ProbePreviouslyFailed] if a probe with the same ID previously failed
+      # @raise [StandardError] re-raises any other instrumentation error after recording failure
       def add_probe(probe)
-        @lock.synchronize do
-          if @installed_probes[probe.id]
+        probe_repository.synchronize do
+          if probe_repository.find_installed(probe.id)
             # Either this probe was already installed, or another probe was
             # installed with the same id (previous version perhaps?).
             # Since our state tracking is keyed by probe id, we cannot
@@ -108,7 +105,7 @@ module Datadog
           end
 
           # Probe failed to install previously, do not try to install it again.
-          if msg = @failed_probes[probe.id]
+          if msg = probe_repository.find_failed(probe.id)
             # TODO test this path
             raise Error::ProbePreviouslyFailed, msg
           end
@@ -116,43 +113,41 @@ module Datadog
           begin
             instrumenter.hook(probe, self)
 
-            @installed_probes[probe.id] = probe
+            probe_repository.add_installed(probe)
             payload = probe_notification_builder.build_installed(probe)
             probe_notifier_worker.add_status(payload, probe: probe)
             # The probe would only be in the pending probes list if it was
             # previously attempted to be installed and the target was not loaded.
             # Always remove from pending list here because it makes the
             # API smaller and shouldn't cause any actual problems.
-            @pending_probes.delete(probe.id)
+            probe_repository.remove_pending(probe.id)
             logger.trace { "di: installed #{probe.type} probe at #{probe.location} (#{probe.id})" }
             true
           rescue Error::DITargetNotDefined
-            @pending_probes[probe.id] = probe
+            probe_repository.add_pending(probe)
             logger.trace { "di: could not install #{probe.type} probe at #{probe.location} (#{probe.id}) because its target is not defined, adding it to pending list" }
             false
           end
-        rescue => exc
-          # In "propagate all exceptions" mode we will try to instrument again.
-          raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+        end
+      rescue => exc
+        # In "propagate all exceptions" mode we will try to instrument again.
+        raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
 
-          logger.debug { "di: error processing probe configuration: #{exc.class}: #{exc}" }
-          telemetry&.report(exc, description: "Error processing probe configuration")
-          # TODO report probe as failed to agent since we won't attempt to
-          # install it again.
+        logger.debug { "di: error processing probe configuration: #{exc.class}: #{exc}" }
+        telemetry&.report(exc, description: "Error processing probe configuration")
 
-          # TODO add top stack frame to message
-          @failed_probes[probe.id] = "#{exc.class}: #{exc}"
+        payload = probe_notification_builder.build_errored(probe, exc)
+        probe_notifier_worker.add_status(payload, probe: probe)
 
-          raise
-        end
+        probe_repository.add_failed(probe.id, "#{exc.class}: #{exc}")
+
+        raise
       end
 
       # Removes probe with specified id. The probe could be pending or
       # installed. Does nothing if there is no probe with the specified id.
       def remove_probe(probe_id)
-        @lock.synchronize do
-          @pending_probes.delete(probe_id)
-        end
+        probe_repository.remove_pending(probe_id)
 
         # Do not delete the probe from the registry here in case
         # deinstrumentation fails - though I don't know why deinstrumentation
@@ -161,10 +156,10 @@ module Datadog
         # in the future, and if deinstrumentation fails I would want to
         # keep that probe as "installed" for the count, so that we can
         # investigate the situation.
-        if probe = @installed_probes[probe_id]
+        if probe = probe_repository.find_installed(probe_id)
           begin
             instrumenter.unhook(probe)
-            @installed_probes.delete(probe_id)
+            probe_repository.remove_installed(probe_id)
           rescue => exc
             raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
             # Silence all exceptions?
@@ -180,9 +175,9 @@ module Datadog
       # This method is meant to be called from the "end" trace point,
       # which is invoked for each class definition.
       private def install_pending_method_probes(cls)
-        @lock.synchronize do
+        probe_repository.synchronize do
           # TODO search more efficiently than linearly
-          @pending_probes.each do |probe_id, probe|
+          probe_repository.pending_probes.each do |probe_id, probe|
             if probe.method?
               # TODO move this stringification elsewhere
               if probe.type_name == cls.name
@@ -190,8 +185,8 @@ module Datadog
                   # TODO is it OK to hook from trace point handler?
                   # TODO the class is now defined, but can hooking still fail?
                   instrumenter.hook(probe, self)
-                  @installed_probes[probe.id] = probe
-                  @pending_probes.delete(probe.id)
+                  probe_repository.add_installed(probe)
+                  probe_repository.remove_pending(probe.id)
                   break
                 rescue Error::DITargetNotDefined
                   # This should not happen... try installing again later?
@@ -200,6 +195,11 @@ module Datadog
 
                   logger.debug { "di: error installing #{probe.type} probe at #{probe.location} (#{probe.id}) after class is defined: #{exc.class}: #{exc}" }
                   telemetry&.report(exc, description: "Error installing probe after class is defined")
+
+                  payload = probe_notification_builder.build_errored(probe, exc)
+                  probe_notifier_worker.add_status(payload, probe: probe)
+
+                  probe_repository.add_failed(probe.id, "#{exc.class}: #{exc}")
                 end
               end
             end
@@ -217,8 +217,8 @@ module Datadog
         if path.nil?
           raise ArgumentError, "path must not be nil"
         end
-        @lock.synchronize do
-          @pending_probes.values.each do |probe|
+        probe_repository.synchronize do
+          probe_repository.pending_probes.values.each do |probe|
             if probe.line?
               if probe.file_matches?(path)
                 add_probe(probe)
@@ -248,6 +248,16 @@ module Datadog
         probe_notifier_worker.add_snapshot(payload)
       end
 
+      # Callback invoked when a probe's condition expression fails to evaluate.
+      #
+      # This can happen when the expression references undefined variables,
+      # has type mismatches, or encounters runtime errors during evaluation.
+      # Rate-limited to 1 notification per second per probe to avoid
+      # flooding the backend when conditions fail repeatedly.
+      #
+      # @param context [Context] The execution context containing probe and captured data
+      # @param expr [String] The condition expression that failed
+      # @param exc [Exception] The exception raised during condition evaluation
       def probe_condition_evaluation_failed_callback(context, expr, exc)
         probe = context.probe
         if probe.condition_evaluation_failed_rate_limiter&.allow?
@@ -256,6 +266,13 @@ module Datadog
         end
       end
 
+      # Callback invoked when a probe is disabled, for example due to
+      # exceeding the CPU consumption limit in DI processing.
+      #
+      # Sends ERROR status notification to the backend.
+      #
+      # @param probe [Probe] The probe that was disabled
+      # @param duration [Numeric] The CPU time consumed by probe processing, in seconds
       def probe_disabled_callback(probe, duration)
         payload = probe_notification_builder.build_disabled(probe, duration)
         probe_notifier_worker.add_status(payload, probe: probe)