debug-agent 0.3.0 → 0.5.0

data/lib/debug_agent/inspectors/gc.rb

@@ -62,6 +62,59 @@ module DebugAgent
     { error: e.message }
   end
 
+  register_tool('get_gc_profiler_detail',
+                'Get GC::Profiler raw data with computed stats: total time, count, ' \
+                'min/avg/max GC time, total mark and sweep time, per-GC entries') do
+    unless defined?(GC::Profiler)
+      next { enabled: false, message: 'GC::Profiler is not available on this Ruby implementation' }
+    end
+
+    raw_data = GC::Profiler.raw_data
+    total_time = GC::Profiler.total_time
+
+    if raw_data.nil? || raw_data.empty?
+      next {
+        enabled: true,
+        total_gc_time_seconds: 0,
+        gc_count: 0,
+        message: 'GC::Profiler has no data. Call GC::Profiler.enable to start collecting.'
+      }
+    end
+
+    gc_times = raw_data.map { |e| e[:GC_TIME].to_f }
+    mark_times = raw_data.map { |e| e[:GC_MARK_TIME].to_f }
+    sweep_times = raw_data.map { |e| e[:GC_SWEEP_TIME].to_f }
+    avg = gc_times.sum / gc_times.size
+
+    {
+      enabled: true,
+      total_gc_time_seconds: total_time.round(6),
+      gc_count: raw_data.size,
+      gc_time_stats_ms: {
+        min: (gc_times.min * 1000).round(3),
+        avg: (avg * 1000).round(3),
+        max: (gc_times.max * 1000).round(3)
+      },
+      total_mark_time_seconds: mark_times.sum.round(6),
+      total_sweep_time_seconds: sweep_times.sum.round(6),
+      entries: raw_data.map.with_index do |entry, i|
+        {
+          index: i,
+          gc_time_ms: (entry[:GC_TIME].to_f * 1000).round(3),
+          gc_invoke_time: entry[:GC_INVOKE_TIME]&.round(6),
+          heap_use_pages: entry[:HEAP_USE_PAGES],
+          heap_live_objects: entry[:HEAP_LIVE_OBJECTS],
+          heap_free_objects: entry[:HEAP_FREE_OBJECTS],
+          heap_total_objects: entry[:HEAP_TOTAL_OBJECTS],
+          gc_mark_time_ms: (entry[:GC_MARK_TIME].to_f * 1000).round(3),
+          gc_sweep_time_ms: (entry[:GC_SWEEP_TIME].to_f * 1000).round(3)
+        }
+      end
+    }
+  rescue => e
+    { error: e.message }
+  end
+
   register_tool('force_gc',
                 'Trigger a full garbage collection (GC.start with full_mark) and show before/after comparison') do
     before_stats = GC.stat

data/lib/debug_agent/inspectors/health.rb

@@ -0,0 +1,110 @@
+module DebugAgent
+  # Registry of health check blocks. Each block returns a hash with at least
+  # a :status key ('UP', 'DOWN', or 'DEGRADED').
+  #
+  #   DebugAgent.register_health_check(:database) { { status: 'UP' } }
+  @health_checks = {}
+
+  class << self
+    attr_reader :health_checks
+
+    def register_health_check(name, &block)
+      @health_checks[name.to_s] = block
+    end
+  end
+
+  register_tool('get_health_status',
+                'Run all registered health checks and report status per component: UP, DOWN, or DEGRADED') do
+    if health_checks.empty?
+      next {
+        message: 'No health checks registered. Call DebugAgent.register_health_check(:name) { ... }.',
+        overall_status: 'UNKNOWN'
+      }
+    end
+
+    results = {}
+    up = 0
+    down = 0
+    degraded = 0
+
+    health_checks.each do |check_name, block|
+      begin
+        result = block.call
+        status = result.is_a?(Hash) ? (result[:status] || result['status'] || 'UP').to_s.upcase : 'UP'
+        results[check_name] = result.merge(status: status, latency_ms: nil)
+
+        case status
+        when 'UP' then up += 1
+        when 'DOWN' then down += 1
+        when 'DEGRADED' then degraded += 1
+        end
+      rescue => e
+        results[check_name] = { status: 'DOWN', error: e.message }
+        down += 1
+      end
+    end
+
+    overall = if down > 0
+      'DOWN'
+    elsif degraded > 0
+      'DEGRADED'
+    else
+      'UP'
+    end
+
+    {
+      overall_status: overall,
+      up: up,
+      down: down,
+      degraded: degraded,
+      total: health_checks.size,
+      components: results
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_health_detail',
+                'Deep dive into a specific health check component for detailed diagnostics',
+                component_name: { type: 'string', description: 'Name of the health check component to inspect', required: true }) do |component_name:|
+    if health_checks.empty?
+      next { error: 'No health checks registered.' }
+    end
+
+    key = component_name.to_s
+    block = health_checks[key]
+    next { error: "No health check registered for '#{component_name}'. Available: #{health_checks.keys.join(', ')}" } unless block
+
+    # Run the check multiple times to measure latency
+    samples = []
+    3.times do
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        result = block.call
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0).round(2)
+        status = result.is_a?(Hash) ? (result[:status] || result['status'] || 'UP').to_s.upcase : 'UP'
+        samples << { status: status, latency_ms: elapsed, detail: result }
+      rescue => e
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0).round(2)
+        samples << { status: 'DOWN', latency_ms: elapsed, error: e.message }
+        break
+      end
+    end
+
+    latencies = samples.map { |s| s[:latency_ms] }
+
+    {
+      component: key,
+      registered_checks: health_checks.keys,
+      latest: samples.last,
+      samples: samples.size,
+      latency_ms: {
+        min: latencies.min,
+        avg: (latencies.sum / latencies.size.to_f).round(2),
+        max: latencies.max
+      }
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/http_client.rb

@@ -0,0 +1,145 @@
+require 'time'
+require 'thread'
+
+module DebugAgent
+  # Track outbound Net::HTTP calls (latency, errors, hosts) and live
+  # connections by wrapping Net::HTTP#request, #start and #finish.
+  @outbound_stats = { total: 0, latencies: [], errors: 0, hosts: {} }
+  @outbound_lock = Mutex.new
+  @http_connections = {}
+
+  class << self
+    attr_reader :outbound_stats
+
+    def record_outbound(http, req, latency_ms, error)
+      @outbound_lock.synchronize do
+        s = @outbound_stats
+        s[:total] += 1
+        s[:latencies] << latency_ms
+        s[:latencies].shift if s[:latencies].size > 1000
+
+        host_key = "#{http.address}:#{http.port}"
+        h = (s[:hosts][host_key] ||= { count: 0, latencies: [], errors: 0 })
+        h[:count] += 1
+        h[:latencies] << latency_ms
+        h[:latencies].shift if h[:latencies].size > 200
+        if error
+          s[:errors] += 1
+          h[:errors] += 1
+        end
+      end
+    end
+
+    def track_http_connect(http)
+      @outbound_lock.synchronize do
+        @http_connections[http.object_id] = {
+          host: http.address,
+          port: http.port,
+          use_ssl: http.use_ssl?,
+          started_at: Time.now.iso8601,
+          active: true
+        }
+      end
+    end
+
+    def track_http_disconnect(http)
+      @outbound_lock.synchronize do
+        conn = @http_connections[http.object_id]
+        conn[:active] = false if conn
+      end
+    end
+
+    # Wrap Net::HTTP once to capture outbound request metrics.
+    def install_outbound_tracker
+      return false unless defined?(::Net::HTTP)
+      return true if ::Net::HTTP.include?(OutboundHttpTracker)
+
+      ::Net::HTTP.prepend(OutboundHttpTracker)
+      true
+    end
+  end
+
+  # Prepended module that instruments Net::HTTP request lifecycle.
+  module OutboundHttpTracker
+    def start
+      DebugAgent.track_http_connect(self) rescue nil
+      super
+    end
+
+    def finish
+      DebugAgent.track_http_disconnect(self) rescue nil
+      super
+    end
+
+    def request(req, *args, &block)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        result = super
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0)
+        DebugAgent.record_outbound(self, req, elapsed, nil) rescue nil
+        result
+      rescue => e
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0)
+        DebugAgent.record_outbound(self, req, elapsed, e) rescue nil
+        raise
+      end
+    end
+  end
+
+  # Auto-install the tracker at load time when Net::HTTP is available.
+  install_outbound_tracker
+
+  register_tool('get_http_connections',
+                'List Net::HTTP connections and their state: host, port, use_ssl, ' \
+                'start_time, active connections') do
+    conns = @outbound_lock.synchronize { @http_connections.values }
+    active = conns.select { |c| c[:active] }
+    {
+      active_count: active.size,
+      total_tracked: conns.size,
+      tracker_active: defined?(::Net::HTTP) && ::Net::HTTP.include?(OutboundHttpTracker),
+      connections: conns.last(200)
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_outbound_summary',
+                'Summary of outbound HTTP calls tracked by the agent: total, avg latency, ' \
+                'error rate, top hosts') do
+    snapshot = @outbound_lock.synchronize do
+      {
+        total: @outbound_stats[:total],
+        latencies: @outbound_stats[:latencies].dup,
+        errors: @outbound_stats[:errors],
+        hosts: @outbound_stats[:hosts].transform_values(&:dup)
+      }
+    end
+
+    lats = snapshot[:latencies]
+    avg = lats.empty? ? 0.0 : (lats.sum / lats.size)
+    total = snapshot[:total]
+
+    top_hosts = snapshot[:hosts].map do |host, info|
+      hl = info[:latencies]
+      {
+        host: host,
+        count: info[:count],
+        avg_latency_ms: hl.empty? ? 0 : (hl.sum / hl.size).round(2),
+        errors: info[:errors]
+      }
+    end.sort_by { |h| -h[:count] }.first(10)
+
+    {
+      total_requests: total,
+      avg_latency_ms: avg.round(2),
+      error_count: snapshot[:errors],
+      error_rate: total.zero? ? '0.0%' : format('%.1f%%', snapshot[:errors].to_f / total * 100),
+      tracked_hosts: snapshot[:hosts].size,
+      tracker_active: defined?(::Net::HTTP) && ::Net::HTTP.include?(OutboundHttpTracker),
+      top_hosts: top_hosts
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/logging.rb

@@ -0,0 +1,163 @@
+require 'time'
+require 'thread'
+require 'logger'
+
+module DebugAgent
+  # Ring buffer of recent log entries and a registry of named loggers.
+  #
+  #   DebugAgent.register_logger(:app, Rails.logger)
+  MAX_LOGS = 100
+
+  @log_buffer = []
+  @log_buffer_lock = Mutex.new
+  @loggers = {}
+
+  class << self
+    attr_reader :loggers
+
+    def register_logger(name, logger)
+      @loggers[name.to_s] = logger
+    end
+
+    # Invoked by the wrapped Logger#add to push an entry into the ring buffer.
+    def capture_log(severity, args)
+      args = args.is_a?(Array) ? args : [args]
+      # Logger passes (message, progname); pick the meaningful value.
+      msg = args.compact.first
+      entry = {
+        timestamp: Time.now.iso8601,
+        severity: severity_label(severity),
+        message: msg.respond_to?(:to_str) ? msg.to_s : msg.inspect
+      }
+      @log_buffer_lock.synchronize do
+        @log_buffer << entry
+        @log_buffer.shift if @log_buffer.size > MAX_LOGS
+      end
+    end
+
+    # Wrap the standard Logger#add / << so all log output flows into the ring
+    # buffer. Only wraps once — guarded by checking for the aliased method.
+    def install_log_capture
+      return false unless defined?(::Logger)
+      return true if ::Logger.method_defined?(:_original_add)
+
+      ::Logger.class_eval do
+        alias_method :_original_add, :add
+        alias_method :_original_lshift, :<<
+
+        def add(severity, *args, &block)
+          if block
+            msg = args[0]
+            msg = block.call if msg.nil?
+            DebugAgent.capture_log(severity, [msg]) rescue nil
+            _original_add(severity, msg, *args[1..-1])
+          else
+            DebugAgent.capture_log(severity, args) rescue nil
+            _original_add(severity, *args)
+          end
+        end
+
+        def <<(msg)
+          DebugAgent.capture_log(nil, [msg]) rescue nil
+          _original_lshift(msg)
+        end
+      end
+      true
+    end
+
+    # Map a Logger severity integer to a human-readable label.
+    def severity_label(severity)
+      labels = %w[DEBUG INFO WARN ERROR FATAL ANY]
+      idx = severity.is_a?(Integer) ? severity : (defined?(::Logger) ? ::Logger::UNKNOWN : 5)
+      labels[idx] || 'UNKNOWN'
+    end
+  end
+
+  # Attempt to wrap Logger at load time (no-op if Logger isn't loaded yet).
+  install_log_capture
+
+  LEVEL_MAP = {
+    'debug' => defined?(::Logger) ? ::Logger::DEBUG : 0,
+    'info'  => defined?(::Logger) ? ::Logger::INFO  : 1,
+    'warn'  => defined?(::Logger) ? ::Logger::WARN  : 2,
+    'error' => defined?(::Logger) ? ::Logger::ERROR : 3,
+    'fatal' => defined?(::Logger) ? ::Logger::FATAL : 4
+  }.freeze
+
+  register_tool('get_log_buffer',
+                'Return recent log entries captured from the built-in ring buffer ' \
+                '(Logger#add and << are auto-wrapped)') do |limit: 50|
+    limit = limit.to_i
+    limit = 50 if limit <= 0
+    entries = @log_buffer_lock.synchronize { @log_buffer.dup }
+    {
+      total_captured: entries.size,
+      capacity: MAX_LOGS,
+      capture_active: defined?(::Logger) && ::Logger.method_defined?(:_original_add),
+      entries: entries.last(limit).reverse
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_logger_info',
+                'List registered loggers with configuration: level, device, formatter, progname') do
+    if loggers.empty?
+      next {
+        message: 'No loggers registered. Call DebugAgent.register_logger(:name, logger).',
+        capture_active: defined?(::Logger) && ::Logger.method_defined?(:_original_add)
+      }
+    end
+
+    list = loggers.map do |name, logger|
+      info = { name: name, class: logger.class.name }
+      info[:level] = severity_label(logger.level) if logger.respond_to?(:level)
+      info[:progname] = logger.progname if logger.respond_to?(:progname)
+
+      if defined?(::Logger) && logger.is_a?(::Logger)
+        logdev = logger.instance_variable_get(:@logdev)
+        dev = logdev&.instance_variable_get(:@dev)
+        info[:device] =
+          case dev
+          when IO then dev.inspect
+          when String then dev
+          when nil then nil
+          else dev.inspect
+          end
+        formatter = logger.instance_variable_get(:@formatter)
+        info[:formatter] = formatter ? formatter.class.name : 'default'
+      end
+      info
+    rescue => e
+      { name: name, error: e.message }
+    end
+
+    { loggers: list }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('set_log_level',
+                "Dynamically change a registered logger's level",
+                logger_name: { type: 'string', description: 'Registered logger name' },
+                level: { type: 'string', description: 'One of: debug, info, warn, error, fatal' }) do |logger_name:, level:|
+    logger = loggers[logger_name.to_s]
+    next({ error: "No logger registered under '#{logger_name}'" }) unless logger
+    next({ error: 'Logger does not respond to level=' }) unless logger.respond_to?(:level=)
+
+    target = LEVEL_MAP[level.to_s.downcase]
+    next({ error: "Invalid level '#{level}'. Use debug/info/warn/error/fatal." }) unless target
+
+    previous = severity_label(logger.level)
+    logger.level = target
+
+    {
+      logger: logger_name,
+      previous_level: previous,
+      new_level: level.to_s.downcase,
+      success: true
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/metrics.rb

@@ -0,0 +1,71 @@
+module DebugAgent
+  # Inspector for Prometheus metrics (prometheus-client gem).
+  # Uses the default registry: Prometheus::Client.registry.
+
+  class << self
+    # Resolve the Prometheus registry to inspect.
+    def prometheus_registry
+      return nil unless defined?(::Prometheus) && defined?(::Prometheus::Client)
+      ::Prometheus::Client.respond_to?(:registry) ? ::Prometheus::Client.registry : nil
+    end
+
+    # Safely read a metric's value(s). Different metric types return
+    # different shapes from #get.
+    def prometheus_metric_value(metric)
+      begin
+        value = metric.get({})
+        # Counter/Gauge return a Hash of {labels => value}; unwrap the unlabeled value.
+        if value.is_a?(Hash) && value.size == 1 && value.key?({})
+          value[{}]
+        else
+          value
+        end
+      rescue => e
+        { error: e.message }
+      end
+    end
+  end
+
+  register_tool('get_registered_metrics',
+                'List registered Prometheus metrics from the prometheus-client gem: ' \
+                'name, type, docstring, value') do
+    registry = prometheus_registry
+    next { error: 'Prometheus client is not loaded (prometheus-client gem not installed)' } unless registry
+    next { error: 'No Prometheus registry available' } unless registry.respond_to?(:metrics)
+
+    metrics = registry.metrics.map do |metric|
+      {
+        name: metric.name,
+        type: metric.respond_to?(:type) ? metric.type.to_s : 'unknown',
+        docstring: metric.respond_to?(:docstring) ? metric.docstring : nil,
+        value: prometheus_metric_value(metric)
+      }
+    rescue => e
+      { name: metric&.respond_to?(:name) ? metric.name : 'unknown', error: e.message }
+    end
+
+    { total: metrics.size, metrics: metrics }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_metric_value',
+                'Get a specific Prometheus metric value by name',
+                name: { type: 'string', description: 'Registered metric name' }) do |name:|
+    registry = prometheus_registry
+    next { error: 'Prometheus client is not loaded (prometheus-client gem not installed)' } unless registry
+    next { error: 'No Prometheus registry available' } unless registry.respond_to?(:metrics)
+
+    metric = registry.metrics.find { |m| m.respond_to?(:name) && m.name.to_s == name.to_s }
+    next { error: "Metric '#{name}' not found in registry" } unless metric
+
+    {
+      name: metric.name,
+      type: metric.respond_to?(:type) ? metric.type.to_s : 'unknown',
+      docstring: metric.respond_to?(:docstring) ? metric.docstring : nil,
+      value: prometheus_metric_value(metric)
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/scheduler.rb

@@ -0,0 +1,154 @@
+module DebugAgent
+  # Registry of scheduled jobs (Sidekiq::Cron, rufus-scheduler, whenever, or
+  # custom Thread-based timers). Applications register jobs so the inspector
+  # can list them and report execution history.
+  #
+  #   DebugAgent.register_scheduled_job(:cleanup, 'every 30s', last_run: Time.now)
+  @scheduled_jobs = {}
+  @job_history = {}
+  @scheduler_lock = Mutex.new
+
+  class << self
+    attr_reader :scheduled_jobs, :job_history
+
+    def register_scheduled_job(name, schedule, **opts)
+      @scheduled_jobs[name.to_s] = {
+        schedule: schedule,
+        name: name.to_s,
+        class: opts[:class] || name.to_s,
+        queue: opts[:queue],
+        enabled: opts.key?(:enabled) ? opts[:enabled] : true,
+        last_run: opts[:last_run],
+        next_run: opts[:next_run],
+        registered_at: Time.now
+      }
+    end
+
+    # Record a job execution for history tracking.
+    def record_job_execution(name, duration_ms, success: true, error: nil)
+      @scheduler_lock.synchronize do
+        history = (@job_history[name.to_s] ||= [])
+        history << {
+          timestamp: Time.now.iso8601,
+          duration_ms: duration_ms.round(2),
+          success: success,
+          error: error
+        }
+        history.shift if history.size > 100
+
+        # Update last_run on the job itself
+        if @scheduled_jobs[name.to_s]
+          @scheduled_jobs[name.to_s][:last_run] = Time.now
+        end
+      end
+    end
+  end
+
+  register_tool('get_scheduled_jobs',
+                'List scheduled jobs from Sidekiq::Cron, rufus-scheduler, whenever, ' \
+                'or custom Thread-based timers. Shows schedule, last run, and status') do
+    jobs = []
+
+    # Registered jobs (Thread-based, custom, etc.)
+    scheduled_jobs.each do |name, job|
+      jobs << {
+        name: name,
+        schedule: job[:schedule],
+        class: job[:class],
+        queue: job[:queue],
+        enabled: job[:enabled],
+        source: job[:source] || 'registered',
+        last_run: job[:last_run],
+        next_run: job[:next_run]
+      }
+    end
+
+    # Sidekiq::Cron jobs
+    if defined?(::Sidekiq::Cron::Job)
+      begin
+        ::Sidekiq::Cron::Job.all.each do |cron_job|
+          jobs << {
+            name: cron_job.name,
+            schedule: cron_job.cron,
+            class: cron_job.klass,
+            queue: cron_job.queue_name,
+            enabled: cron_job.status == 'enabled',
+            source: 'sidekiq-cron',
+            last_run: cron_job.last_enqueue_time
+          }
+        end
+      rescue => e
+        jobs << { source: 'sidekiq-cron', error: e.message }
+      end
+    end
+
+    # rufus-scheduler
+    if defined?(::Rufus::Scheduler)
+      begin
+        ObjectSpace.each_object(::Rufus::Scheduler) do |scheduler|
+          scheduler.jobs.each do |job|
+            jobs << {
+              name: job.respond_to?(:tags) ? job.tags.first : nil,
+              schedule: job.respond_to?(:original) ? job.original : job.class.name,
+              class: job.class.name,
+              enabled: !job.respond_to?(:paused?) || !job.paused?,
+              source: 'rufus-scheduler',
+              last_run: job.respond_to?(:last_time) ? job.last_time : nil,
+              next_run: job.respond_to?(:next_time) ? job.next_time : nil
+            }
+          end
+        end
+      rescue => e
+        jobs << { source: 'rufus-scheduler', error: e.message }
+      end
+    end
+
+    if jobs.empty?
+      next {
+        message: 'No scheduled jobs registered. Call DebugAgent.register_scheduled_job(:name, schedule). ' \
+                 'Also auto-detects Sidekiq::Cron and rufus-scheduler if loaded.',
+        total: 0
+      }
+    end
+
+    { total: jobs.size, jobs: jobs }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_job_history',
+                'Get recent execution history for scheduled jobs: run times, duration, success/failure',
+                job_name: { type: 'string', description: 'Job name to filter history (optional, returns all if omitted)', required: false }) do |job_name: nil|
+    if job_history.empty?
+      next { message: 'No job execution history recorded. Jobs must call DebugAgent.record_job_execution to track history.', total: 0 }
+    end
+
+    if job_name
+      key = job_name.to_s
+      history = job_history[key] || []
+      next {
+        job: key,
+        total: history.size,
+        history: history.reverse.first(50)
+      }
+    end
+
+    all = job_history.map do |name, entries|
+      successful = entries.count { |e| e[:success] }
+      failed = entries.count { |e| !e[:success] }
+      durations = entries.map { |e| e[:duration_ms] }
+      {
+        job: name,
+        total_runs: entries.size,
+        successful: successful,
+        failed: failed,
+        avg_duration_ms: durations.empty? ? 0 : (durations.sum / durations.size.to_f).round(2),
+        last_run: entries.last&.dig(:timestamp)
+      }
+    end
+
+    { total_jobs: all.size, total_runs: job_history.values.map(&:size).sum, jobs: all }
+  rescue => e
+    { error: e.message }
+  end
+end