async-service-supervisor 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acb581fece1b2ca0364e8b7f3fee2893c15d788f022377c23ba810a71276beb7
-  data.tar.gz: 68d38aa49e35ef1c63e6f214ff271daca6650dfa5bffb1d628eb0f429b5d6219
+  metadata.gz: df5a5c251964d3435c184c712d4ccc2aa8c74a255d78f3632669a1a527ce78af
+  data.tar.gz: ea832f3d1e9136ccca58f5c5025fe180de773389a739d9b0ad99aae453df2ee2
 SHA512:
-  metadata.gz: b46f7d61a4ec984478e0fbc062ebb14dc48899a2c004dc23c1446a69f2d095e5614f4eb6fedc0a7d6f264318ea84ce2f12a69b99bff643c18b0b2ef35b13fa8d
-  data.tar.gz: a836860985fc1753ca0b116a9d929562c8b24fd9ba474043c178e2dfa26dd59caf64106ce96a3b508762560c88d5ea39fb74f72d63559f91fab425e79c1869e1
+  metadata.gz: f54af527ecda8c37129a39f6061095cbaf66b47eec102fd21c1aecb9e5791f487c3d48f567f0a0898a7168ba33bc3a60eef18f7fc1beb656640ce53e3b5f02ed
+  data.tar.gz: a9e0b9c6e8a489665d72ed11b0af0eeca18fa7256bfbcdf9d7bef364554fcd219a15c1dbae49d073d8631a92ca023c689f91936444630198b596fcf2eae110dc

data/lib/async/service/supervisor/monitor.rb

@@ -8,11 +8,20 @@ require "async/loop"
 module Async
 	module Service
 		module Supervisor
+			# Base class for supervisor monitors that run periodically within the supervisor process.
+			#
+			# Subclasses should override {#run_once} to implement specific monitoring logic.
 			class Monitor
+				# Initialize a new monitor.
+				#
+				# @parameter interval [Numeric] The interval in seconds between each invocation of {#run_once}.
 				def initialize(interval: 1.0)
 					@interval = interval
 				end
 				
+				# Serialize the monitor state for JSON representation.
+				#
+				# @returns [Hash] An empty hash by default; subclasses should override to include relevant state.
 				def as_json(...)
 					{}
 				end

data/lib/async/service/supervisor/process_monitor.rb

@@ -67,15 +67,20 @@ module Async
 					{ppid: @ppid, metrics: self.metrics}
 				end
 				
-				# Run one iteration of the process monitor.
-				def run_once
-					metrics = self.metrics
-					
+				# Emit the process metrics.
+				#
+				# @parameter metrics [Hash] The process metrics to emit.
+				def emit(metrics)
 					# Log each process individually for better searchability in log platforms:
 					metrics.each do |process_id, general|
 						Console.info(self, "Process metrics captured.", general: general)
 					end
 				end
+				
+				# Run one iteration of the process monitor.
+				def run_once
+					self.emit(self.metrics)
+				end
 			end
 		end
 	end

data/lib/async/service/supervisor/utilization_monitor.rb

@@ -277,10 +277,10 @@ module Async
 					:utilization_monitor
 				end
 				
-				# Serialize utilization data for JSON.
+				# Sample aggregated utilization data.
 				#
 				# @returns [Hash] Hash mapping service names to aggregated utilization metrics.
-				def as_json
+				def sample
 					@guard.synchronize do
 						aggregated = {}
 						
@@ -313,6 +313,13 @@ module Async
 					end
 				end
 				
+				# Serialize utilization data for JSON.
+				#
+				# @returns [Hash] Hash mapping service names to aggregated utilization metrics.
+				def as_json
+					self.sample
+				end
+				
 				# Emit the utilization metrics.
 				#
 				# @parameter status [Hash] The utilization metrics.

data/lib/async/service/supervisor/version.rb

@@ -9,7 +9,7 @@ module Async
 	module Service
 		# @namespace
 		module Supervisor
-			VERSION = "0.15.0"
+			VERSION = "0.17.0"
 		end
 	end
 end

data/lib/metrics/provider/async/service/supervisor/process_monitor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "metrics/provider"
+
+require_relative "../../../../../async/service/supervisor/process_monitor"
+
+class Async::Service::Supervisor::ProcessMonitor
+	Metrics::Provider(self) do
+		PROCESS_METRICS_GENERAL_PROCESSOR_UTILIZATION = Metrics.metric("process.metrics.general.processor_utilization", :gauge, description: "Processor utilization for a supervised process.")
+		PROCESS_METRICS_GENERAL_TOTAL_SIZE = Metrics.metric("process.metrics.general.total_size", :gauge, description: "Total memory size for a supervised process.", unit: "bytes")
+		PROCESS_METRICS_GENERAL_VIRTUAL_SIZE = Metrics.metric("process.metrics.general.virtual_size", :gauge, description: "Virtual memory size for a supervised process.", unit: "bytes")
+		PROCESS_METRICS_GENERAL_RESIDENT_SIZE = Metrics.metric("process.metrics.general.resident_size", :gauge, description: "Resident memory size for a supervised process.", unit: "bytes")
+		
+		def emit(metrics)
+			metrics.each_value do |general|
+				if value = general[:processor_utilization]
+					PROCESS_METRICS_GENERAL_PROCESSOR_UTILIZATION.emit(value)
+				end
+				
+				if value = general[:total_size]
+					PROCESS_METRICS_GENERAL_TOTAL_SIZE.emit(value)
+				end
+				
+				if value = general[:virtual_size]
+					PROCESS_METRICS_GENERAL_VIRTUAL_SIZE.emit(value)
+				end
+				
+				if value = general[:resident_size]
+					PROCESS_METRICS_GENERAL_RESIDENT_SIZE.emit(value)
+				end
+			end
+			
+			super
+		end
+	end
+end

data/lib/metrics/provider/async/service/supervisor/utilization_monitor.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "metrics/provider"
+require "metrics/tags"
+
+require_relative "../../../../../async/service/supervisor/utilization_monitor"
+
+class Async::Service::Supervisor::UtilizationMonitor
+	Metrics::Provider(self) do
+		UTILIZATION = Metrics.metric("async.utilization", :gauge, description: "Active requests per worker.")
+		UTILIZATION_CONNECTIONS_ACTIVE = Metrics.metric("async.utilization.connections.active", :gauge, description: "The number of active connections.")
+		UTILIZATION_CONNECTIONS_TOTAL = Metrics.metric("async.utilization.connections.total", :gauge, description: "The total number of connections.")
+		UTILIZATION_REQUESTS_ACTIVE = Metrics.metric("async.utilization.requests.active", :gauge, description: "The number of active requests.")
+		UTILIZATION_REQUESTS_TOTAL = Metrics.metric("async.utilization.requests.total", :gauge, description: "The total number of requests.")
+		UTILIZATION_WORKERS = Metrics.metric("async.utilization.workers", :gauge, description: "The number of workers contributing utilization metrics.")
+		
+		def emit(metrics)
+			metrics.each do |service_name, fields|
+				tags = Metrics::Tags.normalize(service: service_name)
+				
+				if connections_active = fields[:connections_active]
+					UTILIZATION_CONNECTIONS_ACTIVE.emit(connections_active, tags: tags)
+				end
+				
+				if connections_total = fields[:connections_total]
+					UTILIZATION_CONNECTIONS_TOTAL.emit(connections_total, tags: tags)
+				end
+				
+				if requests_active = fields[:requests_active]
+					UTILIZATION_REQUESTS_ACTIVE.emit(requests_active, tags: tags)
+				end
+				
+				if requests_total = fields[:requests_total]
+					UTILIZATION_REQUESTS_TOTAL.emit(requests_total, tags: tags)
+				end
+				
+				if worker_count = fields[:worker_count]
+					UTILIZATION_WORKERS.emit(worker_count, tags: tags)
+					
+					if worker_count > 0 and requests_active = fields[:requests_active]
+						UTILIZATION.emit(requests_active.to_f / worker_count, tags: tags)
+					end
+				end
+			end
+			
+			super
+		end
+	end
+end

data/lib/metrics/provider/async/service/supervisor.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "supervisor/process_monitor"
+require_relative "supervisor/utilization_monitor"

data/lib/traces/provider/async/service/supervisor/server.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "traces/provider"
+
+require_relative "../../../../../async/service/supervisor/server"
+
+Traces::Provider(Async::Service::Supervisor::Server) do
+	def remove(controller)
+		return super unless controller.id
+		
+		attributes = {
+			"worker.id" => controller.id,
+			"worker.process_id" => controller.process_id,
+			"service.name" => controller.state[:name],
+			"monitor.count" => @monitors.size,
+		}
+		
+		Traces.trace("async.service.supervisor.worker.remove", attributes: attributes) do
+			super
+		end
+	end
+end

data/lib/traces/provider/async/service/supervisor/supervisor_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "traces/provider"
+
+require_relative "../../../../../async/service/supervisor/supervisor_controller"
+
+Traces::Provider(Async::Service::Supervisor::SupervisorController) do
+	def register(worker, process_id:, state: {})
+		attributes = {
+			"worker.process_id" => process_id,
+			"service.name" => state[:name],
+			"monitor.count" => @server.monitors.size,
+		}
+		
+		Traces.trace("async.service.supervisor.worker.register", attributes: attributes) do |span|
+			super.tap do |id|
+				span["worker.id"] = id
+			end
+		end
+	end
+end

data/lib/traces/provider/async/service/supervisor.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "supervisor/server"
+require_relative "supervisor/supervisor_controller"

data/readme.md

@@ -28,6 +28,14 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor/releases/index) for all releases.
 
+### v0.17.0
+
+  - Add opt-in `metrics` and `traces` providers for supervisor process metrics, utilization metrics, and worker lifecycle tracing.
+
+### v0.16.0
+
+  - Add `ProcessMonitor#emit(metrics)` as an override point for subclasses to consume captured process metrics (e.g. emitting StatsD gauges).
+
 ### v0.15.0
 
   - Improve robustness and error handling of default monitors and server loop, ensuring that monitor failures either completely crash the server or retry appropriately, rather than leaving the server in a broken state.
@@ -65,18 +73,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
 
   - Close `Call` queue if asynchronous call fails during dispatch - further messages will fail with `ClosedQueueError`.
 
-### v0.9.0
-
-  - Better handling of write failures in `Connection::Call.dispatch`, ensuring we don't leak calls.
-  - Robust monitor loop handling - restart on failure, and align loop iterations.
-  - Disable memory sampler by default and use text output format.
-      - Introduce support for redirecting dump output to logs.
-
-### v0.8.0
-
-  - Add `Async::Service::Supervisor::ProcessMonitor` for logging CPU and memory metrics periodically.
-  - Fix documentation to use correct `maximum_size_limit:` parameter name for `MemoryMonitor` (was incorrectly documented as `limit:`).
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.17.0
+
+  - Add opt-in `metrics` and `traces` providers for supervisor process metrics, utilization metrics, and worker lifecycle tracing.
+
+## v0.16.0
+
+  - Add `ProcessMonitor#emit(metrics)` as an override point for subclasses to consume captured process metrics (e.g. emitting StatsD gauges).
+
 ## v0.15.0
 
   - Improve robustness and error handling of default monitors and server loop, ensuring that monitor failures either completely crash the server or retry appropriately, rather than leaving the server in a broken state.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -176,6 +176,12 @@ files:
 - lib/async/service/supervisor/version.rb
 - lib/async/service/supervisor/worker.rb
 - lib/async/service/supervisor/worker_controller.rb
+- lib/metrics/provider/async/service/supervisor.rb
+- lib/metrics/provider/async/service/supervisor/process_monitor.rb
+- lib/metrics/provider/async/service/supervisor/utilization_monitor.rb
+- lib/traces/provider/async/service/supervisor.rb
+- lib/traces/provider/async/service/supervisor/server.rb
+- lib/traces/provider/async/service/supervisor/supervisor_controller.rb
 - license.md
 - readme.md
 - releases.md
@@ -199,7 +205,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A supervisor for managing multiple container processes.
 test_files: []