Bump minor version.

Author: ioquatix

context/getting-started.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
-				maximum_size_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
 

context/index.yaml

@@ -10,3 +10,11 @@ files:
   title: Getting Started
   description: This guide explains how to get started with `async-container-supervisor`
     to supervise and monitor worker processes in your Ruby applications.
+- path: memory-monitor.md
+  title: Memory Monitor
+  description: This guide explains how to use the <code class="language-ruby">Async::Container::Supervisor::MemoryMonitor</code>
+    to detect and restart workers that exceed memory limits or develop memory leaks.
+- path: process-monitor.md
+  title: Process Monitor
+  description: This guide explains how to use the <code class="language-ruby">Async::Container::Supervisor::ProcessMonitor</code>
+    to log CPU and memory metrics for your worker processes.

context/memory-monitor.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`.

context/process-monitor.md

@@ -0,0 +1,91 @@
+# Process Monitor
+
+This guide explains how to use the {ruby Async::Container::Supervisor::ProcessMonitor} to log CPU and memory metrics for your worker processes.
+
+## Overview
+
+Understanding how your workers consume resources over time is essential for performance optimization, capacity planning, and debugging. Without visibility into CPU and memory usage, you can't identify bottlenecks, plan infrastructure scaling, or diagnose production issues effectively.
+
+The `ProcessMonitor` provides this observability by periodically capturing and logging comprehensive metrics for your entire application process tree.
+
+Use the `ProcessMonitor` when you need:
+
+- **Performance analysis**: Identify which workers consume the most CPU or memory.
+- **Capacity planning**: Determine optimal worker counts and memory requirements.
+- **Trend monitoring**: Track resource usage patterns over time.
+- **Debugging assistance**: Correlate resource usage with application behavior.
+- **Cost optimization**: Right-size infrastructure based on actual usage.
+
+Unlike the {ruby Async::Container::Supervisor::MemoryMonitor}, which takes action when limits are exceeded, the `ProcessMonitor` is purely observational - it logs metrics without interfering with worker processes.
+
+## Usage
+
+Add a process monitor to log resource usage every minute:
+
+```ruby
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			# Log CPU and memory metrics for all processes:
+			Async::Container::Supervisor::ProcessMonitor.new(
+				interval: 60  # Capture metrics every minute
+			)
+		]
+	end
+end
+```
+
+This allows you to easily search and filter by specific fields:
+- `general.process_id = 12347` - Find metrics for a specific process.
+- `general.command = "worker-1"` - Find all metrics for worker processes.
+- `general.processor_utilization > 50` - Find high CPU usage processes.
+- `general.resident_size > 500000` - Find processes using more than 500MB.
+
+## Configuration Options
+
+### `interval`
+
+The interval (in seconds) at which to capture and log process metrics. Default: `60` seconds.
+
+```ruby
+# Log every 30 seconds
+Async::Container::Supervisor::ProcessMonitor.new(interval: 30)
+
+# Log every 5 minutes
+Async::Container::Supervisor::ProcessMonitor.new(interval: 300)
+```
+
+## Captured Metrics
+
+The `ProcessMonitor` captures the following metrics for each process:
+
+### Core Metrics
+
+- **process_id**: Unique identifier for the process.
+- **parent_process_id**: The parent process that spawned this one.
+- **process_group_id**: Process group identifier.
+- **command**: The command name.
+- **processor_utilization**: CPU usage percentage.
+- **resident_size**: Physical memory used (KB).
+- **total_size**: Total memory space including shared memory (KB).
+- **processor_time**: Total CPU time used (seconds).
+- **elapsed_time**: How long the process has been running (seconds).
+
+### Detailed Memory Metrics
+
+When available (OS-dependent), additional memory details are captured:
+
+- **map_count**: Number of memory mappings (stacks, libraries, etc.).
+- **proportional_size**: Memory usage accounting for shared memory (KB).
+- **shared_clean_size**: Unmodified shared memory (KB).
+- **shared_dirty_size**: Modified shared memory (KB).
+- **private_clean_size**: Unmodified private memory (KB).
+- **private_dirty_size**: Modified private memory (KB).
+- **referenced_size**: Active page-cache (KB).
+- **anonymous_size**: Memory not backed by files (KB)
+- **swap_size**: Memory swapped to disk (KB).
+- **proportional_swap_size**: Proportional swap usage (KB).
+- **major_faults**: The number of page faults requiring I/O.
+- **minor_faults**: The number of page faults that don't require I/O (e.g. CoW).

lib/async/container/supervisor/version.rb

@@ -9,7 +9,7 @@ module Async
 	module Container
 		# @namespace
 		module Supervisor
-			VERSION = "0.7.0"
+			VERSION = "0.8.0"
 		end
 	end
 end

readme.md

@@ -18,10 +18,19 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
   - [Getting Started](https://socketry.github.io/async-container-supervisor/guides/getting-started/index) - This guide explains how to get started with `async-container-supervisor` to supervise and monitor worker processes in your Ruby applications.
 
+  - [Memory Monitor](https://socketry.github.io/async-container-supervisor/guides/memory-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Container::Supervisor::MemoryMonitor</code> to detect and restart workers that exceed memory limits or develop memory leaks.
+
+  - [Process Monitor](https://socketry.github.io/async-container-supervisor/guides/process-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Container::Supervisor::ProcessMonitor</code> to log CPU and memory metrics for your worker processes.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-container-supervisor/releases/index) for all releases.
 
+### v0.8.0
+
+  - Add `Async::Container::Supervisor::ProcessMonitor` for logging CPU and memory metrics periodically.
+  - Fix documentation to use correct `maximum_size_limit:` parameter name for `MemoryMonitor` (was incorrectly documented as `limit:`).
+
 ### v0.7.0
 
   - If a memory leak is detected, sample memory usage for 60 seconds before exiting.

releases.md

@@ -1,6 +1,6 @@
 # Releases
 
-## Unreleased
+## v0.8.0
 
   - Add `Async::Container::Supervisor::ProcessMonitor` for logging CPU and memory metrics periodically.
   - Fix documentation to use correct `maximum_size_limit:` parameter name for `MemoryMonitor` (was incorrectly documented as `limit:`).