lepus 0.0.1.rc2 → 0.1.0

data/lib/lepus/prometheus/instrumentation.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Lepus
+  module Prometheus
+    # Hooks that run inside each Lepus process and forward metrics to the
+    # prometheus_exporter server via Lepus::Prometheus.emit.
+    module Instrumentation
+      # Tracks per-delivery outcomes and latency. Always emits a metric, even
+      # when the underlying consumer raises, so error rates are observable.
+      module HandlerExtensions
+        def process_delivery(delivery_info, metadata, payload)
+          start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          result = nil
+          error_class = nil
+          begin
+            result = super
+          rescue => e
+            error_class = e.class.name
+            raise
+          ensure
+            Lepus::Prometheus.emit(
+              :delivery,
+              consumer: @consumer_class.name,
+              queue: queue_name_for_metric,
+              result: error_class ? "error" : result.to_s,
+              error: error_class.to_s,
+              duration: ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start
+            )
+          end
+          result
+        end
+
+        private
+
+        def queue_name_for_metric
+          q = queue
+          q.respond_to?(:name) ? q.name : q.to_s
+        rescue
+          ""
+        end
+      end
+
+      # Emits process-level gauges on each heartbeat tick. rss_memory is keyed
+      # on (kind, name) only to avoid leaking a new series per pid; pid and
+      # hostname stay available on the `lepus_process_info` info gauge.
+      module WorkerExtensions
+        def heartbeat
+          super
+        ensure
+          Lepus::Prometheus.emit(
+            :process,
+            kind: kind.to_s,
+            name: name,
+            rss_memory: safe_rss_memory_bytes
+          )
+          Lepus::Prometheus.emit(
+            :process_info,
+            kind: kind.to_s,
+            name: name,
+            pid: pid.to_s,
+            hostname: safe_hostname
+          )
+        end
+
+        private
+
+        def safe_rss_memory_bytes
+          Lepus::Processes::MEMORY_GRABBER.call(pid) * 1024
+        rescue
+          0
+        end
+
+        def safe_hostname
+          Socket.gethostname
+        rescue
+          ""
+        end
+      end
+
+      # Periodic poller that turns RabbitMQ queue stats into gauge events.
+      # Runs in a single thread inside whichever process enabled it.
+      class QueuePoller
+        @thread = nil
+        @mutex = Mutex.new
+
+        class << self
+          def start(interval:, api:)
+            @mutex.synchronize do
+              stop_locked
+              @thread = Thread.new { run_loop(interval, api) }
+            end
+          end
+
+          def stop
+            @mutex.synchronize { stop_locked }
+          end
+
+          def running?
+            @mutex.synchronize { !@thread.nil? && @thread.alive? }
+          end
+
+          private
+
+          def stop_locked
+            @thread&.kill
+            @thread = nil
+          end
+
+          def run_loop(interval, api)
+            loop do
+              poll_once(api)
+              sleep interval
+            end
+          end
+
+          def poll_once(api)
+            api.queues.each do |q|
+              Lepus::Prometheus.emit(
+                :queue,
+                name: q[:name],
+                messages: q[:messages].to_i,
+                messages_ready: q[:messages_ready].to_i,
+                messages_unacknowledged: q[:messages_unacknowledged].to_i,
+                consumers: q[:consumers].to_i,
+                memory: q[:memory].to_i
+              )
+            end
+            Lepus::Prometheus.emit(:queue_poll, timestamp: Time.now.to_f)
+          rescue => e
+            Lepus::Prometheus.emit(:queue_poll_error, error: e.class.name)
+            Lepus.logger.warn("[Lepus::Prometheus] queue poll failed: #{e.message}")
+          end
+        end
+      end
+
+      class << self
+        def install!
+          return if @installed
+
+          Lepus::Consumers::Handler.prepend(HandlerExtensions)
+          Lepus::Consumers::Worker.prepend(WorkerExtensions)
+          subscribe_publish_events
+          @installed = true
+        end
+
+        private
+
+        def subscribe_publish_events
+          return unless defined?(ActiveSupport::Notifications)
+
+          ActiveSupport::Notifications.subscribe(/\Apublish\.lepus\z/) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            Lepus::Prometheus.emit(
+              :publish,
+              exchange: event.payload[:exchange].to_s,
+              routing_key: event.payload[:routing_key].to_s,
+              duration: event.duration / 1000.0
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+Lepus::Prometheus::Instrumentation.install!

data/lib/lepus/prometheus.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "prometheus_exporter"
+require "prometheus_exporter/client"
+
+require_relative "prometheus/instrumentation"
+
+module Lepus
+  # Optional integration with the prometheus_exporter gem.
+  # Require "lepus/prometheus" in your Lepus process to start shipping
+  # metrics to a running prometheus_exporter server via the default client.
+  #
+  # On the prometheus_exporter server side, load the companion collector:
+  #   prometheus_exporter -a lepus/prometheus/collector
+  module Prometheus
+    DEFAULT_QUEUE_POLL_INTERVAL = 30
+
+    class << self
+      attr_writer :client
+
+      def client
+        @client ||= ::PrometheusExporter::Client.default
+      end
+
+      # Emit an opaque metric payload to the exporter server.
+      # Silently swallows transport errors so instrumentation cannot
+      # break the caller; non-transport bugs surface as debug logs.
+      def emit(metric, **data)
+        client.send_json(type: "lepus", metric: metric.to_s, **data)
+      rescue => e
+        Lepus.logger.debug { "[Lepus::Prometheus] emit(#{metric}) failed: #{e.class}: #{e.message}" }
+        nil
+      end
+
+      # Start polling the RabbitMQ management API for queue-level gauges.
+      # Safe to call once per process. Requires "lepus/web/management_api".
+      def watch_queues(interval: DEFAULT_QUEUE_POLL_INTERVAL, api: nil)
+        require "lepus/web/management_api"
+        api ||= Lepus::Web::ManagementAPI.new
+        Instrumentation::QueuePoller.start(interval: interval, api: api)
+      end
+
+      def stop_watching_queues
+        Instrumentation::QueuePoller.stop
+      end
+    end
+  end
+end

data/lib/lepus/publisher.rb

@@ -42,7 +42,9 @@ module Lepus
 
       payload, opts = prepare_message(message, **options)
       exchange = channel.exchange(exchange_name, exchange_options)
-      exchange.publish(payload, opts)
+      Lepus.instrument(:publish, exchange: exchange_name, routing_key: opts[:routing_key]) do
+        exchange.publish(payload, opts)
+      end
     end
 
     private

data/lib/lepus/supervisor.rb

@@ -32,6 +32,8 @@ module Lepus
       @configured_processes = {}
 
       super
+
+      @name ||= hostname
     end
 
     def start
@@ -81,8 +83,6 @@ module Lepus
     end
 
     def boot
-      ProcessRegistry.start
-
       Lepus.instrument(:start_process, process: self) do
         if require_file
           Kernel.require(require_file)
@@ -96,6 +96,13 @@ module Lepus
           end
         end
 
+        # Start the registry *after* the host app is loaded. Mounting
+        # `Lepus::Web` in `routes.rb` (or any late `require "lepus/web"`) flips
+        # the default backend to :rabbitmq; starting the registry earlier
+        # would lock in the FileBackend and the later flip would point the
+        # registry at a backend that was never started.
+        ProcessRegistry.start
+
         setup_consumers
         check_bunny_connection
 

data/lib/lepus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lepus
-  VERSION = "0.0.1.rc2"
+  VERSION = "0.1.0"
 end

data/lib/lepus/web/aggregator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "concurrent"
+
+module Lepus
+  module Web
+    # Aggregates process heartbeats from RabbitMQ into in-memory state.
+    # Subscribes to the lepus.heartbeat fanout exchange and maintains
+    # a thread-safe cache of all processes across connected Lepus apps.
+    class Aggregator
+      HEARTBEAT_EXCHANGE = ProcessRegistry::RabbitmqBackend::HEARTBEAT_EXCHANGE
+
+      attr_reader :stale_threshold
+
+      def initialize(stale_threshold: nil)
+        @stale_threshold = stale_threshold || Lepus.config.process_alive_threshold
+        @processes = Concurrent::Map.new
+        @connection = nil
+        @channel = nil
+        @consumer = nil
+        @running = Concurrent::AtomicBoolean.new(false)
+        @pruning_task = nil
+        @mutex = Mutex.new
+      end
+
+      def start
+        return if @running.true?
+
+        @mutex.synchronize do
+          return if @running.true?
+
+          @running.make_true
+          setup_subscription
+          start_pruning_task
+        end
+      rescue => e
+        Lepus.logger.error("[Web::Aggregator] Failed to start: #{e.message}")
+        @running.make_false
+      end
+
+      def stop
+        @mutex.synchronize do
+          @running.make_false
+          @pruning_task&.shutdown
+          @consumer&.cancel
+          @channel&.close if @channel&.open?
+          @connection&.close if @connection&.open?
+        end
+      rescue => e
+        Lepus.logger.warn("[Web::Aggregator] Error during shutdown: #{e.message}")
+      ensure
+        @pruning_task = nil
+        @consumer = nil
+        @channel = nil
+        @connection = nil
+      end
+
+      def running?
+        @running.true?
+      end
+
+      def all_processes
+        prune_stale_entries
+        @processes.values.map { |data| data[:process] }
+      end
+
+      def find(id)
+        @processes[id]&.dig(:process)
+      end
+
+      def count
+        @processes.size
+      end
+
+      def clear
+        @processes.clear
+      end
+
+      private
+
+      def setup_subscription
+        @connection = Lepus.config.create_connection(suffix: "(web-aggregator)")
+        @channel = @connection.create_channel
+
+        exchange = @channel.fanout(
+          HEARTBEAT_EXCHANGE,
+          durable: false,
+          auto_delete: false
+        )
+
+        queue = @channel.queue("", exclusive: true, auto_delete: true)
+        queue.bind(exchange)
+
+        @consumer = queue.subscribe do |_delivery_info, _metadata, payload|
+          handle_message(payload)
+        end
+      end
+
+      def handle_message(payload)
+        data = JSON.parse(payload, symbolize_names: true)
+
+        case data[:type]
+        when "heartbeat"
+          process_heartbeat(data)
+        when "deregister"
+          process_deregistration(data)
+        end
+      rescue => e
+        Lepus.logger.warn("[Web::Aggregator] Failed to handle message: #{e.message}")
+      end
+
+      def process_heartbeat(data)
+        process_data = data[:process]
+        return unless process_data && process_data[:id]
+
+        metrics = data[:metrics] || {}
+
+        flat_process = process_data.merge(
+          rss_memory: metrics[:rss_memory] || 0,
+          connections: metrics[:connections] || 0,
+          consumers: metrics[:consumers] || []
+        )
+
+        @processes[process_data[:id]] = {
+          process: flat_process,
+          received_at: Time.now
+        }
+      end
+
+      def process_deregistration(data)
+        process_id = data[:process_id]
+        @processes.delete(process_id) if process_id
+      end
+
+      def start_pruning_task
+        @pruning_task = Concurrent::TimerTask.new(
+          execution_interval: [@stale_threshold / 2, 30].min
+        ) do
+          prune_stale_entries
+        end
+
+        @pruning_task.execute
+      end
+
+      def prune_stale_entries
+        threshold = Time.now - @stale_threshold
+        @processes.each do |id, data|
+          @processes.delete(id) if data[:received_at] < threshold
+        end
+      end
+    end
+  end
+end

data/lib/lepus/web/api.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Web
+    class API
+      def initialize(aggregator: nil, management_api: nil)
+        @aggregator = aggregator
+        @management_api = management_api
+      end
+
+      def call(env)
+        req = Rack::Request.new(env)
+        case req.path_info
+        when "/health"
+          Web::RespondWith.json(template: :health)
+        when "/processes"
+          processes_data
+        when "/queues"
+          queues_data
+        when "/connections"
+          connections_data
+        when "/exchanges"
+          exchanges_data
+        else
+          Web::RespondWith.json(template: :not_found)
+        end
+      end
+
+      private
+
+      def aggregator
+        @aggregator || Web.aggregator
+      end
+
+      def management_api
+        @management_api || Web.management_api
+      end
+
+      def processes_data
+        if aggregator&.running?
+          payload = aggregator.all_processes
+          Web::RespondWith.json(template: :ok, body: payload)
+        else
+          Web::RespondWith.json(template: :ok, body: [])
+        end
+      end
+
+      def queues_data
+        if management_api
+          raw_queues = management_api.queues
+          payload = annotate_queues_with_apps(raw_queues)
+          Web::RespondWith.json(template: :ok, body: payload)
+        else
+          Web::RespondWith.json(template: :ok, body: [])
+        end
+      rescue => e
+        Lepus.logger.warn("[Web::API] Failed to fetch queues: #{e.message}")
+        Web::RespondWith.json(template: :ok, body: [])
+      end
+
+      def connections_data
+        if management_api
+          payload = management_api.connections
+          Web::RespondWith.json(template: :ok, body: payload)
+        else
+          Web::RespondWith.json(template: :ok, body: [])
+        end
+      rescue => e
+        Lepus.logger.warn("[Web::API] Failed to fetch connections: #{e.message}")
+        Web::RespondWith.json(template: :ok, body: [])
+      end
+
+      def exchanges_data
+        if management_api
+          raw_exchanges = management_api.exchanges
+          payload = filter_exchanges(raw_exchanges)
+          Web::RespondWith.json(template: :ok, body: payload)
+        else
+          Web::RespondWith.json(template: :ok, body: [])
+        end
+      rescue => e
+        Lepus.logger.warn("[Web::API] Failed to fetch exchanges: #{e.message}")
+        Web::RespondWith.json(template: :ok, body: [])
+      end
+
+      def annotate_queues_with_apps(queues)
+        return queues unless aggregator&.running?
+
+        queue_app_map = build_queue_app_map
+        return queues if queue_app_map.empty?
+
+        queues.map do |queue|
+          app = queue_app_map[queue[:name]]
+          app ? queue.merge(application: app) : queue
+        end
+      end
+
+      def filter_exchanges(exchanges)
+        return exchanges if Lepus.config.web_show_all_exchanges
+        return exchanges unless aggregator&.running?
+
+        known_exchanges = build_known_exchange_names
+        return exchanges if known_exchanges.empty?
+
+        exchanges.select { |e| known_exchanges.include?(e[:name]) }
+      end
+
+      def build_queue_app_map
+        map = {}
+        aggregator.all_processes.each do |process|
+          app_name = process[:application]
+          next unless app_name
+
+          (process[:consumers] || []).each do |consumer|
+            map[consumer[:queue]] = app_name if consumer[:queue]
+          end
+        end
+        map
+      end
+
+      def build_known_exchange_names
+        names = Set.new
+        aggregator.all_processes.each do |process|
+          (process[:consumers] || []).each do |consumer|
+            names << consumer[:exchange] if consumer[:exchange]
+          end
+        end
+        names
+      end
+    end
+  end
+end

data/lib/lepus/web/app.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Web
+    class App
+      def self.build
+        root = Web.assets_path
+
+        Rack::Builder.new do
+          use Rack::Static,
+            urls: ["/assets", "/sw.js"],
+            root: root.to_s
+
+          map "/api" do
+            run Lepus::Web::API.new
+          end
+
+          run lambda { |env|
+            req = Rack::Request.new(env)
+            path = req.path_info
+
+            if path == "/" || path == "/index.html"
+              [200, {"content-type" => "text/html"}, [Web.render_index(env)]]
+            else
+              file_path = root.join(path.sub(%r{^/}, ""))
+              if File.file?(file_path)
+                [200, {"content-type" => Web.mime_for(file_path)}, [File.binread(file_path)]]
+              else
+                [200, {"content-type" => "text/html"}, [Web.render_index(env)]]
+              end
+            end
+          }
+        end
+      end
+    end
+  end
+end