leopard 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b477f10d51aef7a541a2a08d615c4ab03c12393edee90ef4d46265df76727c3a
-  data.tar.gz: 5ad3323e0fd8a1f3f09fc9dd648bc21c05b7b0d21a51bc46cef8fc27c379a745
+  metadata.gz: e28fb312a603ba19a413cdc3c9b62e702ec70daa6870bd833b182dd82a96b147
+  data.tar.gz: 5dcb6ade2032068fd4daaf15b7953ae8ad3e81d352d72a6945e3452fb16b762a
 SHA512:
-  metadata.gz: 44c692417837a8d9e1c6e6ed1fa84e1c7eb096367b7617e729e8068d5e93c7a01d1ac5414a5d01945c37180e2c918c3aba08122af73b9ad2010773656d6a535f
-  data.tar.gz: caff9b0df3beb7a16bd8d8c4830257f24ad1dec98fb57d3b5dba6847892f84cda089a7fe85d1368fb64834996ab69cc1831383b6d0c1d7ca3e7b44cb536a99b2
+  metadata.gz: a85035745ea9c0470764ea48c9127a60ae8459ba88d01158c33f22fab74aba81d5781d1c44bbbc09a2bcb53f0ae8787b2434c2ecf16063a0300ecfb3ce63bf7b
+  data.tar.gz: bcb763a8fc34511e78e9764b648ac75e24cf6370075550a958eeb69fb2cd0a738232c488fc5f06cf7ffe97b004a5d499f70e4a972c8e3aef5c09475d58135535

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.7"
+  ".": "0.2.8"
 }

data/.version.txt

@@ -1 +1 @@
-0.2.7
+0.2.8

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.2.8](https://github.com/rubyists/leopard/compare/v0.2.7...v0.2.8) (2026-05-19)
+
+
+### Features
+
+* improved leopard saturation metrics ([2303ef2](https://github.com/rubyists/leopard/commit/2303ef223b6b8150d728d827592744bbc75fc1a3))
+* improved leopard saturation metrics ([c143056](https://github.com/rubyists/leopard/commit/c143056683f694eba1704acb84139095887515f4))
+
 ## [0.2.7](https://github.com/rubyists/leopard/compare/v0.2.6...v0.2.7) (2026-04-29)
 
 

data/lib/leopard/metrics_server.rb

@@ -80,45 +80,62 @@ module Rubyists
         render_metrics_template(metrics)
       end
 
-      # Aggregates per-subject worker utilization metrics.
+      # Aggregates per-worker, per-subject saturation metrics and per-worker executor metrics.
       #
       # @param workers [Array<Object>] Active Leopard worker instances to observe.
       #
       # @return [Hash{Symbol => Object}] Metric hashes for the Prometheus template.
       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,
-        }
+        subject_metrics = []
+        executors       = []
+
+        workers.each_with_index do |w, i|
+          accumulate_worker_metrics(w, i, subject_metrics)
+          ex = w.instance_variable_get(:@client)&.subscription_executor
+          executors << { worker: i, executor: ex } if ex
+        end
+
+        { subject_metrics:, executors: }
       end
 
-      # Adds one worker's endpoint saturation metrics to the aggregate hashes.
+      # Appends one worker's per-subject slot metrics to the subject_metrics array.
       #
       # @param worker [Object] A Leopard worker instance.
-      # @param busy [Hash{String => Integer}] Subject-to-busy-worker counts.
-      # @param pending [Hash{String => Integer}] Subject-to-pending-message counts.
+      # @param worker_index [Integer] Position of this worker in the workers array.
+      # @param subject_metrics [Array<Hash>] Accumulator for per-worker-per-subject metric rows.
       #
       # @return [void]
-      def accumulate_worker_metrics(worker, busy, pending)
+      def accumulate_worker_metrics(worker, worker_index, subject_metrics)
         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
+        service.endpoints.each do |endpoint|
+          row = endpoint_subject_metrics(endpoint, worker_index)
+          subject_metrics << row if row
         end
       end
 
+      # Builds a per-worker-per-subject metric row from a single endpoint, or nil if not yet active.
+      #
+      # @param endpoint [Object] A NATS service endpoint.
+      # @param worker_index [Integer] Position of the owning worker in the workers array.
+      #
+      # @return [Hash, nil]
+      def endpoint_subject_metrics(endpoint, worker_index)
+        # TODO: use endpoint.handler once nats-pure.rb adds attr_reader :handler to NATS::Service::Endpoint
+        sub = endpoint.instance_variable_get(:@handler)
+        return unless sub
+
+        concurrency = sub.instance_variable_get(:@processing_concurrency).to_i
+        {
+          worker: worker_index,
+          subject: endpoint.subject.to_s,
+          busy_slots: concurrency - sub.concurrency_semaphore.available_permits,
+          capacity_slots: concurrency,
+          pending: sub.pending_queue&.size.to_i,
+        }
+      end
+
       # Renders the metrics ERB template with aggregated metric data.
       #
       # @param metrics [Hash{Symbol => Object}] Aggregated metric data for template rendering.

data/lib/leopard/templates/prometheus_metrics.erb

@@ -1,17 +1,35 @@
-# 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] %>
+# HELP leopard_subject_busy_slots Thread slots actively processing a message for this subject on this worker
+# TYPE leopard_subject_busy_slots gauge
+<% subject_metrics.each do |m| -%>
+leopard_subject_busy_slots{subject="<%= m[:subject] %>",worker="<%= m[:worker] %>"} <%= m[:busy_slots] %>
 <% 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 %>
+# HELP leopard_subject_capacity_slots Total thread slots allocated for this subject on this worker
+# TYPE leopard_subject_capacity_slots gauge
+<% subject_metrics.each do |m| -%>
+leopard_subject_capacity_slots{subject="<%= m[:subject] %>",worker="<%= m[:worker] %>"} <%= m[:capacity_slots] %>
 <% end -%>
 
-# HELP leopard_subject_pending_messages Messages pending processing across all instances
+# HELP leopard_subject_pending_messages Messages waiting to acquire a processing slot for this subject on this worker
 # TYPE leopard_subject_pending_messages gauge
-<% subjects.each do |subject| -%>
-leopard_subject_pending_messages{subject="<%= subject %>"} <%= pending[subject] %>
+<% subject_metrics.each do |m| -%>
+leopard_subject_pending_messages{subject="<%= m[:subject] %>",worker="<%= m[:worker] %>"} <%= m[:pending] %>
+<% end -%>
+
+# HELP leopard_executor_active_threads Approximate number of active threads in the subscription executor (concurrent-ruby active_count is approximate)
+# TYPE leopard_executor_active_threads gauge
+<% executors.each do |e| -%>
+leopard_executor_active_threads{worker="<%= e[:worker] %>"} <%= e[:executor].active_count %>
+<% end -%>
+
+# HELP leopard_executor_max_threads Maximum threads in the subscription executor; queued_tasks goes positive when sum of capacity_slots across subjects exceeds this value
+# TYPE leopard_executor_max_threads gauge
+<% executors.each do |e| -%>
+leopard_executor_max_threads{worker="<%= e[:worker] %>"} <%= e[:executor].max_length %>
+<% end -%>
+
+# HELP leopard_executor_queued_tasks Tasks holding a semaphore permit but waiting for a free executor thread; nonzero only when the executor pool is fully saturated
+# TYPE leopard_executor_queued_tasks gauge
+<% executors.each do |e| -%>
+leopard_executor_queued_tasks{worker="<%= e[:worker] %>"} <%= e[:executor].queue_length %>
 <% end -%>

data/lib/leopard/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leopard
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - bougyman