Add ProcessMonitor and fix several minor issues.

Author: samuel-williams-shopify

async-container-supervisor.gemspec

@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
 	spec.add_dependency "io-endpoint"
 	spec.add_dependency "memory", "~> 0.7"
 	spec.add_dependency "memory-leak", "~> 0.5"
+	spec.add_dependency "process-metrics"
 end

context/getting-started.md

@@ -120,7 +120,7 @@ service "supervisor" do
 			# Restart workers that exceed 500MB of memory:
 			Async::Container::Supervisor::MemoryMonitor.new(
 				interval: 10,  # Check every 10 seconds
-				limit: 1024 * 1024 * 500  # 500MB limit
+				maximum_size_limit: 1024 * 1024 * 500  # 500MB limit
 			)
 		]
 	end

examples/memory-leak/service.rb

@@ -22,7 +22,7 @@ def setup(container)
 
 				chunks = []
 				while true
-					Console.info(self, "Leaking memory...")
+					# Console.info(self, "Leaking memory...")
 					chunks << " " * 1024 * 1024 * rand(10)
 					sleep 1
 					instance.ready!
@@ -51,7 +51,7 @@ def setup(container)
 			# The interval at which to check for memory leaks.
 			interval: 1,
 			# The total size limit of all processes:
-			maximum_size_limit: 1024 * 1024 * 1000, # 1000 MB
+			maximum_size_limit: 1024 * 1024 * 100, # 1000 MB
 		)]
 	end
 end

examples/process-monitor/readme.md

@@ -0,0 +1,21 @@
+# Process Monitor Example
+
+This example demonstrates how to use the `ProcessMonitor` to log process metrics periodically for all worker processes.
+
+## Overview
+
+The `ProcessMonitor` captures CPU and memory metrics for the entire process tree by tracking the parent process ID (ppid). This is more efficient than tracking individual processes and provides a comprehensive view of resource usage across all workers.
+
+## Usage
+
+Run the service:
+
+```bash
+$ ./service.rb
+```
+
+This will:
+1. Start a supervisor process.
+2. Spawn 4 worker processes that perform CPU and memory work.
+3. Log process metrics every 10 seconds.
+4. Monitor memory usage and restart workers that exceed 500MB.

examples/process-monitor/service.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env async-service
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/container/supervisor"
+
+class WorkerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(name: self.class.name, count: 4, restart: true, health_check_timeout: 2) do |instance|
+			Async do
+				if @environment.implements?(Async::Container::Supervisor::Supervised)
+					@evaluator.make_supervised_worker(instance).run
+				end
+				
+				start_time = Time.now
+				
+				instance.ready!
+				
+				# Simulate some CPU and memory activity
+				counter = 0
+				chunks = []
+				while true
+					# Do some work
+					counter += 1
+					if counter % 10 == 0
+						chunks << " " * 1024 * 1024 * rand(5)
+					end
+					
+					# Simulate CPU usage
+					(1..1000).each {|i| Math.sqrt(i)}
+					
+					sleep 1
+					instance.ready!
+					
+					uptime = Time.now - start_time
+					instance.name = "Worker running for #{uptime.to_i} seconds (counter: #{counter})"
+				end
+			ensure
+				Console.info(self, "Exiting...")
+			end
+		end
+	end	
+end
+
+service "worker" do
+	service_class WorkerService
+	
+	include Async::Container::Supervisor::Supervised
+end
+
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			# Monitor process metrics every 10 seconds
+			Async::Container::Supervisor::ProcessMonitor.new(interval: 10),
+			
+			# Also monitor memory and restart workers if they exceed 500MB
+			Async::Container::Supervisor::MemoryMonitor.new(
+				interval: 5,
+				maximum_size_limit: 1024 * 1024 * 500
+			)
+		]
+	end
+end
+

examples/simple/simple.rb

@@ -48,7 +48,7 @@ def setup(container)
 	monitors do
 		[Async::Container::Supervisor::MemoryMonitor.new(
 			interval: 1,
-			limit: 1024 * 1024 * 400
+			maximum_size_limit: 1024 * 1024 * 400
 		)]
 	end
 end

guides/getting-started/readme.md

@@ -109,25 +109,36 @@ This will start:
 
 ### Adding Health Monitors
 
-You can add monitors to detect and respond to unhealthy conditions. For example, to add a memory monitor:
+You can add monitors to observe worker health and automatically respond to issues. Monitors are useful for:
+
+- **Memory leak detection**: Automatically restart workers consuming excessive memory.
+- **Performance monitoring**: Track CPU and memory usage trends.
+- **Capacity planning**: Understand resource requirements.
+
+For example, to add monitoring:
 
 ```ruby
 service "supervisor" do
 	include Async::Container::Supervisor::Environment
 
 	monitors do
 		[
-			# Restart workers that exceed 500MB of memory:
+			# Log process metrics for observability:
+			Async::Container::Supervisor::ProcessMonitor.new(
+				interval: 60
+			),
+			
+			# Restart workers exceeding memory limits:
 			Async::Container::Supervisor::MemoryMonitor.new(
-				interval: 10,  # Check every 10 seconds
-				limit: 1024 * 1024 * 500  # 500MB limit
+				interval: 10,
+				maximum_size_limit: 1024 * 1024 * 500  # 500MB limit per process
 			)
 		]
 	end
 end
 ```
 
-The {ruby Async::Container::Supervisor::MemoryMonitor} will periodically check worker memory usage and restart any workers that exceed the configured limit.
+See the {ruby Async::Container::Supervisor::MemoryMonitor Memory Monitor} and {ruby Async::Container::Supervisor::ProcessMonitor Process Monitor} guides for detailed configuration options and best practices.
 
 ### Collecting Diagnostics
 

guides/links.yaml

@@ -1,3 +1,8 @@
 getting-started:
   order: 1
 
+memory-monitor:
+  order: 2
+
+process-monitor:
+  order: 3

guides/memory-monitor/readme.md

@@ -0,0 +1,129 @@
+# Memory Monitor
+
+This guide explains how to use the {ruby Async::Container::Supervisor::MemoryMonitor} to detect and restart workers that exceed memory limits or develop memory leaks.
+
+## Overview
+
+Long-running worker processes often accumulate memory over time, either through legitimate growth or memory leaks. Without intervention, workers can consume all available system memory, causing performance degradation or system crashes. The `MemoryMonitor` solves this by automatically detecting and restarting problematic workers before they impact system stability.
+
+Use the `MemoryMonitor` when you need:
+
+- **Memory leak protection**: Automatically restart workers that continuously accumulate memory.
+- **Resource limits**: Enforce maximum memory usage per worker.
+- **System stability**: Prevent runaway processes from exhausting system memory.
+- **Leak diagnosis**: Capture memory samples when leaks are detected for debugging.
+
+The monitor uses the `memory-leak` gem to track process memory usage over time, detecting abnormal growth patterns that indicate leaks.
+
+## Usage
+
+Add a memory monitor to your supervisor service to automatically restart workers that exceed 500MB:
+
+```ruby
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			Async::Container::Supervisor::MemoryMonitor.new(
+				# Check worker memory every 10 seconds:
+				interval: 10,
+
+				# Restart workers exceeding 500MB:
+				maximum_size_limit: 1024 * 1024 * 500
+			)
+		]
+	end
+end
+```
+
+When a worker exceeds the limit:
+1. The monitor logs the leak detection.
+2. Optionally captures a memory sample for debugging.
+3. Sends `SIGINT` to gracefully shut down the worker.
+4. The container automatically spawns a replacement worker.
+
+## Configuration Options
+
+The `MemoryMonitor` accepts the following options:
+
+### `interval`
+
+The interval (in seconds) at which to check for memory leaks. Default: `10` seconds.
+
+```ruby
+Async::Container::Supervisor::MemoryMonitor.new(interval: 30)
+```
+
+### `maximum_size_limit`
+
+The maximum memory size (in bytes) per process. When a process exceeds this limit, it will be restarted.
+
+```ruby
+# 500MB limit
+Async::Container::Supervisor::MemoryMonitor.new(maximum_size_limit: 1024 * 1024 * 500)
+
+# 1GB limit
+Async::Container::Supervisor::MemoryMonitor.new(maximum_size_limit: 1024 * 1024 * 1024)
+```
+
+### `total_size_limit`
+
+The total size limit (in bytes) for all monitored processes combined. If not specified, only per-process limits are enforced.
+
+```ruby
+# Total limit of 2GB across all workers
+Async::Container::Supervisor::MemoryMonitor.new(
+	maximum_size_limit: 1024 * 1024 * 500,  # 500MB per process
+	total_size_limit: 1024 * 1024 * 1024 * 2  # 2GB total
+)
+```
+
+### `memory_sample`
+
+Options for capturing memory samples when a leak is detected. If `nil`, memory sampling is disabled.
+
+Default: `{duration: 30, timeout: 120}`
+
+```ruby
+# Customize memory sampling:
+Async::Container::Supervisor::MemoryMonitor.new(
+	memory_sample: {
+		duration: 60,  # Sample for 60 seconds
+		timeout: 180   # Timeout after 180 seconds
+	}
+)
+
+# Disable memory sampling:
+Async::Container::Supervisor::MemoryMonitor.new(
+	memory_sample: nil
+)
+```
+
+## Memory Leak Detection
+
+When a memory leak is detected, the monitor will:
+
+1. Log the leak detection with process details.
+2. If `memory_sample` is configured, capture a memory sample from the worker.
+3. Send a `SIGINT` signal to gracefully restart the worker.
+4. The container will automatically restart the worker process.
+
+### Memory Sampling
+
+When a memory leak is detected and `memory_sample` is configured, the monitor requests a lightweight memory sample from the worker. This sample:
+
+- Tracks allocations during the sampling period.
+- Forces a garbage collection.
+- Returns a JSON report showing retained objects.
+
+The report includes:
+- `total_allocated`: Total allocated memory and object count.
+- `total_retained`: Total retained memory and count after GC.
+- `by_gem`: Breakdown by gem/library.
+- `by_file`: Breakdown by source file.
+- `by_location`: Breakdown by specific file:line locations.
+- `by_class`: Breakdown by object class.
+- `strings`: String allocation analysis.
+
+This is much more efficient than a full heap dump using `ObjectSpace.dump_all`.