debug-agent 0.2.6 → 0.4.0

data/lib/debug_agent/inspectors/faraday.rb

@@ -0,0 +1,79 @@
+module DebugAgent
+  # Registry of named Faraday connections so the inspector can introspect them.
+  #
+  #   DebugAgent.register_faraday(:api, Faraday.new('https://api.example.com'))
+  @faraday_connections = {}
+
+  class << self
+    attr_reader :faraday_connections
+
+    def register_faraday(name, conn)
+      @faraday_connections[name.to_s] = conn
+    end
+
+    def faraday_conn_info(name, conn)
+      info = { name: name, class: conn.class.name }
+
+      if conn.respond_to?(:url_prefix)
+        info[:url] = conn.url_prefix.to_s
+        info[:host] = conn.url_prefix.host
+        info[:port] = conn.url_prefix.port
+        info[:scheme] = conn.url_prefix.scheme
+      end
+
+      builder = conn.respond_to?(:builder) ? conn.builder : nil
+      if builder
+        handlers =
+          if builder.respond_to?(:handlers)
+            builder.handlers.map { |h| faraday_handler_name(h) }
+          else
+            []
+          end
+        info[:middleware] = handlers
+
+        adapter =
+          if builder.respond_to?(:adapter)
+            faraday_handler_name(builder.adapter)
+          end
+        info[:adapter] = adapter if adapter
+      end
+
+      info[:headers] = conn.headers.to_h if conn.respond_to?(:headers) && conn.headers.respond_to?(:to_h)
+
+      info
+    rescue => e
+      { name: name, error: e.message }
+    end
+
+    def faraday_handler_name(handler)
+      return handler.name if handler.respond_to?(:name)
+      return handler.class.name if handler.respond_to?(:class)
+      handler.to_s
+    end
+  end
+
+  register_tool('get_faraday_connections',
+                'List registered Faraday connections with URL, adapter, and middleware stack ' \
+                '(requires faraday gem)') do |name: nil|
+    next { error: 'Faraday is not loaded (faraday gem not installed)' } unless defined?(::Faraday)
+
+    conns = faraday_connections
+    if conns.empty?
+      next {
+        message: 'No Faraday connections registered. Call DebugAgent.register_faraday(:name, conn).'
+      }
+    end
+
+    targets = name ? { name.to_s => conns[name.to_s] } : conns
+    targets = targets.reject { |_, c| c.nil? }
+    next { error: "No Faraday connection registered under '#{name}'" } if targets.empty?
+
+    list = targets.map do |conn_name, conn|
+      faraday_conn_info(conn_name, conn)
+    end
+
+    { connections: list }
+  rescue => e
+    { error: e.message }
+  end
+end

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/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/puma.rb

@@ -0,0 +1,73 @@
+module DebugAgent
+  register_tool('get_puma_stats',
+                'Get Puma worker stats: running workers, threads, backlog, requests ' \
+                '(uses Puma.stats if Puma is loaded)') do
+    unless defined?(::Puma)
+      return { error: 'Puma is not loaded (puma gem not installed)' }
+    end
+
+    raw =
+      if ::Puma.respond_to?(:stats_hash)
+        ::Puma.stats_hash
+      elsif ::Puma.respond_to?(:stats)
+        # Puma.stats returns a JSON string in older versions; parse it.
+        s = ::Puma.stats
+        s.is_a?(String) ? JSON.parse(s, symbolize_names: true) : s
+      else
+        return { error: 'Puma is loaded but does not expose Puma.stats' }
+      end
+
+    raw = raw.respond_to?(:transform_keys) ? raw : raw
+
+    # Normalize into a structured summary.
+    workers = []
+
+    # Clustered mode: raw is { workers: N, booted_workers: N, old_workers: N,
+    #                          phase: N, worker_status: [...] }
+    # Single mode: raw is { backed_up: N, running: N, pool_capacity: N,
+    #                         max_threads: N, requests_count: N }
+    if raw.is_a?(Hash) && raw.key?(:worker_status)
+      raw[:worker_status].each_with_index do |w, i|
+        last_stats = w[:last_status] || {}
+        workers << {
+          index: i,
+          pid: w[:pid],
+          index_field: w[:index],
+          booted: w[:booted],
+          last_checkin: w[:last_checkin],
+          running_threads: last_stats[:running],
+          pool_capacity: last_stats[:pool_capacity],
+          max_threads: last_stats[:max_threads],
+          backlog: last_stats[:backed_up],
+          requests: last_stats[:requests_count]
+        }
+      end
+
+      {
+        mode: 'cluster',
+        configured_workers: raw[:workers],
+        booted_workers: raw[:booted_workers],
+        old_workers: raw[:old_workers],
+        phase: raw[:phase],
+        workers: workers,
+        total_running_threads: workers.sum { |w| w[:running_threads].to_i },
+        total_backlog: workers.sum { |w| w[:backlog].to_i },
+        total_requests: workers.sum { |w| w[:requests].to_i }
+      }
+    elsif raw.is_a?(Hash)
+      {
+        mode: 'single',
+        running_threads: raw[:running],
+        pool_capacity: raw[:pool_capacity],
+        max_threads: raw[:max_threads],
+        backlog: raw[:backed_up],
+        requests: raw[:requests_count],
+        raw: raw
+      }
+    else
+      { raw: raw }
+    end
+  rescue => e
+    { error: e.message }
+  end
+end