async-service-supervisor 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ae8e8b4a4a8853a5c4c7ff0044a8be8bf6a1da1a9929acd09ddb9284b77b083
-  data.tar.gz: 261ccf70f647cf5676494fc77a952eea875ba342428284df2d56abf4ec1922f9
+  metadata.gz: af7b7a67aaac7ed8eadf666de3a01345e949ba59829aa6c864e94af19f5d422a
+  data.tar.gz: 9765b0474d90eff9294e7865708a0c772a87e8ff7b0787baf0478f67e742b22b
 SHA512:
-  metadata.gz: 5ed659e705698067c9d1d59e1a61674bc82586445c6bf9ace4a932c5e9e79fcb426204f527a2670fffe9e0532adb80e99f20427eb8ab3325ede2a20d4ff4c735
-  data.tar.gz: 12fba3a0e3c4fdbe2379ea8aacd89e271488ac8c8f99e2920b6c63e867e98f4e0552b55442785cb70a21ceee34be9048bf9c2651aab41a8950bdc3b6df5fb9c8
+  metadata.gz: b678aebfa3fe28e7930c4c2426daae4f18acd8da24aa423994d8271c6a2ef8674a0dcdaa138d40c2db98e15faf4d2aa1e85815d63faae3a4cecdd374784409bc
+  data.tar.gz: 118ab77fbf30089894f3537ba839e292d59b5263056efd07aa34af35f1dca599d087a0896a0b1dbe5b0bb1f6654751f87b2f66c98ff2fb5e15d68ac20f372637

data/bake/async/service/supervisor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 def initialize(...)
 	super

data/context/getting-started.md

@@ -133,14 +133,17 @@ service "supervisor" do
 			Async::Service::Supervisor::MemoryMonitor.new(
 				interval: 10,
 				maximum_size_limit: 1024 * 1024 * 500  # 500MB limit per process
+			),
+			
+			# Aggregate application-level metrics (connections, requests) from workers:
+			Async::Service::Supervisor::UtilizationMonitor.new(
+				interval: 10
 			)
 		]
 	end
 end
 ```
 
-See the {ruby Async::Service::Supervisor::MemoryMonitor Memory Monitor} and {ruby Async::Service::Supervisor::ProcessMonitor Process Monitor} guides for detailed configuration options and best practices.
-
 ### Collecting Diagnostics
 
 The supervisor can collect various diagnostics from workers on demand:

data/context/index.yaml

@@ -23,3 +23,8 @@ files:
   title: Process Monitor
   description: This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::ProcessMonitor</code>
     to log CPU and memory metrics for your worker processes.
+- path: utilization-monitor.md
+  title: Utilization Monitor
+  description: This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::UtilizationMonitor</code>
+    to collect and aggregate application-level utilization metrics from your worker
+    processes.

data/context/utilization-monitor.md

@@ -0,0 +1,229 @@
+# Utilization Monitor
+
+This guide explains how to use the {ruby Async::Service::Supervisor::UtilizationMonitor} to collect and aggregate application-level utilization metrics from your worker processes.
+
+## Overview
+
+While the {ruby Async::Service::Supervisor::ProcessMonitor} captures OS-level metrics (CPU, memory) and the {ruby Async::Service::Supervisor::MemoryMonitor} takes action when limits are exceeded, the `UtilizationMonitor` focuses on **application-level metrics**—connections, requests, queue depths, and other business-specific utilization data. Without it, you can't easily answer questions like "How many active connections do my workers have?" or "What is the total request throughput across all workers?"
+
+The `UtilizationMonitor` solves this by using shared memory to efficiently collect metrics from workers and aggregate them by service name. Workers write metrics to a shared memory segment; the supervisor periodically reads and aggregates them without any IPC overhead during collection.
+
+Use the `UtilizationMonitor` when you need:
+
+- **Application observability**: Track connections, requests, queue depths, or custom metrics across workers.
+- **Service-level aggregation**: See totals per service (e.g., "echo" service: 42 connections, 1000 messages).
+- **Lightweight collection**: Avoid IPC or network calls—metrics are read directly from shared memory.
+- **Integration with logging**: Emit aggregated metrics to your logging pipeline for dashboards and alerts.
+
+The monitor uses the `async-utilization` gem for schema definition and shared memory layout. Workers must include {ruby Async::Service::Supervisor::Supervised} and define a `utilization_schema` to participate.
+
+## Usage
+
+### Supervisor Configuration
+
+Add a utilization monitor to your supervisor service:
+
+```ruby
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+	
+	monitors do
+		[
+			Async::Service::Supervisor::UtilizationMonitor.new(
+				path: File.expand_path("utilization.shm", root),
+				interval: 10 # Aggregate and emit metrics every 10 seconds
+			)
+		]
+	end
+end
+```
+
+### Worker Configuration
+
+Workers must include {ruby Async::Service::Supervisor::Supervised} and define a `utilization_schema` that describes the metrics they expose:
+
+```ruby
+service "echo" do
+	include Async::Service::Managed::Environment
+	include Async::Service::Supervisor::Supervised
+	
+	service_class EchoService
+	
+	utilization_schema do
+		{
+			connections_total: :u64,
+			connections_active: :u32,
+			messages_total: :u64
+		}
+	end
+end
+```
+
+### Emitting Metrics from Workers
+
+Workers obtain a utilization registry from the evaluator and use it to update metrics:
+
+```ruby
+def run(instance, evaluator)
+	evaluator.prepare!(instance)
+	instance.ready!
+	
+	registry = evaluator.utilization_registry
+	connections_total = registry.metric(:connections_total)
+	connections_active = registry.metric(:connections_active)
+	messages_total = registry.metric(:messages_total)
+	
+	@bound_endpoint.accept do |peer|
+		connections_total.increment
+		connections_active.track do
+			peer.each_line do |line|
+				messages_total.increment
+				peer.write(line)
+			end
+		end
+	end
+end
+```
+
+The supervisor aggregates these metrics by service name and emits them at the configured interval. For example:
+
+```json
+{
+	"echo": {
+		"connections_total": 150,
+		"connections_active": 12,
+		"messages_total": 45000
+	}
+}
+```
+
+## Configuration Options
+
+### `path`
+
+Path to the shared memory file used for worker metrics. Default: `"utilization.shm"` (relative to current working directory).
+
+Be explicit about the path when using {ruby Async::Service::Supervisor::Environment} so supervisor and workers resolve the same file regardless of working directory:
+
+```ruby
+monitors do
+	[
+		Async::Service::Supervisor::UtilizationMonitor.new(
+			path: File.expand_path("utilization.shm", root),
+			interval: 10
+		)
+	]
+end
+```
+
+### `interval`
+
+The interval (in seconds) at which to aggregate and emit utilization metrics. Default: `10` seconds.
+
+```ruby
+# Emit every second for high-frequency monitoring
+Async::Service::Supervisor::UtilizationMonitor.new(interval: 1)
+
+# Emit every 5 minutes for low-overhead monitoring
+Async::Service::Supervisor::UtilizationMonitor.new(interval: 300)
+```
+
+### `size`
+
+Total size of the shared memory buffer. Default: `IO::Buffer::PAGE_SIZE * 8`. The buffer grows automatically when more workers are registered than segments available.
+
+```ruby
+Async::Service::Supervisor::UtilizationMonitor.new(
+	size: IO::Buffer::PAGE_SIZE * 32  # Larger initial buffer for many workers
+)
+```
+
+### `segment_size`
+
+Size of each allocation segment per worker. Default: `512` bytes. Must accommodate your schema; the `async-utilization` gem lays out fields according to type (e.g., `u64` = 8 bytes, `u32` = 4 bytes).
+
+```ruby
+Async::Service::Supervisor::UtilizationMonitor.new(
+	segment_size: 256  # Smaller segments if schema is compact
+)
+```
+
+## Schema Types
+
+The `utilization_schema` maps metric names to types supported by {ruby IO::Buffer}:
+
+| Type | Size | Use case |
+|------|------|----------|
+| `:u32` | 4 bytes | Counters that may wrap (e.g., connections_active) |
+| `:u64` | 8 bytes | Monotonically increasing counters (e.g., requests_total) |
+| `:i32` | 4 bytes | Signed 32-bit values |
+| `:i64` | 8 bytes | Signed 64-bit values |
+| `:f32` | 4 bytes | Single-precision floats |
+| `:f64` | 8 bytes | Double-precision floats |
+
+Prefer `:u64` for totals that only increase; use `:u32` for gauges or values that may decrease.
+
+## Default Schema
+
+The {ruby Async::Service::Supervisor::Supervised} mixin provides a default schema if you don't override `utilization_schema`:
+
+```ruby
+{
+	connections_active: :u32,
+	connections_total: :u64,
+	requests_active: :u32,
+	requests_total: :u64
+}
+```
+
+Override it when your service has different metrics:
+
+```ruby
+utilization_schema do
+	{
+		connections_active: :u32,
+		connections_total: :u64,
+		messages_total: :u64,
+		queue_depth: :u32
+	}
+end
+```
+
+## Metric API
+
+The utilization registry provides methods to update metrics:
+
+- **`increment`**: Increment a counter by 1.
+- **`set(value)`**: Set a gauge to a specific value.
+- **`track { ... }`**: Execute a block and increment/decrement a gauge around it (e.g., `connections_active` while handling a connection).
+
+```ruby
+connections_total = registry.metric(:connections_total)
+connections_active = registry.metric(:connections_active)
+
+# Increment total connections when a client connects
+connections_total.increment
+
+# Track active connections for the duration of the block
+connections_active.track do
+	handle_client(peer)
+end
+```
+
+## Aggregation Behavior
+
+Metrics are aggregated by service name (from `supervisor_worker_state[:name]`). Values are summed across workers of the same service. For example, with 4 workers each reporting `connections_active: 3`, the aggregated value is `12`.
+
+## Best Practices
+
+- **Define a minimal schema**: Only include metrics you need; each field consumes shared memory.
+- **Use appropriate types**: `u64` for ever-increasing counters; `u32` for gauges.
+- **Match schema across workers**: All workers of the same service should use the same schema for consistent aggregation.
+- **Combine with other monitors**: Use `UtilizationMonitor` alongside `ProcessMonitor` and `MemoryMonitor` for full observability.
+
+## Common Pitfalls
+
+- **Workers without schema**: Workers that don't define `utilization_schema` (or return `nil`) are not registered. They won't contribute to utilization metrics.
+- **Schema mismatch**: If workers of the same service use different schemas, aggregation may produce incorrect or partial results.
+- **Path permissions**: Ensure the shared memory path is accessible to all worker processes (e.g., same user, or appropriate permissions).
+- **Segment size**: If your schema is large, increase `segment_size` to avoid allocation failures.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async/bus/client"
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "io/endpoint/unix_endpoint"
 

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

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async/service/environment"
 require "async/service/managed/environment"
 
 require_relative "service"
+require_relative "server"
 
 module Async
 	module Service

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
 module Async
 	module Service
 		module Supervisor

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "memory/leak/cluster"
 require "set"
@@ -85,11 +85,26 @@ module Async
 					end
 				end
 				
+				# The key used when this monitor's status is aggregated with others.
+				def self.monitor_type
+					:memory_monitor
+				end
+				
+				# Serialize memory cluster data for JSON.
+				def as_json
+					@cluster.as_json
+				end
+				
+				# Serialize to JSON string.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
 				# Get status for the memory monitor.
 				#
-				# @returns [Hash] Status including the memory cluster.
+				# @returns [Hash] Hash with type and data keys.
 				def status
-					{memory_monitor: @cluster.as_json}
+					{type: self.class.monitor_type, data: as_json}
 				end
 				
 				# Invoked when a memory leak is detected.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "process/metrics"
 require_relative "loop"
@@ -57,11 +57,26 @@ module Async
 					Process::Metrics::General.capture(ppid: @ppid).transform_values!(&:as_json)
 				end
 				
+				# The key used when this monitor's status is aggregated with others.
+				def self.monitor_type
+					:process_monitor
+				end
+				
+				# Serialize process metrics for JSON.
+				def as_json
+					{ppid: @ppid, metrics: self.metrics}
+				end
+				
+				# Serialize to JSON string.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
 				# Get status for the process monitor.
 				#
-				# @returns [Hash] Status including process metrics.
+				# @returns [Hash] Hash with type and data keys.
 				def status
-					{process_monitor: {ppid: @ppid, metrics: self.metrics}}
+					{type: self.class.monitor_type, data: as_json}
 				end
 				
 				# Run the process monitor.

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

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

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async"
 require "async/service/managed/service"

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

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async/service/environment"
+require "async/utilization"
+
+require_relative "worker"
 
 module Async
 	module Service
@@ -30,10 +33,38 @@ module Async
 					{name: self.name}
 				end
 				
+				# A default schema for utilization metrics.
+				# @returns [Hash | Nil] The utilization schema or nil if utilization is disabled.
+				def utilization_schema
+					{
+						connections_active: :u32,
+						connections_total: :u64,
+						requests_active: :u32,
+						requests_total: :u64,
+					}
+				end
+				
+				# Get the utilization registry for this service.
+				#
+				# Creates a new registry instance for tracking utilization metrics.
+				# This registry is used by workers to emit metrics that can be collected
+				# by the supervisor's utilization monitor.
+				#
+				# @returns [Async::Utilization::Registry] A new utilization registry instance.
+				def utilization_registry
+					Async::Utilization::Registry.new
+				end
+				
 				# The supervised worker for the current process.
 				# @returns [Worker] The worker client.
 				def supervisor_worker
-					Worker.new(process_id: Process.pid, endpoint: supervisor_endpoint, state: self.supervisor_worker_state)
+					Worker.new(
+						process_id: Process.pid,
+						endpoint: supervisor_endpoint,
+						state: self.supervisor_worker_state,
+						utilization_schema: self.utilization_schema,
+						utilization_registry: self.utilization_registry,
+					)
 				end
 				
 				# Create a supervised worker for the given instance.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by Samuel Williams.
 
 require "async/bus/controller"
 

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

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "set"
+
+require_relative "loop"
+require "async/utilization"
+
+module Async
+	module Service
+		module Supervisor
+			# Monitors worker utilization metrics aggregated by service name.
+			#
+			# Uses shared memory to efficiently collect utilization metrics from workers
+			# and aggregates them by service name for monitoring and reporting.
+			class UtilizationMonitor
+				# Allocates and manages shared memory segments for worker utilization data.
+				#
+				# Manages a shared memory file that workers can write utilization metrics to.
+				# Allocates segments to workers and maintains a free list for reuse.
+				# Each process (supervisor and workers) maps the shared memory file independently.
+				class SegmentAllocator
+					# Initialize a new shared memory manager.
+					#
+					# Creates and maps the shared memory file. Workers will map the same file
+					# independently using the provided path.
+					#
+					# @parameter path [String] Path to the shared memory file.
+					# @parameter size [Integer] Total size of the shared memory buffer.
+					# @parameter segment_size [Integer] Size of each allocation segment (default: 512 bytes).
+					# @parameter growth_factor [Integer, Float] Factor to grow by when resizing (default: 2, doubles the size).
+					#   Can be less than 2 or a floating point value; the result will be page-aligned to an integer.
+					def initialize(path, size: IO::Buffer::PAGE_SIZE * 8, segment_size: 512, growth_factor: 2)
+						@path = path
+						@size = size
+						@segment_size = segment_size
+						@growth_factor = growth_factor
+						
+						@file = File.open(path, "w+b")
+						@file.truncate(size)
+						# Supervisor maps the file for reading worker data
+						@buffer = IO::Buffer.map(@file, size)
+						
+						# Track allocated segments: worker_id => {offset: Integer, schema: Array}
+						@allocations = {}
+						
+						# Free list of segment offsets
+						@free_list = []
+						
+						# Initialize free list with all segments
+						(0...(@size / @segment_size)).each do |segment_index|
+							@free_list << (segment_index * @segment_size)
+						end
+					end
+					
+					# Allocate a segment for a worker.
+					#
+					# Automatically resizes the shared memory file if no segments are available.
+					#
+					# @parameter worker_id [Integer] The ID of the worker.
+					# @parameter schema [Array] Array of [key, type, offset] tuples describing the data layout.
+					# @returns [Integer] The offset into the shared memory buffer, or nil if allocation fails.
+					def allocate(worker_id, schema)
+						# Try to resize if we're out of segments
+						if @free_list.empty?
+							unless resize(@size * @growth_factor)
+								return nil
+							end
+						end
+						
+						offset = @free_list.shift
+						@allocations[worker_id] = {offset: offset, schema: schema}
+						
+						return offset
+					end
+					
+					# Free a segment allocated to a worker.
+					#
+					# @parameter worker_id [Integer] The ID of the worker.
+					def free(worker_id)
+						if allocation = @allocations.delete(worker_id)
+							@free_list << allocation[:offset]
+						end
+					end
+					
+					# Get the allocation information for a worker.
+					#
+					# @parameter worker_id [Integer] The ID of the worker.
+					# @returns [Hash] Allocation info with :offset and :schema, or nil if not allocated.
+					def allocation(worker_id)
+						@allocations[worker_id]
+					end
+					
+					# Get the current size of the shared memory file.
+					#
+					# @returns [Integer] The current size of the shared memory file.
+					def size
+						@size
+					end
+					
+					# Update the schema for an existing allocation.
+					#
+					# @parameter worker_id [Integer] The ID of the worker.
+					# @parameter schema [Array] Array of [key, type, offset] tuples describing the data layout.
+					def update_schema(worker_id, schema)
+						if allocation = @allocations[worker_id]
+							allocation[:schema] = schema
+						end
+					end
+					
+					# Read utilization data from a worker's allocated segment.
+					#
+					# @parameter worker_id [Integer] The ID of the worker.
+					# @returns [Hash] Hash mapping keys to their values, or nil if not allocated.
+					def read(worker_id)
+						allocation = @allocations[worker_id]
+						return nil unless allocation
+						
+						offset = allocation[:offset]
+						schema = allocation[:schema]
+						
+						result = {}
+						schema.each do |key, type, field_offset|
+							absolute_offset = offset + field_offset
+							
+							# Use IO::Buffer type symbols directly (i32, u32, i64, u64, f32, f64)
+							# IO::Buffer accepts both lowercase and uppercase versions
+							begin
+								result[key] = @buffer.get_value(type, absolute_offset)
+							rescue => error
+								Console.warn(self, "Failed to read value", type: type, key: key, offset: absolute_offset, exception: error)
+							end
+						end
+						
+						return result
+					end
+					
+					# Resize the shared memory file.
+					#
+					# Extends the file to the new size, remaps the buffer, and adds new segments
+					# to the free list. The new size must be larger than the current size and should
+					# be page-aligned for optimal performance.
+					#
+					# @parameter new_size [Integer] The new size for the shared memory file.
+					# @returns [Boolean] True if resize was successful, false otherwise.
+					def resize(new_size)
+						old_size = @size
+						return false if new_size <= old_size
+						
+						# Ensure new size is page-aligned (rounds up to nearest page boundary)
+						page_size = IO::Buffer::PAGE_SIZE
+						new_size = (((new_size + page_size - 1) / page_size) * page_size).to_i
+						
+						begin
+							# Extend the file:
+							@file.truncate(new_size)
+							
+							# Remap the buffer to the new size:
+							@buffer&.free
+							@buffer = IO::Buffer.map(@file, new_size)
+							
+							# Calculate new segments to add to free list:
+							old_segment_count = old_size / @segment_size
+							new_segment_count = new_size / @segment_size
+							
+							# Add new segments to free list:
+							(old_segment_count...new_segment_count).each do |segment_index|
+								@free_list << (segment_index * @segment_size)
+							end
+							
+							@size = new_size
+							
+							Console.info(self, "Resized shared memory", old_size: old_size, new_size: new_size, segments_added: new_segment_count - old_segment_count)
+							
+							return true
+						rescue => error
+							Console.error(self, "Failed to resize shared memory", old_size: old_size, new_size: new_size, exception: error)
+							return false
+						end
+					end
+					
+					# Close the shared memory file.
+					def close
+						@file&.close
+						@buffer = nil
+					end
+				end
+				# Initialize a new utilization monitor.
+				#
+				# @parameter path [String] Path to the shared memory file.
+				# @parameter interval [Integer] Interval in seconds to aggregate and update metrics.
+				# @parameter size [Integer] Total size of the shared memory buffer.
+				# @parameter segment_size [Integer] Size of each allocation segment (default: 512 bytes).
+				def initialize(path: "utilization.shm", interval: 10, size: IO::Buffer::PAGE_SIZE * 8, segment_size: 512)
+					@path = path
+					@interval = interval
+					@segment_size = segment_size
+					
+					@allocator = SegmentAllocator.new(path, size: size, segment_size: segment_size)
+					
+					# Track workers: worker_id => supervisor_controller
+					@workers = {}
+					
+					@guard = Mutex.new
+				end
+				
+				# Register a worker with the utilization monitor.
+				#
+				# Allocates a segment of shared memory and instructs the worker
+				# to map the shared memory file and expose utilization information at the allocated offset.
+				# The worker maps the file independently and returns its schema.
+				#
+				# @parameter supervisor_controller [SupervisorController] The supervisor controller for the worker.
+				def register(supervisor_controller)
+					@guard.synchronize do
+						worker_id = supervisor_controller.id
+						return unless worker_id
+						
+						# Allocate a segment first (we'll get schema from worker)
+						offset = @allocator.allocate(worker_id, [])
+						
+						unless offset
+							Console.warn(self, "Failed to allocate utilization segment", worker_id: worker_id)
+							return
+						end
+						
+						# Inform worker of the shared memory path, size, and allocated offset
+						# The worker will map the file itself and return its schema
+						begin
+							worker = supervisor_controller.worker
+							
+							if worker
+								# Pass the segment size - observer will handle page alignment and file mapping
+								schema = worker.setup_utilization_observer(@path, @segment_size, offset)
+								
+								# Update the allocation with the actual schema
+								if schema && !schema.empty?
+									@allocator.update_schema(worker_id, schema)
+									@workers[worker_id] = supervisor_controller
+									
+									Console.info(self, "Registered worker utilization", worker_id: worker_id, offset: offset, schema: schema)
+								else
+									# Worker didn't provide schema, free the allocation
+									@allocator.free(worker_id)
+									Console.info(self, "Worker did not provide utilization schema", worker_id: worker_id)
+								end
+							end
+						rescue => error
+							Console.error(self, "Error setting up worker utilization", worker_id: worker_id, exception: error)
+							@allocator.free(worker_id)
+						end
+					end
+				end
+				
+				# Remove a worker from the utilization monitor.
+				#
+				# Returns the allocated segment back to the free list.
+				#
+				# @parameter supervisor_controller [SupervisorController] The supervisor controller for the worker.
+				def remove(supervisor_controller)
+					@guard.synchronize do
+						worker_id = supervisor_controller.id
+						return unless worker_id
+						
+						@workers.delete(worker_id)
+						@allocator.free(worker_id)
+						
+						Console.debug(self, "Freed utilization segment", worker_id: worker_id)
+					end
+				end
+				
+				# The key used when this monitor's status is aggregated with others.
+				def self.monitor_type
+					:utilization_monitor
+				end
+				
+				# Serialize utilization data for JSON.
+				#
+				# @returns [Hash] Hash mapping service names to aggregated utilization metrics.
+				def as_json
+					@guard.synchronize do
+						aggregated = {}
+						
+						@workers.each do |worker_id, supervisor_controller|
+							service_name = supervisor_controller.state[:name] || "unknown"
+							
+							data = @allocator.read(worker_id)
+							next unless data
+							
+							# Initialize service aggregation if needed
+							aggregated[service_name] ||= {}
+							
+							# Sum up all numeric fields
+							data.each do |key, value|
+								if value.is_a?(Numeric)
+									aggregated[service_name][key] ||= 0
+									aggregated[service_name][key] += value
+								else
+									# For non-numeric values, we could handle differently
+									# For now, just store the last value
+									aggregated[service_name][key] = value
+								end
+							end
+						end
+						
+						aggregated
+					end
+				end
+				
+				# Serialize to JSON string.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
+				# Get aggregated utilization status by service name.
+				#
+				# Reads utilization data from all registered workers and aggregates it
+				# by service name (from supervisor_controller.state[:name]).
+				#
+				# @returns [Hash] Hash with type and data keys.
+				def status
+					{type: self.class.monitor_type, data: as_json}
+				end
+				
+				# Emit the utilization metrics.
+				#
+				# @parameter status [Hash] The utilization metrics.
+				def emit(metrics)
+					Console.info(self, "Utilization:", metrics: metrics)
+				end
+				
+				# Run the utilization monitor.
+				#
+				# Periodically aggregates utilization data from all workers.
+				#
+				# @returns [Async::Task] The task that is running the utilization monitor.
+				def run
+					Async do
+						Loop.run(interval: @interval) do
+							self.emit(self.as_json)
+						end
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # @namespace
 module Async
@@ -9,7 +9,7 @@ module Async
 	module Service
 		# @namespace
 		module Supervisor
-			VERSION = "0.11.1"
+			VERSION = "0.12.0"
 		end
 	end
 end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "client"
 require_relative "worker_controller"
@@ -26,12 +26,17 @@ module Async
 				# @parameter process_id [Integer] The process ID to register with the supervisor.
 				# @parameter endpoint [IO::Endpoint] The supervisor endpoint to connect to.
 				# @parameter state [Hash] Optional state to associate with this worker (e.g., service name).
-				def initialize(process_id: Process.pid, endpoint: Supervisor.endpoint, state: {})
+				# @parameter utilization_schema [Hash | Nil] Optional utilization schema definition.
+				# @parameter utilization_registry [Registry, nil] Optional utilization registry. If nil, a new registry is created.
+				def initialize(process_id: Process.pid, endpoint: Supervisor.endpoint, state: {}, utilization_schema: nil, utilization_registry: nil)
 					super(endpoint: endpoint)
 					
 					@id = nil
 					@process_id = process_id
 					@state = state
+					
+					@utilization_schema = utilization_schema
+					@utilization_registry = utilization_registry || require("async/utilization") && Async::Utilization::Registry.new
 				end
 				
 				# @attribute [Integer] The ID assigned by the supervisor.
@@ -43,6 +48,34 @@ module Async
 				# @attribute [Hash] State associated with this worker (e.g., service name).
 				attr_accessor :state
 				
+				# @attribute [Hash | Nil] Utilization schema definition.
+				attr :utilization_schema
+				
+				# @attribute [Registry] The utilization registry for this worker.
+				attr :utilization_registry
+				
+				# Setup utilization observer for this worker.
+				#
+				# Maps the shared memory file and configures the utilization registry to write
+				# metrics to it. Called by the supervisor (via WorkerController) to inform the
+				# worker of the shared memory file path and allocated offset.
+				#
+				# @parameter path [String] Path to the shared memory file that the worker should map.
+				# @parameter size [Integer] Size of the shared memory region to map.
+				# @parameter offset [Integer] Offset into the shared memory buffer allocated for this worker.
+				# @returns [Array] Array of [key, type, offset] tuples describing the utilization schema.
+				#   Returns empty array if no utilization schema is configured.
+				def setup_utilization_observer(path, size, offset)
+					return [] unless @utilization_schema
+					
+					schema = Async::Utilization::Schema.build(@utilization_schema)
+					observer = Async::Utilization::Observer.open(schema, path, size, offset)
+					@utilization_registry.observer = observer
+					
+					# Pass the schema back to the supervisor so it can be used to aggregate the metrics:
+					observer.schema.to_a
+				end
+				
 				protected def connected!(connection)
 					super
 					

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async/bus/controller"
 require "stringio"
@@ -101,6 +101,19 @@ module Async
 				ensure
 					GC::Profiler.disable
 				end
+				
+				# Setup utilization observer for this worker.
+				#
+				# Delegates to the worker to map the shared memory file and configure its
+				# utilization registry. Called by the supervisor via RPC.
+				#
+				# @parameter path [String] Path to the shared memory file that the worker should map.
+				# @parameter size [Integer] Size of the shared memory region to map.
+				# @parameter offset [Integer] Offset into the shared memory buffer allocated for this worker.
+				# @returns [Array] Array of [key, type, offset] tuples describing the utilization schema.
+				def setup_utilization_observer(path, size, offset)
+					@worker.setup_utilization_observer(path, size, offset)
+				end
 			end
 		end
 	end

data/lib/async/service/supervisor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "supervisor/version"
 
@@ -12,6 +12,7 @@ require_relative "supervisor/client"
 
 require_relative "supervisor/memory_monitor"
 require_relative "supervisor/process_monitor"
+require_relative "supervisor/utilization_monitor"
 
 require_relative "supervisor/environment"
 require_relative "supervisor/supervised"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2025, by Samuel Williams.  
+Copyright, 2025-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -24,10 +24,16 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
   - [Process Monitor](https://socketry.github.io/async-service-supervisor/guides/process-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::ProcessMonitor</code> to log CPU and memory metrics for your worker processes.
 
+  - [Utilization Monitor](https://socketry.github.io/async-service-supervisor/guides/utilization-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::UtilizationMonitor</code> to collect and aggregate application-level utilization metrics from your worker processes.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor/releases/index) for all releases.
 
+### v0.12.0
+
+  - Introduce `UtilizationMonitor`, that uses shared memory to track worker utilization metrics, like total and active requests, connections, etc.
+
 ### v0.11.0
 
   - Add `state` attribute to `SupervisorController` to store per-worker metadata (e.g., service name).
@@ -73,10 +79,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
 
   - Fix timed out RPCs and subsequent responses which should be ignored.
 
-### v0.6.0
-
-  - Add `async:container:supervisor:reload` command to restart the container (blue/green deployment).
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.12.0
+
+  - Introduce `UtilizationMonitor`, that uses shared memory to track worker utilization metrics, like total and active requests, connections, etc.
+
 ## v0.11.0
 
   - Add `state` attribute to `SupervisorController` to store per-worker metadata (e.g., service name).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: async-utilization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: io-endpoint
   requirement: !ruby/object:Gem::Requirement
@@ -132,6 +146,7 @@ files:
 - context/memory-monitor.md
 - context/migration.md
 - context/process-monitor.md
+- context/utilization-monitor.md
 - lib/async/service/supervisor.rb
 - lib/async/service/supervisor/client.rb
 - lib/async/service/supervisor/endpoint.rb
@@ -143,6 +158,7 @@ files:
 - lib/async/service/supervisor/service.rb
 - lib/async/service/supervisor/supervised.rb
 - lib/async/service/supervisor/supervisor_controller.rb
+- lib/async/service/supervisor/utilization_monitor.rb
 - lib/async/service/supervisor/version.rb
 - lib/async/service/supervisor/worker.rb
 - lib/async/service/supervisor/worker_controller.rb
@@ -162,7 +178,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="