async-service-supervisor 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d6f60f666c3e162c85ca9a275a74dd74dc2219230950d18a0ecf08cffa5761a
-  data.tar.gz: 2c78c20413ca658e6f2341999bfe42fc1600028978ab134ea10f0b0bed5ac44c
+  metadata.gz: df5a5c251964d3435c184c712d4ccc2aa8c74a255d78f3632669a1a527ce78af
+  data.tar.gz: ea832f3d1e9136ccca58f5c5025fe180de773389a739d9b0ad99aae453df2ee2
 SHA512:
-  metadata.gz: c4f862fdaeef651d0b736381340277720b987ac70a3f2e32481a636c638a251f30f5340da9f9789938eb4c7e25b9188b1e3f83c86ae0846f2620d23c9e69365f
-  data.tar.gz: 59291a5fe82bd9dbd2b42ef041b2cde87648666c787c99c90725b88576c0484e759c11fdd6a23ce8d58ce4666f6d21e9258065a2af870f040ab74cbccf15d50a
+  metadata.gz: f54af527ecda8c37129a39f6061095cbaf66b47eec102fd21c1aecb9e5791f487c3d48f567f0a0898a7168ba33bc3a60eef18f7fc1beb656640ce53e3b5f02ed
+  data.tar.gz: a9e0b9c6e8a489665d72ed11b0af0eeca18fa7256bfbcdf9d7bef364554fcd219a15c1dbae49d073d8631a92ca023c689f91936444630198b596fcf2eae110dc

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.16.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,10 @@ 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).
@@ -69,13 +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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # 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).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.16.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: []