async-service-supervisor 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d6f60f666c3e162c85ca9a275a74dd74dc2219230950d18a0ecf08cffa5761a
-  data.tar.gz: 2c78c20413ca658e6f2341999bfe42fc1600028978ab134ea10f0b0bed5ac44c
+  metadata.gz: 6a0086a1c1f5816a02f4d611debc76dbb5ca57d61add0ae50c95a5c94169b268
+  data.tar.gz: '07742320659e85f1931e75929de111362d503ec3e1f32cda7c4971d0459a95d0'
 SHA512:
-  metadata.gz: c4f862fdaeef651d0b736381340277720b987ac70a3f2e32481a636c638a251f30f5340da9f9789938eb4c7e25b9188b1e3f83c86ae0846f2620d23c9e69365f
-  data.tar.gz: 59291a5fe82bd9dbd2b42ef041b2cde87648666c787c99c90725b88576c0484e759c11fdd6a23ce8d58ce4666f6d21e9258065a2af870f040ab74cbccf15d50a
+  metadata.gz: d67c02d1a93dbda316a5656f832a14337e528d9532bffe28fe78bddd6fadde1181bd7dce9c164c5c602654dd29d3826c370edfd54fe4c4a54179813cb6d35af5
+  data.tar.gz: ad9a517628238cd27c72f5bbf3fcd044eda810b39745faa7c455cfa8cc4f2af24807ad5ecb86d597cd96b0d10b92061f33c8357851b2dd608ea7facaf792f057

checksums.yaml.gz.sig

@@ -1,2 +1,3 @@
-�2뷢��
-�-��ˆ������A, �����W}�)N�S��8
+�v]���s,�[��*�qC�jL�a+��G��p��0�Kk��>%Up	���ig8,�o���
+)�p\��hVk�n�b���7�V�U�!^�X�
+��**�|H��԰]�ZR/�(�u}؁�	8?G��������Qh

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

@@ -56,12 +56,15 @@ module Async
 				end
 				
 				# The supervised worker for the current process.
+				# @parameter state [Hash | Nil] Additional state to register with the supervisor.
 				# @returns [Worker] The worker client.
-				def supervisor_worker
+				def supervisor_worker(state: nil)
+					state = self.supervisor_worker_state.merge(state || {})
+					
 					Worker.new(
 						process_id: Process.pid,
 						endpoint: supervisor_endpoint,
-						state: self.supervisor_worker_state,
+						state: state,
 						utilization_schema: self.utilization_schema,
 						utilization_registry: self.utilization_registry,
 					)
@@ -70,11 +73,12 @@ module Async
 				# Create a supervised worker for the given instance.
 				#
 				# @parameter instance [Async::Container::Instance] The container instance.
+				# @parameter state [Hash | Nil] Additional state to register with the supervisor.
 				# @returns [Worker] The worker client.
-				def prepare!(instance)
+				def prepare!(instance, state: nil)
 					super(instance)
 					
-					supervisor_worker.run
+					supervisor_worker(state: state).run
 				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.16.0"
+			VERSION = "0.18.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.18.0
+
+  - Allow supervised services to merge additional worker state during preparation and worker construction.
+
+### 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).
@@ -65,17 +73,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
   - Add support for `Memory::Leak::Cluster` `free_size_minimum:` option.
   - Remove extraneous "Memory leak detected\!" logs.
 
-### v0.9.1
-
-  - 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,13 @@
 # Releases
 
+## v0.18.0
+
+  - Allow supervised services to merge additional worker state during preparation and worker construction.
+
+## 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.18.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: []