Introduce UtilizationMonitor.

[samuel-williams-shopify]

Adds a UtilizationMonitor class that efficiently collects and aggregates utilization metrics from worker processes using shared memory. Workers write metrics directly to shared memory segments, and the supervisor reads and aggregates them by service name.

• Shared Memory-Based: Uses memory-mapped files (IO::Buffer) for efficient, zero-copy metric collection, minimal overhead for services to publish metrics.
• Automatic Resizing: Dynamically grows the shared memory file when segments run out (configurable growth factor).
• Service Aggregation: Aggregates metrics from multiple workers by service name.
• Graceful Error Handling: Handles worker registration failures and missing workers without crashing.
• Flexible Schema: Each service publishes metrics according to a well defined schema in shared memory.

Architecture

• UtilizationMonitor: Main class that manages worker registration and metric aggregation.
• SegmentAllocator: Internal class that manages shared memory segment allocation, freeing, and automatic resizing.
• Integration: Works with async-utilization gem - workers use Async::Utilization::Observer to write metrics to shared memory.

Usage

monitor = Async::Service::Supervisor::UtilizationMonitor.new(
  path: "utilization.shm",
  size: IO::Buffer::PAGE_SIZE * 8,
  segment_size: 512
)

# Register workers as they connect:
monitor.register(supervisor_controller)

# Get aggregated metrics by service name:
status = monitor.status
# => {utilization_monitor: {"service_name" => {connections_total: 100, connections_active: 5}}}

# Remove workers when they disconnect:
monitor.remove(supervisor_controller)

Types of Changes

• New feature.

Contribution

• I added tests for my changes.
• I tested my changes locally.
• I agree to the Developer's Certificate of Origin 1.1.

[samuel-williams-shopify]

cc @ivoanjo you might be interested in the design of this feature.

[ivoanjo]

👀 This is super cool and I've been thinking we might want/need something like this for dd-trace-rb as well!