datadog 2.33.0 → 2.35.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

@@ -3,12 +3,16 @@
 require_relative 'scope'
 require_relative 'symbol'
 require_relative 'file_hash'
-require_relative '../core/utils/array'
+require_relative '../core/utils/enumerable_compat'
 
 module Datadog
   module SymbolDatabase
     # Extracts symbol metadata from loaded Ruby modules and classes via introspection.
     #
+    # 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.
     # Filters to user code only (excludes gems, stdlib, test files).
@@ -80,6 +84,11 @@ 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
       def initialize(logger:, settings:)
@@ -150,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
@@ -584,7 +593,7 @@ module Datadog
 
         return [] if params.nil? || params.empty?
 
-        Core::Utils::Array.filter_map(params) do |param_type, param_name|
+        Core::Utils::EnumerableCompat.filter_map(params) do |param_type, param_name|
           # Skip block parameters for MVP
           next if param_type == :block
 
@@ -605,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.
@@ -620,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)
@@ -782,7 +810,7 @@ module Datadog
       # @return [Scope] Scope object
       def convert_node_to_scope(node)
         # Build method scopes from collected method entries
-        method_scopes = Core::Utils::Array.filter_map(node[:methods]) do |method_info|
+        method_scopes = Core::Utils::EnumerableCompat.filter_map(node[:methods]) do |method_info|
           build_instance_method_scope(node[:mod], method_info[:name], method_info[:method])
         end
 

data/lib/datadog/symbol_database/remote.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Datadog
+  module SymbolDatabase
+    # Provides remote configuration integration for symbol database.
+    #
+    # Responsibilities:
+    # - Registers with Core::Remote as a receiver for LIVE_DEBUGGING_SYMBOL_DB product
+    # - Processes remote config changes (insert/update/delete)
+    # - Calls Component.start_upload when upload_symbols: true
+    # - Calls Component.stop_upload when config deleted or upload_symbols: false
+    #
+    # Flow:
+    # 1. Remote config system calls receiver with repository and changes
+    # 2. For each change, process_change called
+    # 3. parse_config extracts upload_symbols flag
+    # 4. enable_upload or disable_upload called on component
+    #
+    # Created by: Symbol database initialization
+    # Accessed by: Core::Remote system when configurations change
+    # Requires: Component must exist (accessed via Datadog.send(:components).symbol_database)
+    #
+    # @api private
+    module Remote
+      PRODUCT = 'LIVE_DEBUGGING_SYMBOL_DB'
+
+      class << self
+        # Declare products this receiver handles.
+        # @return [Array<String>] Product names
+        def products
+          [PRODUCT]
+        end
+
+        # Declare capabilities for this receiver.
+        # @return [Array] Capabilities (none for symbol database)
+        def capabilities
+          []
+        end
+
+        # Create receivers for remote configuration.
+        # @return [Array<Receiver>] Array of receivers
+        def receivers(_telemetry)
+          receiver do |repository, changes|
+            telemetry = lookup_telemetry
+            component = begin
+              Datadog.send(:components, allow_initialization: false)&.symbol_database
+            rescue => e
+              Datadog.logger.debug { "symdb: failed to look up component in RC receiver: #{e.class}: #{e.message}" }
+              telemetry&.report(e, description: 'symdb: failed to look up component in RC receiver')
+              nil
+            end
+
+            if component
+              changes.each do |change|
+                process_change(component, change, telemetry)
+              end
+            end
+          end
+        end
+
+        # Create a single receiver for the product.
+        # @param products [Array<String>] Product names to match
+        # @return [Array<Receiver>] Receiver array
+        def receiver(products = [PRODUCT], &block)
+          matcher = Core::Remote::Dispatcher::Matcher::Product.new(products)
+          [Core::Remote::Dispatcher::Receiver.new(matcher, &block)]
+        end
+
+        private
+
+        # Look up the telemetry component for error reporting. Returns nil if the
+        # component tree isn't built yet (very early boot) or the lookup raises.
+        # `allow_initialization: false` avoids triggering component-tree construction
+        # from inside an RC receiver callback.
+        # @return [Core::Telemetry::Component, nil]
+        # @api private
+        def lookup_telemetry
+          Datadog.send(:components, allow_initialization: false)&.telemetry
+        rescue
+          nil
+        end
+
+        # Process a single configuration change.
+        # @param component [Component] Symbol database component
+        # @param change [Change] Configuration change (:insert, :update, :delete)
+        # @param telemetry [Core::Telemetry::Component, nil] Telemetry for error reporting
+        # @return [void]
+        # @api private
+        def process_change(component, change, telemetry)
+          case change.type
+          when :insert
+            # @type var change: ::Datadog::Core::Remote::Configuration::Repository::Change::Inserted
+            enable_upload(component, change.content)
+            change.content.applied
+          when :update
+            # @type var change: ::Datadog::Core::Remote::Configuration::Repository::Change::Updated
+            disable_upload(component)
+            enable_upload(component, change.content)
+            change.content.applied
+          when :delete
+            # @type var change: ::Datadog::Core::Remote::Configuration::Repository::Change::Deleted
+            disable_upload(component)
+            change.previous&.applied
+          else
+            component.logger.debug { "symdb: unrecognized change type: #{change.type}" }
+            # Steep cannot narrow `change.content` from a respond_to? check — it sees
+            # the Repository::Change union type where `Deleted` lacks `content`.
+            change.content.errored("Unrecognized change type: #{change.type}") if change.respond_to?(:content) # steep:ignore NoMethod
+          end
+        rescue => e
+          component.logger.debug { "symdb: error processing remote config change: #{e.class}: #{e.message}" }
+          telemetry&.report(e, description: 'symdb: error processing remote config change')
+          # Rescue runs regardless of which branch raised — Steep cannot narrow the
+          # union type from a respond_to? check.
+          content_obj = change.respond_to?(:content) ? change.content : change.previous # steep:ignore NoMethod
+          content_obj&.errored(e.to_s)
+        end
+
+        # Enable upload if config has upload_symbols: true.
+        # @param component [Component] Symbol database component
+        # @param content [Content] Remote config content
+        # @return [void]
+        # @api private
+        def enable_upload(component, content)
+          config = parse_config(content, component.logger)
+
+          unless config
+            return
+          end
+
+          if config['upload_symbols']
+            component.logger.debug { "symdb: upload enabled via remote config" }
+            component.start_upload
+          else
+            component.logger.debug { "symdb: upload disabled in config" }
+          end
+        end
+
+        # Disable upload.
+        # @param component [Component] Symbol database component
+        # @return [void]
+        # @api private
+        def disable_upload(component)
+          component.logger.debug { "symdb: upload disabled via remote config" }
+          component.stop_upload
+        end
+
+        # Parse and validate remote config content.
+        # @param content [Content] Remote config content
+        # @param logger [SymbolDatabase::Logger] Logger for invalid-config diagnostics
+        # @return [Hash, nil] Parsed config or nil if invalid
+        # @api private
+        #
+        # JSON::ParserError is intentionally NOT rescued here — it propagates to
+        # process_change's rescue, which logs and reports to telemetry. Catching
+        # it locally would swallow the error from telemetry observability.
+        def parse_config(content, logger)
+          config = JSON.parse(content.data)
+
+          unless config.is_a?(Hash)
+            logger.debug { "symdb: invalid config format: expected Hash, got #{config.class}" }
+            return nil
+          end
+
+          unless config.key?('upload_symbols')
+            logger.debug { "symdb: missing 'upload_symbols' key in config" }
+            return nil
+          end
+
+          config
+        end
+      end
+    end
+  end
+end