leopard 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91aa4b92bca51e6d8b73238440961b9f3f43a0cbad93e7faa8a905ed25cf0ae0
-  data.tar.gz: '060265234152419f9ccffae0177c83cf3a6e9d175d453fb4657163a419ce7ed9'
+  metadata.gz: bb81d09b4b0709f3f290009e42e9fa1080e6b33e1fa578473b789875cfa44054
+  data.tar.gz: 0f1d6d756f9a60cb9cd9f6a7072e6c9e2fcd1060faed0121ad6a3d27496a3ea6
 SHA512:
-  metadata.gz: e7f3a1b44ac12f62f1bd0fd06aa9a5e48d0007f022f6664929b569e0016587d24adce6c2e3e5fb7ed769a38509d3e83e79c80e891c7470c61c6848fede6380a2
-  data.tar.gz: 33416a919d4e8f073ea9b89a46ede9aae3979284f2614b868a997fd3e6f21dae98802755203139a55facb58c4aad16a0a5fdc42499cf7cfc04521d5eff8c3126
+  metadata.gz: c584384a406f264f2e3bb20c0a40fd75506e7f407985f7b4fb42166899fce3b233f99df795e6e75a4c973f6369c93cb10a9eb29f4453a4cd88c19680d9839ed2
+  data.tar.gz: 4bdbdfc0debc18a1bbd7ef8e636e4ad2019fa593fd083a47683f48bfb099302552e528eac530f99e464f5347c0475d1c49a874aa4021aaf5dcb2c4a4e321fe68

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.4"
+  ".": "0.2.5"
 }

data/.version.txt

@@ -1 +1 @@
-0.2.4
+0.2.5

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.5](https://github.com/rubyists/leopard/compare/v0.2.4...v0.2.5) (2026-04-16)
+
+
+### Features
+
+* add optional prometheus metrics endpoint with saturation metrics ([#42](https://github.com/rubyists/leopard/issues/42)) ([fcd767a](https://github.com/rubyists/leopard/commit/fcd767ab5438c92bf50800d50027b43b7d0f9f0e))
+
 ## [0.2.4](https://github.com/rubyists/leopard/compare/v0.2.3...v0.2.4) (2026-03-31)
 
 

data/lib/leopard/metrics_server.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'erb'
+
+module Rubyists
+  module Leopard
+    module MetricsServer
+      private
+
+      def start_metrics_server(workers)
+        port = ENV.fetch('LEOPARD_METRICS_PORT', '9394').to_i
+        Thread.new do
+          server = TCPServer.new(port)
+          logger.info "Metrics server listening on :#{port}"
+          loop { Thread.new(server.accept) { |client| handle_metrics_client(client, workers) } }
+        rescue StandardError => e
+          logger.error "Metrics server error: #{e.message}"
+        end
+      end
+
+      def handle_metrics_client(client, workers)
+        request_line = client.gets
+        loop { break if (client.gets || '').chomp.empty? }
+        write_metrics_response(client, request_line, workers)
+      rescue StandardError => e
+        logger.warn "Metrics request error: #{e.message}"
+      ensure
+        close_client(client)
+      end
+
+      def close_client(client)
+        client.close
+      rescue StandardError
+        nil
+      end
+
+      def write_metrics_response(client, request_line, workers)
+        if request_line&.start_with?('GET /metrics')
+          body = prometheus_metrics(workers)
+          client.write "HTTP/1.1 200 OK\r\n" \
+                       "Content-Type: text/plain; version=0.0.4\r\n" \
+                       "Content-Length: #{body.bytesize}\r\n\r\n#{body}"
+        else
+          client.write "HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\n\r\n"
+        end
+      end
+
+      def prometheus_metrics(workers)
+        metrics = collect_prometheus_metrics(workers)
+        render_metrics_template(metrics)
+      end
+
+      def collect_prometheus_metrics(workers)
+        busy    = Hash.new(0)
+        pending = Hash.new(0)
+        workers.each { |w| accumulate_worker_metrics(w, busy, pending) }
+        {
+          busy:,
+          pending:,
+          subjects: (busy.keys | pending.keys).sort,
+          total: workers.size,
+        }
+      end
+
+      def accumulate_worker_metrics(worker, busy, pending)
+        service = worker.instance_variable_get(:@service)
+        return unless service
+
+        service.endpoints.each do |ep|
+          # TODO: use ep.handler once nats-pure.rb adds attr_reader :handler to NATS::Service::Endpoint
+          sub = ep.instance_variable_get(:@handler)
+          next unless sub
+
+          subj = ep.subject.to_s
+          busy[subj]    += sub.concurrency_semaphore.available_permits.zero? ? 1 : 0
+          pending[subj] += sub.pending_queue&.size.to_i
+        end
+      end
+
+      def render_metrics_template(metrics)
+        ERB.new(File.read(metrics_template_path), trim_mode: '-').result_with_hash(metrics)
+      end
+
+      def metrics_template_path
+        File.expand_path('templates/prometheus_metrics.erb', __dir__)
+      end
+    end
+  end
+end

data/lib/leopard/nats_api_server.rb

@@ -6,6 +6,7 @@ require 'dry/configurable'
 require 'concurrent'
 require_relative '../leopard'
 require_relative 'message_wrapper'
+require_relative 'metrics_server'
 
 module Rubyists
   module Leopard
@@ -24,6 +25,8 @@ module Rubyists
       Endpoint = Struct.new(:name, :subject, :queue, :group, :handler)
 
       module ClassMethods
+        include MetricsServer
+
         def endpoints = @endpoints ||= []
         def groups = @groups ||= {}
         def middleware = @middleware ||= []
@@ -78,6 +81,7 @@ module Rubyists
           pool = spawn_instances(nats_url, service_opts, instances, workers, blocking)
           logger.info 'Setting up signal trap...'
           trap_signals(workers, pool)
+          start_metrics_server(workers) if ENV['LEOPARD_METRICS_PORT']
           return pool unless blocking
 
           sleep

data/lib/leopard/templates/prometheus_metrics.erb

@@ -0,0 +1,17 @@
+# HELP leopard_subject_busy_instances Instances currently processing a message on this subject
+# TYPE leopard_subject_busy_instances gauge
+<% subjects.each do |subject| -%>
+leopard_subject_busy_instances{subject="<%= subject %>"} <%= busy[subject] %>
+<% end -%>
+
+# HELP leopard_subject_total_instances Total Leopard instances in this process
+# TYPE leopard_subject_total_instances gauge
+<% subjects.each do |subject| -%>
+leopard_subject_total_instances{subject="<%= subject %>"} <%= total %>
+<% end -%>
+
+# HELP leopard_subject_pending_messages Messages pending processing across all instances
+# TYPE leopard_subject_pending_messages gauge
+<% subjects.each do |subject| -%>
+leopard_subject_pending_messages{subject="<%= subject %>"} <%= pending[subject] %>
+<% end -%>

data/lib/leopard/version.rb

@@ -3,7 +3,7 @@
 module Rubyists
   module Leopard
     # x-release-please-start-version
-    VERSION = '0.2.4'
+    VERSION = '0.2.5'
     # x-release-please-end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: leopard
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - bougyman
 bindir: exe
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -103,8 +103,10 @@ files:
 - lib/leopard.rb
 - lib/leopard/errors.rb
 - lib/leopard/message_wrapper.rb
+- lib/leopard/metrics_server.rb
 - lib/leopard/nats_api_server.rb
 - lib/leopard/settings.rb
+- lib/leopard/templates/prometheus_metrics.erb
 - lib/leopard/version.rb
 homepage: https://github.com/rubyists/leopard
 licenses: