async-service-supervisor 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a0086a1c1f5816a02f4d611debc76dbb5ca57d61add0ae50c95a5c94169b268
-  data.tar.gz: '07742320659e85f1931e75929de111362d503ec3e1f32cda7c4971d0459a95d0'
+  metadata.gz: 537a7bbe49f8304f907d4b258931dd3de900c591d781dd305b0daa8c285d4432
+  data.tar.gz: 2a1da9aa30958fd2628312aa053aaf2f6d61215689761c6bf8247b9e09510b4b
 SHA512:
-  metadata.gz: d67c02d1a93dbda316a5656f832a14337e528d9532bffe28fe78bddd6fadde1181bd7dce9c164c5c602654dd29d3826c370edfd54fe4c4a54179813cb6d35af5
-  data.tar.gz: ad9a517628238cd27c72f5bbf3fcd044eda810b39745faa7c455cfa8cc4f2af24807ad5ecb86d597cd96b0d10b92061f33c8357851b2dd608ea7facaf792f057
+  metadata.gz: 86c98af76a9bd87f0c31bdf590765ac3e851d259604f1a62e0a5df134943fce4bfccf67ddaa3870c4c202f34eae9eab0a71cbcc72879ec7191f868147c3ad8ba
+  data.tar.gz: 7daac497ebd34ff0cd408bb34284979da4bb727a70e754be0b3c30e35ceaabefb60545523b9d47be9741551df2b54893d3535c44e612c9e7139f3b90298f726b

data/bake/async/service/supervisor.rb

@@ -32,12 +32,98 @@ def status
 	end
 end
 
+# List the connection IDs of all registered workers.
+def workers
+	client do |connection|
+		supervisor = connection[:supervisor]
+		supervisor.keys
+	end
+end
+
+# Dump the object space of a worker to a file on the worker's filesystem.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+# @parameter path [String] The file path where the worker should write the dump.
+# @parameter shapes [Boolean] Whether to include Ruby shape-tree records.
+def memory_dump(connection_id:, path:, shapes: true)
+	with_worker(connection_id) do |worker|
+		worker.memory_dump(path: path, shapes: shapes)
+	end
+end
+
+# Start recording object allocation metadata in a worker.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+def allocation_trace_start(connection_id:)
+	with_worker(connection_id) do |worker|
+		worker.allocation_trace_start
+	end
+end
+
+# Stop recording object allocations, dump the traced heap, and clear the metadata.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+# @parameter path [String] The file path where the worker should write the dump.
+# @parameter shapes [Boolean] Whether to include Ruby shape-tree records.
+def allocation_trace_stop(connection_id:, path:, shapes: true)
+	with_worker(connection_id) do |worker|
+		worker.allocation_trace_stop(path: path, shapes: shapes)
+	end
+end
+
+# Dump the fiber scheduler hierarchy of a worker.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+# @parameter path [String | Nil] An optional file path on the worker's filesystem.
+# @parameter log [String | Nil] An optional message to log with the dump.
+def scheduler_dump(connection_id:, path: nil, log: nil)
+	with_worker(connection_id) do |worker|
+		worker.scheduler_dump(path: path, log: log)
+	end
+end
+
+# Dump information about all threads in a worker.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+# @parameter path [String | Nil] An optional file path on the worker's filesystem.
+def thread_dump(connection_id:, path: nil)
+	with_worker(connection_id) do |worker|
+		worker.thread_dump(path: path)
+	end
+end
+
+# Start garbage collection profiling in a worker.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+def garbage_profile_start(connection_id:)
+	with_worker(connection_id) do |worker|
+		worker.garbage_profile_start
+	end
+end
+
+# Stop garbage collection profiling in a worker and return or save the results.
+#
+# @parameter connection_id [Integer] The connection ID of the worker to target.
+# @parameter path [String | Nil] An optional file path on the worker's filesystem.
+def garbage_profile_stop(connection_id:, path: nil)
+	with_worker(connection_id) do |worker|
+		worker.garbage_profile_stop(path: path)
+	end
+end
+
 private
 
 def endpoint
 	Async::Service::Supervisor.endpoint
 end
 
+def with_worker(connection_id)
+	client do |connection|
+		supervisor = connection[:supervisor]
+		yield supervisor[connection_id]
+	end
+end
+
 def client(&block)
 	Sync do
 		Async::Service::Supervisor::Client.new(endpoint: self.endpoint).connect(&block)

data/context/getting-started.md

@@ -149,44 +149,28 @@ end
 The supervisor can collect various diagnostics from workers on demand:
 
 - **Memory dumps**: Full heap dumps for memory analysis via `ObjectSpace.dump_all`.
-- **Memory samples**: Lightweight sampling to identify memory leaks.
 - **Thread dumps**: Stack traces of all threads.
-- **Scheduler dumps**: Async fiber hierarchy
-- **Garbage collection profiles**: GC performance data
+- **Scheduler dumps**: Async fiber hierarchy.
+- **Garbage collection profiles**: GC performance data.
 
-These can be triggered programmatically or via command-line tools (when available).
+These can be triggered programmatically or with Bake tasks.
 
 #### Memory Leak Diagnosis
 
-To identify memory leaks, you can use the memory sampling feature which is much lighter weight than a full memory dump. It tracks allocations over a time period and focuses on retained objects.
-
-**Using the bake task:**
+Start by listing the workers registered with the supervisor:
 
 ```bash
-# Sample for 30 seconds and print report to console
-$ bake async:container:supervisor:memory_sample duration=30
+$ bake async:service:supervisor:workers
 ```
 
-**Programmatically:**
+Then capture heap dumps from the same worker before and after the suspected growth period:
 
-```ruby
-# Assuming you have a connection to a worker:
-result = connection.call(do: :memory_sample, duration: 30)
-puts result[:data]
+```bash
+$ bake async:service:supervisor:memory_dump connection_id=1 path=/var/tmp/worker-before.json
+$ bake async:service:supervisor:memory_dump connection_id=1 path=/var/tmp/worker-after.json
 ```
 
-This will sample memory allocations for the specified duration, then force a garbage collection and return a JSON report showing what objects were allocated during that period and retained after GC. Late-lifecycle allocations that are retained are likely memory leaks.
-
-The JSON report includes:
-- `total_allocated`: Total allocated memory and count
-- `total_retained`: Total retained memory and count  
-- `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 `do: :memory_dump` which uses `ObjectSpace.dump_all` and can be slow and blocking on large heaps. The JSON format also makes it easy to integrate with monitoring and analysis tools.
+Heap dumps are heavyweight and may contain sensitive application data. See the [Memory Diagnostics](../memory-diagnostics/index) guide for the complete capture, comparison, and GC profiling workflow.
 
 ## Advanced Usage
 

data/context/index.yaml

@@ -19,6 +19,10 @@ files:
   title: Memory Monitor
   description: This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::MemoryMonitor</code>
     to detect and restart workers that exceed memory limits or develop memory leaks.
+- path: memory-diagnostics.md
+  title: Memory Diagnostics
+  description: This guide explains how to capture Ruby heap dumps and garbage collection
+    profiles from supervised workers, then use them to investigate memory growth.
 - path: process-monitor.md
   title: Process Monitor
   description: This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::ProcessMonitor</code>

data/context/memory-diagnostics.md

@@ -0,0 +1,249 @@
+# Memory Diagnostics
+
+This guide explains how to capture Ruby heap dumps and garbage collection profiles from supervised workers, then use them to investigate memory growth.
+
+## Overview
+
+Use the diagnostic Bake tasks when a worker's memory grows unexpectedly and you need to understand what it is retaining. A typical investigation combines:
+
+- {ruby Async::Service::Supervisor::MemoryMonitor} or process metrics to identify sustained growth.
+- Heap dumps to compare the objects present before and after representative load.
+- Garbage collection profiles to measure time spent collecting objects.
+- Scheduler and thread dumps to correlate memory growth with stuck or unusually long-running work.
+
+These operations run inside the selected worker. They are intended for diagnosis rather than continuous monitoring.
+
+## Finding a Worker
+
+Run Bake from the service root where `supervisor.ipc` is located, then list the registered workers:
+
+```bash
+$ bake async:service:supervisor:workers
+```
+
+The result contains supervisor-assigned connection IDs. These IDs are not process IDs and may change whenever a worker or supervisor restarts. List the workers again if an operation reports that the connection no longer exists.
+
+When workers are interchangeable, choose one ID and use that same worker throughout an investigation. If a worker restarts between snapshots, its replacement has a new heap and a new connection ID, so the snapshots are not directly comparable.
+
+## Capturing a Heap Dump
+
+Choose a path that is writable from the worker and has enough free space:
+
+```bash
+$ bake async:service:supervisor:memory_dump \
+    connection_id=1 \
+    path=/var/tmp/worker-1-before.json
+```
+
+The returned path identifies the file written by the worker:
+
+```text
+{:path=>"/var/tmp/worker-1-before.json"}
+```
+
+The path is resolved in the worker's filesystem namespace, not the shell running Bake. For a containerized or remote worker, retrieve the file from that worker or write it to a shared volume.
+
+Ruby heap dumps use newline-delimited JSON: each line describes an object, root, or heap record. They are not a single JSON array.
+
+### Operational Safety
+
+A full heap dump calls `ObjectSpace.dump_all`. Before running it in production, consider the following:
+
+- Dumping a large heap is slow and blocks the selected worker while Ruby walks its object space.
+- The output can be much larger than the worker's resident memory. Check available disk space first.
+- Heap records may contain application strings and other sensitive data. Store and transfer dumps accordingly.
+- Avoid capturing every worker at once. Start with one representative worker during a low-risk period.
+- The dump includes objects present at that instant, including garbage that Ruby has not collected yet. For retained-growth comparisons, capture snapshots shortly after comparable GC activity when possible.
+
+## Analyzing Heap Dumps
+
+Different tools answer different questions about a heap dump:
+
+| Tool | Best for | Snapshots |
+| --- | --- | --- |
+| [`heap-profiler`](https://github.com/Shopify/heap-profiler) | Aggregate memory and object counts by class, gem, file, and location | One |
+| [`sheap`](https://github.com/jhawthorn/sheap) | Finding objects retained across snapshots and tracing paths back to roots | Two or three |
+| [Reap](https://github.com/oxidize-rb/reap) | Finding objects that dominate and retain large portions of a heap | One |
+
+Install and run these tools on a trusted analysis system after retrieving the dumps from the worker. The dumps can contain sensitive application data.
+
+### Aggregate Reports with `heap-profiler`
+
+Capture a heap dump and pass it directly to `heap-profiler`:
+
+```bash
+$ bake async:service:supervisor:memory_dump \
+    connection_id=1 \
+    path=/var/tmp/worker-1.json
+
+$ gem install heap-profiler
+$ heap-profiler /var/tmp/worker-1.json
+```
+
+Use `--max` to show more entries when the default report is too short:
+
+```bash
+$ heap-profiler --max=100 /var/tmp/worker-1.json
+```
+
+The report is a useful overview of the largest classes, strings, and allocation locations in one snapshot. It does not calculate a delta between arbitrary Bake snapshots. Capture reports at comparable points in the workload if you want to compare their aggregate counts manually.
+
+### Retention Diffs with `sheap`
+
+Capture a baseline and two later snapshots from the same worker. The third snapshot distinguishes objects that remain retained from temporary allocations present only in the second dump:
+
+```bash
+$ bake async:service:supervisor:memory_dump connection_id=1 path=/var/tmp/worker-1-before.json
+
+# Run representative traffic or wait through the suspected growth period.
+$ bake async:service:supervisor:memory_dump connection_id=1 path=/var/tmp/worker-1-after.json
+
+# Run another comparable workload and GC cycle.
+$ bake async:service:supervisor:memory_dump connection_id=1 path=/var/tmp/worker-1-later.json
+```
+
+Install `sheap` and open an interactive two-snapshot diff:
+
+```bash
+$ gem install sheap
+$ sheap /var/tmp/worker-1-before.json /var/tmp/worker-1-after.json
+```
+
+The command opens IRB with `$before`, `$after`, and `$diff` available. For example:
+
+```ruby
+# Count newly retained objects by Ruby heap type:
+$diff.retained.map(&:type_str).tally.sort_by(&:last).last(20)
+
+# Inspect a large retained collection and find its path from a heap root:
+large_array = $diff.retained.arrays.max_by(&:length)
+$after.find_path(large_array)
+```
+
+Use the library API for a three-snapshot diff:
+
+```ruby
+three_way = Sheap::Diff.new(
+	"/var/tmp/worker-1-before.json",
+	"/var/tmp/worker-1-after.json",
+	"/var/tmp/worker-1-later.json"
+)
+
+three_way.retained.map(&:type_str).tally.sort_by(&:last).last(20)
+```
+
+`sheap` identifies objects by heap address and type. Heap compaction can move objects, while freed addresses can be reused, so disable automatic compaction during the investigation and prefer a three-snapshot diff. Always compare dumps from the same live worker.
+
+Look for:
+
+- Collection classes whose object count or shallow memory continually grows.
+- Repeated strings or payloads that should have expired.
+- Paths from roots through registries, caches, queues, or other long-lived state.
+- Objects that remain in the three-snapshot diff after comparable GC activity.
+
+### Dominator Analysis with Reap
+
+Reap builds a dominator tree from a single heap's reference graph. An object dominates another object when every path from a heap root to the second object passes through the first. This makes Reap useful for finding a small cache, queue, thread, or registry that keeps a much larger object graph alive.
+
+Reap does not currently accept Ruby's address-less `SHAPE` records. Disable them when capturing a dump for Reap:
+
+```bash
+$ bake async:service:supervisor:memory_dump \
+    connection_id=1 \
+    path=/var/tmp/worker-1-reap.json \
+    shapes=false
+```
+
+Install Reap with Cargo, then print the largest dominators and optionally generate an inverted flame graph:
+
+```bash
+$ cargo install reap
+$ reap /var/tmp/worker-1-reap.json \
+    --count 20 \
+    --flamegraph /var/tmp/worker-1-retained.svg
+```
+
+The report separates an object's shallow size from the total memory it dominates. Use `--root ADDRESS` to repeat the analysis for a suspicious subtree, or `--dot FILE` to write its dominator graph. Dumps captured with `shapes=false` remain compatible with `heap-profiler` and `sheap`.
+
+Reap does not compare snapshots or use allocation generations. Combine it with a `sheap` diff when you need both evidence of continued retention and the aggregate size of the retained graph.
+
+## Recording Allocation Locations
+
+By default, a heap dump may not contain allocation source locations. Start tracing on the selected worker before the workload you want to investigate:
+
+```bash
+$ bake async:service:supervisor:allocation_trace_start connection_id=1
+```
+
+Exercise the workload, then stop tracing and write the heap dump:
+
+```bash
+$ bake async:service:supervisor:allocation_trace_stop \
+    connection_id=1 \
+    path=/var/tmp/worker-1-traced.json
+```
+
+The stop operation disables tracing before dumping the heap, then clears the allocation metadata after the dump is complete. Start and stop must target the same live connection ID. Use `shapes=false` with the stop task when the dump will be analyzed by Reap.
+
+Allocation tracing is process-global and adds runtime and memory overhead, so enable it selectively and measure its impact before using it in production. The start task refuses to run if tracing is already active, avoiding interference with another profiler. While tracing is enabled, heap records can include `file`, `line`, `method`, and allocation generation fields. `heap-profiler` automatically includes breakdowns by gem, file, and location when this information is present.
+
+High allocation counts identify hot allocation sites. Compare the `heap-profiler` reports and focus on locations whose objects remain present and continue accumulating, rather than sites that merely allocate many short-lived objects.
+
+## Profiling Garbage Collection
+
+Start the Ruby GC profiler on the same worker you are investigating:
+
+```bash
+$ bake async:service:supervisor:garbage_profile_start connection_id=1
+```
+
+Exercise the workload, then stop profiling and write the report:
+
+```bash
+$ bake async:service:supervisor:garbage_profile_stop \
+    connection_id=1 \
+    path=/var/tmp/worker-1-gc.txt
+```
+
+The start and stop commands must target the same live connection ID. The report is written in the worker's filesystem namespace.
+
+GC profiling helps distinguish several patterns:
+
+- Growing heap size and increasing GC time can indicate retained objects or a cache without a bound.
+- High GC time without retained heap growth usually indicates allocation churn rather than a leak.
+- Heap growth with little GC activity may mean the workload has not yet forced collection; compare snapshots after similar GC activity.
+
+GC profiling records collection timing and heap statistics. It does not identify which objects retain memory, so use it alongside heap dumps.
+
+## Capturing Scheduler and Thread State
+
+Memory growth can be caused by queued work, blocked requests, or fibers retaining large request graphs. Capture scheduler and thread state from the same worker:
+
+```bash
+$ bake async:service:supervisor:scheduler_dump \
+    connection_id=1 \
+    path=/var/tmp/worker-1-scheduler.txt
+
+$ bake async:service:supervisor:thread_dump \
+    connection_id=1 \
+    path=/var/tmp/worker-1-threads.txt
+```
+
+Without `path`, scheduler and thread dumps are returned to Bake instead of being written by the worker. A path is usually more convenient for large diagnostic output.
+
+Look for fibers or threads that remain in every snapshot, queues that never drain, and repeated backtraces corresponding to the workload that causes memory growth.
+
+## Suggested Investigation Workflow
+
+1. Confirm sustained growth with the `MemoryMonitor`, `ProcessMonitor`, or external process metrics.
+2. List worker connection IDs and select one representative worker.
+3. Enable allocation tracing before the workload if its overhead is acceptable.
+4. Capture a baseline heap dump after normal warm-up, using `shapes=false` if you plan to use Reap.
+5. Start GC profiling and run representative traffic or wait through the suspected leak interval.
+6. Capture scheduler and thread dumps if work appears stuck or backlogged.
+7. Stop GC profiling and capture the second heap dump from the same worker.
+8. Repeat the workload and capture a third dump for a stronger `sheap` retention signal.
+9. Use `heap-profiler` for aggregate counts, `sheap` for retained objects and root paths, and Reap for dominator sizes.
+10. Repeat the experiment if necessary to distinguish sustained retention from normal cache warm-up.
+
+Use the {ruby Async::Service::Supervisor::MemoryMonitor} to protect production from unbounded growth, but complete diagnostics before its configured limit restarts the worker. A restarted worker receives a new connection ID and loses the heap state you were observing.

data/context/memory-monitor.md

@@ -11,7 +11,7 @@ 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.
+- **Leak diagnosis**: Identify workers that should be investigated with heap diagnostics.
 
 The monitor uses the `memory-leak` gem to track process memory usage over time, detecting abnormal growth patterns that indicate leaks.
 
@@ -39,9 +39,8 @@ 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.
+2. Sends `SIGINT` to gracefully shut down the worker.
+3. The container automatically spawns a replacement worker.
 
 ## Configuration Options
 
@@ -79,51 +78,21 @@ Async::Service::Supervisor::MemoryMonitor.new(
 )
 ```
 
-### `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::Service::Supervisor::MemoryMonitor.new(
-	memory_sample: {
-		duration: 60,  # Sample for 60 seconds
-		timeout: 180   # Timeout after 180 seconds
-	}
-)
-
-# Disable memory sampling:
-Async::Service::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
+2. Send a `SIGINT` signal to gracefully restart the worker.
+3. The container will automatically restart the worker process.
 
-When a memory leak is detected and `memory_sample` is configured, the monitor requests a lightweight memory sample from the worker. This sample:
+### Heap Diagnostics
 
-- Tracks allocations during the sampling period.
-- Forces a garbage collection.
-- Returns a JSON report showing retained objects.
+The monitor does not automatically capture heap data before restarting a worker. When investigating growth, use the worker diagnostic Bake tasks to:
 
-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.
+- List live worker connection IDs.
+- Capture full `ObjectSpace` heap dumps before and after representative load.
+- Record garbage collection profiles.
+- Capture scheduler and thread state.
 
-This is much more efficient than a full heap dump using `ObjectSpace.dump_all`.
+See the [Memory Diagnostics](../memory-diagnostics/index) guide for a safe capture and comparison workflow. Complete the diagnostic capture before the configured limit restarts the worker.

data/context/migration.md

@@ -223,7 +223,7 @@ $ bake async:service:supervisor:reload
 $ bake async:service:supervisor:status
 ```
 
-**Note:** The `memory_sample` bake task has been removed in `async-service-supervisor`. This functionality was removed as it wasn't very useful and added complexity. If you were using memory sampling, you'll need to find alternative approaches for memory leak detection, such as using the `MemoryMonitor` with appropriate limits or external memory profiling tools.
+**Note:** The `memory_sample` Bake task has been removed in `async-service-supervisor`. Use the `MemoryMonitor` to detect sustained growth and the worker diagnostic Bake tasks to capture heap dumps and GC profiles. See the [Memory Diagnostics](../memory-diagnostics/index) guide for the recommended workflow.
 
 ### 8. Update Programmatic Client Usage
 

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

@@ -9,7 +9,7 @@ module Async
 	module Service
 		# @namespace
 		module Supervisor
-			VERSION = "0.18.0"
+			VERSION = "0.19.0"
 		end
 	end
 end

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

@@ -57,14 +57,49 @@ module Async
 				# This is a heavyweight operation that dumps all objects in the heap.
 				#
 				# @parameter path [String] Optional file path to save the dump.
-				def memory_dump(path: nil)
+				# @parameter shapes [Boolean] Whether to include Ruby shape-tree records.
+				def memory_dump(path: nil, shapes: true)
 					require "objspace"
 					
 					dump(path: path, buffer: false) do |file|
-						ObjectSpace.dump_all(output: file)
+						ObjectSpace.dump_all(output: file, shapes: shapes)
 					end
 				end
 				
+				# Start recording object allocation metadata.
+				#
+				# Allocation tracing is process-global and can add significant overhead.
+				def allocation_trace_start
+					require "objspace"
+					
+					raise "Object allocation tracing was already started by this controller!" if @allocation_trace_active
+					raise "Object allocation tracing is already active!" if ObjectSpace.allocation_sourcefile(Object.new)
+					
+					ObjectSpace.trace_object_allocations_start
+					@allocation_trace_active = true
+					
+					return {started: true}
+				end
+				
+				# Stop recording allocations, dump the traced heap, and clear the metadata.
+				#
+				# @parameter path [String] File path where the heap dump should be written.
+				# @parameter shapes [Boolean] Whether to include Ruby shape-tree records.
+				def allocation_trace_stop(path:, shapes: true)
+					require "objspace"
+					stopped = false
+					
+					raise "Object allocation tracing was not started by this controller!" unless @allocation_trace_active
+					
+					ObjectSpace.trace_object_allocations_stop
+					stopped = true
+					@allocation_trace_active = false
+					
+					memory_dump(path: path, shapes: shapes)
+				ensure
+					ObjectSpace.trace_object_allocations_clear if stopped
+				end
+				
 				# Dump information about all running threads.
 				#
 				# Includes thread inspection and backtraces for debugging.
@@ -118,4 +153,3 @@ module Async
 		end
 	end
 end
-

data/readme.md

@@ -20,6 +20,8 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
   - [Memory Monitor](https://socketry.github.io/async-service-supervisor/guides/memory-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::MemoryMonitor</code> to detect and restart workers that exceed memory limits or develop memory leaks.
 
+  - [Memory Diagnostics](https://socketry.github.io/async-service-supervisor/guides/memory-diagnostics/index) - This guide explains how to capture Ruby heap dumps and garbage collection profiles from supervised workers, then use them to investigate memory growth.
+
   - [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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -157,6 +157,7 @@ files:
 - bake/async/service/supervisor.rb
 - context/getting-started.md
 - context/index.yaml
+- context/memory-diagnostics.md
 - context/memory-monitor.md
 - context/migration.md
 - context/process-monitor.md