datadog 2.32.0 → 2.34.0

data/lib/datadog/symbol_database/component.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+require_relative 'extractor'
+require_relative 'logger'
+require_relative 'scope_batcher'
+require_relative 'uploader'
+require_relative '../core/utils/time'
+
+module Datadog
+  module SymbolDatabase
+    # Main coordinator for symbol database upload functionality.
+    #
+    # Responsibilities:
+    # - Lifecycle management: Initialization, shutdown, upload triggering
+    # - Coordination: Connects Extractor → ScopeBatcher → Uploader
+    # - Remote config handling: start_upload called by Remote module on config changes
+    # - Debounce: extraction is deferred by EXTRACT_DEBOUNCE_INTERVAL seconds so
+    #   reconfigurations during boot coalesce into a single extraction on the
+    #   final Component instance.
+    #
+    # Upload flow:
+    # 1. Remote config sends upload_symbols: true (or force_upload mode)
+    # 2. start_upload called — schedules extraction EXTRACT_DEBOUNCE_INTERVAL
+    #    seconds in the future on a per-instance scheduler thread.
+    # 3. When the timer fires (no further start_upload calls reset it),
+    #    extract_and_upload runs: ObjectSpace iteration → Extractor → ScopeBatcher.
+    # 4. ScopeBatcher batches and triggers Uploader.
+    # 5. A class-level flag is set so subsequent Component instances created via
+    #    Datadog reconfiguration do not re-upload.
+    #
+    # Created by: Components#initialize (in Core::Configuration::Components)
+    # Accessed by: Remote config receiver via Datadog.send(:components).symbol_database
+    # Requires: Remote config enabled (unless force mode)
+    #
+    # @api private
+    class Component
+      # Debounce window for extraction. Multiple start_upload calls within this
+      # window coalesce; the timer fires once after the window of inactivity.
+      # Long enough to absorb reconfiguration cascades during Rails boot.
+      EXTRACT_DEBOUNCE_INTERVAL = 5  # seconds
+
+      # Class-level state: tracks whether any Component instance in this process
+      # has performed an extract+upload. Survives Component replacement during
+      # Datadog reconfiguration so duplicate uploads are prevented.
+      @uploaded_this_process = false
+      @upload_done_mutex = Mutex.new
+      @upload_done_cv = ConditionVariable.new
+
+      class << self
+        attr_reader :upload_done_mutex, :upload_done_cv
+
+        # Whether any Component instance in this process has completed an
+        # upload. Cross-instance flag — used to dedupe uploads across
+        # Component rebuilds within a single Ruby process.
+        # @return [Boolean]
+        def uploaded_this_process?
+          @upload_done_mutex.synchronize { @uploaded_this_process }
+        end
+
+        # Mark the current process as having completed a symbol upload.
+        # Called by the Component instance that successfully completes an
+        # upload; subsequent start_upload calls on any instance short-circuit.
+        # @return [void]
+        def mark_uploaded
+          @upload_done_mutex.synchronize do
+            @uploaded_this_process = true
+            @upload_done_cv.broadcast
+          end
+        end
+
+        # Reset class-level upload state. Test-only.
+        # @api private
+        def reset_uploaded_this_process_for_tests!
+          @upload_done_mutex.synchronize { @uploaded_this_process = false }
+        end
+      end
+
+      # Build a new Component if feature is enabled and dependencies met.
+      # @param settings [Configuration::Settings] Tracer settings
+      # @param agent_settings [Configuration::AgentSettings] Agent configuration
+      # @param logger [Logger] Logger instance
+      # @param telemetry [Core::Telemetry::Component, nil] Telemetry component for error reporting
+      # @return [Component, nil] Component instance or nil if not enabled/requirements not met
+      def self.build(settings, agent_settings, logger, telemetry: nil)
+        symdb_logger = SymbolDatabase::Logger.new(settings, logger)
+
+        unless settings.respond_to?(:symbol_database) && settings.symbol_database.enabled
+          symdb_logger.debug("symdb: symbol database upload not enabled, skipping")
+          return
+        end
+
+        # Symbol database requires MRI Ruby 2.6+.
+        # Configuration accessors (settings.symbol_database.*) remain available on all
+        # platforms — only the component (upload) is disabled on unsupported engines/versions.
+        # environment_supported? logs the specific reason (engine or version) internally.
+        return nil unless environment_supported?(symdb_logger)
+
+        # Requires remote config (unless force mode)
+        if !settings.remote&.enabled && !settings.symbol_database.internal.force_upload
+          symdb_logger.debug("symdb: remote config not available and force_upload not set, skipping")
+          return nil
+        end
+
+        new(settings, agent_settings, symdb_logger, telemetry: telemetry).tap do |component|
+          # Defer extraction if force upload mode — wait for app boot to complete
+          component.schedule_deferred_upload if settings.symbol_database.internal.force_upload
+        end
+      end
+
+      attr_reader :settings, :logger, :last_upload_time, :last_upload_scope_count, :upload_in_progress
+
+      # Initialize component.
+      # @param settings [Configuration::Settings] Tracer settings
+      # @param agent_settings [Configuration::AgentSettings] Agent configuration
+      # @param logger [Logger] Logger instance
+      # @param telemetry [Core::Telemetry::Component, nil] Telemetry component for error reporting
+      def initialize(settings, agent_settings, logger, telemetry: nil)
+        @settings = settings
+        @agent_settings = agent_settings
+        @logger = logger
+        @telemetry = telemetry
+
+        @extractor = Extractor.new(logger: logger, settings: settings)
+        @uploader = Uploader.new(settings: settings, agent_settings: agent_settings, logger: logger, telemetry: telemetry)
+        @scope_batcher = ScopeBatcher.new(@uploader, logger: logger)
+
+        @last_upload_time = nil
+        @last_upload_scope_count = nil
+        @mutex = Mutex.new
+        @upload_in_progress = false
+        @upload_in_progress_cv = ConditionVariable.new
+        @shutdown = false
+
+        # Per-instance scheduler state. The scheduler thread is started lazily
+        # on the first start_upload call.
+        @scheduler_mutex = Mutex.new
+        @scheduler_cv = ConditionVariable.new
+        @scheduled_at = nil
+        @scheduler_signaled = false
+        @scheduler_thread = nil
+      end
+
+      # Schedule a deferred upload that waits for app boot to complete.
+      #
+      # In Rails: registers ActiveSupport.on_load(:after_initialize). When the
+      # hook has already fired (e.g., this Component was built by a reconfigure
+      # after Rails finished initializing), the callback runs immediately.
+      #
+      # In non-Rails: triggers start_upload immediately.
+      #
+      # Each Component registers its own callback. Old Components that have
+      # been shut down short-circuit in start_upload via @shutdown.
+      # Cross-process deduplication is handled by the class-level
+      # uploaded_this_process? flag, not by guarding registration.
+      #
+      # @return [void]
+      def schedule_deferred_upload
+        if defined?(::ActiveSupport) && defined?(::Rails::Railtie)
+          # Capture self — on_load runs the block via instance_exec on the
+          # loaded object (Rails::Application), so a bare `start_upload`
+          # would resolve against it.
+          component = self
+          logger = @logger
+          ::ActiveSupport.on_load(:after_initialize) do
+            # Only auto-trigger when Rails has eager-loaded application
+            # classes during initialization. In dev (eager_load=false)
+            # there is nothing complete to extract; the auto-deferred
+            # upload would race with explicit triggers and produce
+            # under-extracted uploads.
+            if defined?(::Rails) && ::Rails.application&.config&.eager_load # steep:ignore NoMethod
+              component.start_upload
+            else
+              logger.debug { "symdb: skipping auto-deferred upload (eager_load disabled)" }
+            end
+          end
+        else
+          start_upload
+        end
+      end
+
+      # Whether this component has been shut down.
+      # @return [Boolean]
+      def shutdown?
+        @scheduler_mutex.synchronize { @shutdown }
+      end
+
+      # Schedule symbol upload (triggered by remote config or force mode).
+      # The actual extraction is debounced by EXTRACT_DEBOUNCE_INTERVAL seconds —
+      # subsequent calls within the window restart the timer.
+      # Thread-safe: can be called concurrently from multiple remote config updates.
+      # @return [void]
+      def start_upload
+        return if Component.uploaded_this_process?
+
+        @scheduler_mutex.synchronize do
+          return if @shutdown
+
+          @scheduled_at = Datadog::Core::Utils::Time.get_time + EXTRACT_DEBOUNCE_INTERVAL
+          @scheduler_signaled = true
+          @scheduler_cv.signal
+          ensure_scheduler_thread
+        end
+      rescue => e
+        @logger.debug { "symdb: error scheduling upload: #{e.class}: #{e.message}" }
+        @telemetry&.report(e, description: 'symdb: error scheduling upload')
+      end
+
+      # Stop symbol upload (cancel the scheduler).
+      # Thread-safe: can be called concurrently from multiple remote config updates.
+      # @return [void]
+      def stop_upload
+        @scheduler_mutex.synchronize do
+          @scheduled_at = nil
+          @scheduler_signaled = true
+          @scheduler_cv.signal
+        end
+      end
+
+      # Block until any Component in this process has finished an extract+upload,
+      # or until the timeout elapses. Used by short-lived scripts that trigger
+      # an upload via force_upload and need to wait before exiting.
+      # @param timeout [Numeric] Maximum seconds to wait
+      # @return [Boolean] true if an upload completed; false on timeout
+      def wait_for_idle(timeout: 30)
+        deadline = Datadog::Core::Utils::Time.get_time + timeout
+        Component.upload_done_mutex.synchronize do
+          # Read @uploaded_this_process directly: we already hold
+          # Component.upload_done_mutex here, and uploaded_this_process?
+          # would try to re-acquire it (non-reentrant), deadlocking.
+          until Component.instance_variable_get(:@uploaded_this_process)
+            remaining = deadline - Datadog::Core::Utils::Time.get_time
+            return false if remaining <= 0
+            Component.upload_done_cv.wait(Component.upload_done_mutex, remaining)
+          end
+        end
+        true
+      end
+
+      # Shutdown component and cleanup resources.
+      # Cancels the per-instance scheduler so any pending debounced extraction
+      # is dropped. Waits for an in-flight extraction to complete before
+      # returning. Does not touch class-level state, so a sibling Component
+      # built after shutdown can still upload.
+      # @return [void]
+      def shutdown!
+        @scheduler_mutex.synchronize do
+          @shutdown = true
+          @scheduler_signaled = true
+          @scheduler_cv.signal
+        end
+        @scheduler_thread&.join(5)
+        @scheduler_thread = nil
+
+        @mutex.synchronize do
+          if @upload_in_progress
+            @upload_in_progress_cv.wait(@mutex, 5)
+          end
+        end
+
+        @scope_batcher.shutdown
+      end
+
+      private
+
+      # Check whether the runtime environment supports symbol database upload.
+      # Only MRI Ruby 2.6+ is supported. JRuby and TruffleRuby are not supported
+      # because ObjectSpace iteration and Method#source_location behave differently.
+      # Configuration accessors remain available on all platforms — this only gates
+      # the component (upload) itself.
+      # @param logger [Logger]
+      # @return [Boolean]
+      def self.environment_supported?(logger)
+        if RUBY_ENGINE != 'ruby'
+          logger.debug { "symdb: not supported on #{RUBY_ENGINE}, skipping" }
+          return false
+        end
+        if RUBY_VERSION < '2.6'
+          logger.debug { "symdb: requires Ruby 2.6+, running #{RUBY_VERSION}, skipping" }
+          return false
+        end
+        true
+      end
+      private_class_method :environment_supported?
+
+      # Start the scheduler thread if not already running.
+      # Must be called from within @scheduler_mutex.synchronize.
+      # @return [void]
+      def ensure_scheduler_thread
+        return if @scheduler_thread&.alive?
+        @scheduler_thread = Thread.new { scheduler_loop }
+      end
+
+      # Scheduler thread main loop. Waits for the debounce window to elapse,
+      # then runs extract_and_upload exactly once for this Component.
+      # @return [void]
+      def scheduler_loop
+        loop do
+          # should_fire = true means the debounce deadline elapsed without further
+          # signals; extract_and_upload runs once after the mutex is released.
+          should_fire = false
+
+          @scheduler_mutex.synchronize do
+            return if @shutdown
+            return if Component.uploaded_this_process?
+
+            # Copy to local so Steep narrows `Float?` to `Float` in the else branch.
+            # Steep does not track narrowing on instance variables across nil checks.
+            scheduled_at = @scheduled_at
+            if scheduled_at.nil?
+              # Nothing scheduled (e.g. stop_upload cleared it). Wait
+              # indefinitely for a signal, then re-evaluate on next loop.
+              @scheduler_signaled = false
+              @scheduler_cv.wait(@scheduler_mutex)
+            else
+              remaining = scheduled_at - Datadog::Core::Utils::Time.get_time
+              if remaining > 0
+                # Wait until the debounce deadline. Any signal (start_upload,
+                # stop_upload, shutdown!) wakes us early; we always re-loop
+                # and recompute rather than firing immediately on wake.
+                @scheduler_signaled = false
+                @scheduler_cv.wait(@scheduler_mutex, remaining)
+              else
+                # Deadline elapsed without further signal — fire after releasing the mutex.
+                should_fire = true
+              end
+            end
+          end
+
+          # `next` inside `synchronize` only exits the synchronize block — not the
+          # surrounding loop. Use an explicit flag so the loop only fires
+          # extract_and_upload when the debounce deadline has actually elapsed.
+          next unless should_fire
+
+          # Outside the mutex.
+          return if @shutdown
+          if Component.uploaded_this_process?
+            return
+          end
+
+          extract_and_upload
+          Component.mark_uploaded
+          return
+        end
+      rescue => e
+        @logger.debug { "symdb: scheduler error: #{e.class}: #{e.message}" }
+        @telemetry&.report(e, description: 'symdb: scheduler error')
+      end
+
+      # Extract symbols from all loaded modules and upload.
+      # @return [void]
+      def extract_and_upload
+        @mutex.synchronize { @upload_in_progress = true }
+
+        begin
+          @logger.trace { "symdb: starting extraction and upload" }
+          start_time = Datadog::Core::Utils::Time.get_time
+
+          # Extract symbols from all loaded modules grouped by source file.
+          # extract_all handles ObjectSpace iteration, filtering, and FQN-based nesting.
+          file_scopes = @extractor.extract_all
+          extracted_count = 0
+          file_scopes.each do |scope|
+            @scope_batcher.add_scope(scope)
+            extracted_count += 1
+            log_scope_tree(scope, 0)
+          end
+
+          @logger.debug do
+            extraction_duration = Datadog::Core::Utils::Time.get_time - start_time
+            targetable_count = count_targetable_methods(file_scopes)
+            "symdb: extracted #{extracted_count} scopes (#{targetable_count} methods with targetable lines) in #{'%.2f' % extraction_duration}s"
+          end
+
+          # Flush any remaining scopes (triggers upload)
+          @scope_batcher.flush
+
+          @last_upload_time = Datadog::Core::Utils::Time.now
+          @last_upload_scope_count = extracted_count
+        rescue => e
+          @logger.debug { "symdb: extraction error: #{e.class}: #{e.message}" }
+          @telemetry&.report(e, description: 'symdb: extraction error')
+        ensure
+          @mutex.synchronize do
+            @upload_in_progress = false
+            @upload_in_progress_cv.signal
+          end
+        end
+      end
+
+      def log_scope_tree(scope, depth)
+        indent = '  ' * depth
+        @logger.trace { "symdb:   #{indent}#{scope.scope_type} #{scope.name}" }
+        scope.scopes&.each { |child| log_scope_tree(child, depth + 1) }
+      end
+
+      def count_targetable_methods(file_scopes)
+        count = 0
+        file_scopes.each do |file_scope|
+          file_scope.scopes&.each do |class_or_module|
+            class_or_module.scopes&.each do |method_scope|
+              count += 1 if method_scope.scope_type == 'METHOD' && method_scope.targetable_lines?
+            end
+          end
+        end
+        count
+      end
+    end
+  end
+end

data/lib/datadog/symbol_database/configuration.rb

@@ -7,7 +7,7 @@ module Datadog
       # Configuration settings for symbol database upload feature.
       #
       # Public environment variable:
-      # - DD_SYMBOL_DATABASE_UPLOAD_ENABLED (default: true) - Feature gate
+      # - DD_SYMBOL_DATABASE_UPLOAD_ENABLED (default: false) - Feature gate
       #
       # Extended into: Core::Configuration::Settings (via extend)
       # Accessed as: Datadog.configuration.symbol_database.enabled
@@ -31,7 +31,7 @@ module Datadog
               option :enabled do |o|
                 o.type :bool
                 o.env 'DD_SYMBOL_DATABASE_UPLOAD_ENABLED'
-                o.default true
+                o.default false
               end
 
               # Settings in the 'internal' group are for internal Datadog

data/lib/datadog/symbol_database/extractor.rb

@@ -9,9 +9,9 @@ module Datadog
   module SymbolDatabase
     # Extracts symbol metadata from loaded Ruby modules and classes via introspection.
     #
-    # Instance created by Component with injected dependencies (logger, settings,
-    # telemetry). All methods are instance methods accessing @logger, @settings,
-    # @telemetry directly — no parameter threading needed.
+    # Instance created by Component with injected dependencies (logger, settings).
+    # All methods are instance methods accessing @logger, @settings directly —
+    # no parameter threading needed.
     #
     # Uses Ruby's reflection APIs (Module#constants, Class#instance_methods, Method#parameters)
     # to build hierarchical Scope structures representing code organization.
@@ -46,10 +46,9 @@ module Datadog
     #    for post-hoc diagnosis, return nil or empty array. One bad method/module
     #    doesn't kill the entire class extraction.
     #
-    # 3. **Top-level entry rescues** (`rescue => e` with logging + telemetry):
+    # 3. **Top-level entry rescues** (`rescue => e` with logging):
     #    extract() and extract_all() are the error boundaries. Any exception that
-    #    escapes layers 1-2 is caught here, logged, and tracked via telemetry.
-    #    These are the only rescue blocks that increment telemetry counters.
+    #    escapes layers 1-2 is caught here and logged.
     #
     # @api private
     class Extractor
@@ -71,11 +70,11 @@ module Datadog
       EXCLUDED_COMMON_MODULES = ['Kernel', 'PP::', 'JSON::', 'Enumerable', 'Comparable'].freeze
 
       # RubyVM::InstructionSequence#trace_points event types included when
-      # computing injectable lines on METHOD scopes.
+      # computing targetable lines on METHOD scopes.
       # :line — any line with executable bytecode (primary line probe target)
       # :return — last expression before method returns (DI instruments return events)
       # :call excluded — method entry is handled by method probes, not line probes
-      INJECTABLE_LINE_EVENTS = [:line, :return].freeze
+      TARGETABLE_LINE_EVENTS = [:line, :return].freeze
 
       # Cached unbound Module#singleton_class? — dispatched explicitly so user classes
       # that define their own `singleton_class?` (e.g. with required arguments) cannot
@@ -85,13 +84,16 @@ module Datadog
       MODULE_SINGLETON_CLASS_PRED = Module.instance_method(:singleton_class?)
       private_constant :MODULE_SINGLETON_CLASS_PRED
 
+      # Cached UnboundMethod for Module#name — avoids resolving it on every
+      # safe_mod_name call. Some classes override .name (e.g. Faker::Travel::Airport),
+      # so we bind the original Module#name to get the real module name safely.
+      MODULE_NAME = Module.instance_method(:name)
+
       # @param logger [Logger] Logger instance (SymbolDatabase::Logger facade or compatible)
       # @param settings [Configuration::Settings] Tracer settings
-      # @param telemetry [Telemetry, nil] Optional telemetry for metrics
-      def initialize(logger:, settings:, telemetry: nil)
+      def initialize(logger:, settings:)
         @logger = logger
         @settings = settings
-        @telemetry = telemetry
       end
 
       # Extract symbols from a single module or class.
@@ -125,7 +127,6 @@ module Datadog
         wrap_in_file_scope(source_file, [inner_scope])
       rescue => e
         @logger.debug { "symdb: failed to extract #{mod_name || '<unknown>'}: #{e.class}: #{e.message}" }
-        @telemetry&.inc('tracers', 'symbol_database.extract_error', 1)
         nil
       end
 
@@ -147,7 +148,6 @@ module Datadog
         convert_trees_to_scopes(file_trees)
       rescue => e
         @logger.debug { "symdb: error in extract_all: #{e.class}: #{e.message}" }
-        @telemetry&.inc('tracers', 'symbol_database.extract_all_error', 1)
         []
       end
 
@@ -159,7 +159,7 @@ module Datadog
       # @param mod [Module] The module
       # @return [String, nil] Module name or nil
       def safe_mod_name(mod)
-        Module.instance_method(:name).bind(mod).call
+        MODULE_NAME.bind(mod).call
       rescue => e
         @logger.debug { "symdb: safe_mod_name failed: #{e.class}: #{e.message}" }
         nil
@@ -399,7 +399,7 @@ module Datadog
           location = method.source_location
           next unless location && location[0]
           starts << location[1]
-          _ranges, method_end = extract_injectable_lines(method, location[1])
+          _ranges, method_end = extract_targetable_lines(method, location[1])
           ends << method_end
         end
 
@@ -491,7 +491,7 @@ module Datadog
         source_file, line = location
         return nil unless user_code_path?(source_file)  # Skip gem/stdlib methods
 
-        injectable_lines, end_line = extract_injectable_lines(method, line)
+        targetable_lines, end_line = extract_targetable_lines(method, line)
 
         Scope.new(
           scope_type: 'METHOD',
@@ -499,7 +499,7 @@ module Datadog
           source_file: source_file,
           start_line: line,
           end_line: end_line,
-          injectible_lines: injectable_lines,
+          targetable_lines: targetable_lines,
           language_specifics: {
             visibility: method_visibility(klass, method_name),
             method_type: method_type.to_s,
@@ -526,29 +526,29 @@ module Datadog
         end
       end
 
-      # Extract injectable lines and end_line from a method's bytecode.
+      # Extract targetable lines and end_line from a method's bytecode.
       # Returns [ranges, end_line] where ranges is an array of {start:, end:} hashes
       # or nil if iseq is unavailable (C-extension methods).
       # @param method [Method, UnboundMethod] The method
       # @param start_line [Integer] Fallback end_line if iseq unavailable
       # @return [Array(Array<Hash>, Integer), Array(nil, Integer)]
-      def extract_injectable_lines(method, start_line)
+      def extract_targetable_lines(method, start_line)
         iseq = RubyVM::InstructionSequence.of(method) # steep:ignore
         unless iseq
-          @logger.debug { "symdb: no iseq for #{method.name} (C extension or native), skipping injectable lines" }
+          @logger.debug { "symdb: no iseq for #{method.name} (C extension or native), skipping targetable lines" }
           return [nil, start_line]
         end
 
         lines = iseq.trace_points
-          .select { |_, event| INJECTABLE_LINE_EVENTS.include?(event) }
+          .select { |_, event| TARGETABLE_LINE_EVENTS.include?(event) }
           .map(&:first)
           .uniq
           .sort
 
         end_line = lines.max || start_line
-        ranges = build_injectable_ranges(lines)
+        ranges = build_targetable_ranges(lines)
         result = ranges.empty? ? nil : ranges
-        @logger.debug { "symdb: #{method.name} injectable lines: #{result ? "#{ranges.size} range(s), lines #{lines.first}..#{lines.last}" : 'none (no matching events)'}" }
+        @logger.debug { "symdb: #{method.name} targetable lines: #{result ? "#{ranges.size} range(s), lines #{lines.first}..#{lines.last}" : 'none (no matching events)'}" }
         [result, end_line]
       end
 
@@ -556,7 +556,7 @@ module Datadog
       # [4, 5, 6, 8, 10, 11] => [{start: 4, end: 6}, {start: 8, end: 8}, {start: 10, end: 11}]
       # @param lines [Array<Integer>] Sorted, deduplicated line numbers
       # @return [Array<Hash>] Array of {start:, end:} range hashes
-      def build_injectable_ranges(lines)
+      def build_targetable_ranges(lines)
         return [] if lines.empty?
 
         ranges = []
@@ -614,10 +614,26 @@ module Datadog
 
       # ── extract_all helpers ──────────────────────────────────────────────
 
+      # Sleep between chunks of modules processed in collect_extractable_modules so
+      # request-handling threads have guaranteed CPU time while extraction is in
+      # flight. Unlike Thread.pass (which only offers the GVL among runnable
+      # threads and leaves the extractor immediately re-runnable), sleep removes
+      # the extractor thread from the runnable set for a fixed duration, capping
+      # its CPU share at sleep_work_ratio regardless of GVL scheduling.
+      #
+      # The cadence is measured in modules that pass the singleton-class fast-path
+      # skip — singleton classes are discarded in microseconds and counting them
+      # would add wall-clock delay disproportionate to the work being done (e.g.
+      # on heavily monkey-patched processes that retain large singleton chains).
+      SLEEP_EVERY_N_MODULES = 100
+      SLEEP_SECONDS = 0.001
+      private_constant :SLEEP_EVERY_N_MODULES, :SLEEP_SECONDS
+
       # Pass 1: Collect all extractable modules with methods grouped by source file.
       # @return [Hash] { mod_name => { mod:, methods_by_file: { path => [{name:, method:, type:}] } } }
       def collect_extractable_modules
         entries = {}
+        seen = 0
 
         ObjectSpace.each_object(Module) do |mod|
           # Singleton classes (per-object metaclasses) are never user-code classes.
@@ -629,6 +645,9 @@ module Datadog
           # processes. Ruby 2.7+ optimized this path; the skip is a no-op there.
           next if MODULE_SINGLETON_CLASS_PRED.bind(mod).call
 
+          seen += 1
+          sleep SLEEP_SECONDS if (seen % SLEEP_EVERY_N_MODULES).zero?
+
           mod_name = safe_mod_name(mod)
           next unless mod_name
           next unless user_code_module?(mod)
@@ -840,7 +859,7 @@ module Datadog
 
         source_file, line = location
 
-        injectable_lines, end_line = extract_injectable_lines(method, line)
+        targetable_lines, end_line = extract_targetable_lines(method, line)
 
         Scope.new(
           scope_type: 'METHOD',
@@ -848,7 +867,7 @@ module Datadog
           source_file: source_file,
           start_line: line,
           end_line: end_line,
-          injectible_lines: injectable_lines,
+          targetable_lines: targetable_lines,
           language_specifics: {
             visibility: klass ? method_visibility(klass, method_name) : 'public', # steep:ignore
             method_type: 'instance',