async-container-supervisor 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad71770c6717fe41a49b28a2f4614e7f539d572332805e44cc8f857d0c6cc404
-  data.tar.gz: 2f2ed9f22cce34b84f85c132f87b5c3296b539530ea26d0127a24dacdc4b5aac
+  metadata.gz: a2da6a39261568dcfdcd067bcbd7364397df19aad34826ec9d7b6745e74aa198
+  data.tar.gz: b8510b8f17ac2fea393f12223604c96a8f9303d6e87b1fc2ac54fc6b0cdfdaeb
 SHA512:
-  metadata.gz: 360ca6f0fe692937d47579307d9abd59f4879ce4eef88d927b32441eb71f40ac827ea63bc66e2c45b9b489072385de13f49c2bfb2698ab0ff878853d6a34d768
-  data.tar.gz: 8c655ae5432df6b742660ca02251b8f7d25ca2b8a2937aa59d66cf485b562e7abc9f1bd7154cdded585f0e773de40dc9c1bb93871871a56f8cda5288ae61fc60
+  metadata.gz: bf79321c826f009edac43b3c1bf1313710ed6881863aa56dea8c7909c7c231cbb1e07b92b0ed2241f1f76cd137e934ec17fb0b6ed00b30ebe8778c430c61735c
+  data.tar.gz: c469d508ec02830abe705ec935b6778b45f78923ed592e9af652f07189ad1929e2c61be389bed2ab2076697e7349398e199a43dd238b486e6ebbc899e4b5f9f7

data/bake/async/container/supervisor.rb

@@ -29,6 +29,25 @@ def status
 	end
 end
 
+# Sample memory allocations from a worker over a time period.
+#
+# This is useful for identifying memory leaks by tracking allocations
+# that are retained after garbage collection.
+#
+# @parameter duration [Integer] The duration in seconds to sample for (default: 10).
+# @parameter connection_id [String] The connection ID to target a specific worker.
+def memory_sample(duration: 10, connection_id:)
+	client do |connection|
+		Console.info(self, "Sampling memory from worker...", duration: duration, connection_id: connection_id)
+		
+		# Build the operation request:
+		operation = {do: :memory_sample, duration: duration}
+		
+		# Use the forward operation to proxy the request to a worker:
+		return connection.call(do: :forward, operation: operation, connection_id: connection_id)
+	end
+end
+
 private
 
 def endpoint

data/context/getting-started.md

@@ -139,13 +139,46 @@ The {ruby Async::Container::Supervisor::MemoryMonitor} will periodically check w
 
 The supervisor can collect various diagnostics from workers on demand:
 
-- **Memory dumps**: Full heap dumps for memory analysis
-- **Thread dumps**: Stack traces of all threads
+- **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
 
 These can be triggered programmatically or via command-line tools (when available).
 
+#### 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:**
+
+```bash
+# Sample for 30 seconds and print report to console
+$ bake async:container:supervisor:memory_sample duration=30
+```
+
+**Programmatically:**
+
+```ruby
+# Assuming you have a connection to a worker:
+result = connection.call(do: :memory_sample, duration: 30)
+puts result[:data]
+```
+
+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.
+
 ## Advanced Usage
 
 ### Custom Monitors

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

@@ -45,7 +45,7 @@ module Async
 				
 				# Run the client in a loop, reconnecting if necessary.
 				def run
-					Async do
+					Async(annotation: "Supervisor Client", transient: true) do
 						loop do
 							connection = connect!
 							

data/lib/async/container/supervisor/connection.rb

@@ -71,6 +71,27 @@ module Async
 						@queue.closed?
 					end
 					
+					# Forward this call to another connection, proxying all responses back.
+					#
+					# This provides true streaming forwarding - intermediate responses flow through
+					# in real-time rather than being buffered.
+					#
+					# @parameter target_connection [Connection] The connection to forward the call to.
+					# @parameter operation [Hash] The operation request to forward (must include :do key).
+					def forward(target_connection, operation)
+						# Forward the operation in an async task to avoid blocking
+						Async do
+							# Make the call to the target connection and stream responses back:
+							Call.call(target_connection, **operation) do |response|
+								# Push each response through our queue:
+								self.push(**response)
+							end
+						ensure
+							# Close our queue to signal completion:
+							@queue.close
+						end
+					end
+					
 					def self.dispatch(connection, target, id, message)
 						Async do
 							call = self.new(connection, id, message)

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

@@ -10,15 +10,19 @@ module Async
 	module Container
 		module Supervisor
 			class MemoryMonitor
+				MEMORY_SAMPLE = {duration: 60, timeout: 60+20}
+				
 				# Create a new memory monitor.
 				#
 				# @parameter interval [Integer] The interval at which to check for memory leaks.
 				# @parameter total_size_limit [Integer] The total size limit of all processes, or nil for no limit.
 				# @parameter options [Hash] Options to pass to the cluster when adding processes.
-				def initialize(interval: 10, total_size_limit: nil, **options)
+				def initialize(interval: 10, total_size_limit: nil, memory_sample: MEMORY_SAMPLE, **options)
 					@interval = interval
 					@cluster = Memory::Leak::Cluster.new(total_size_limit: total_size_limit)
 					
+					@memory_sample = memory_sample
+					
 					# We use these options when adding processes to the cluster:
 					@options = options
 					
@@ -74,6 +78,23 @@ module Async
 				# @parameter monitor [Memory::Leak::Monitor] The monitor that detected the memory leak.
 				# @returns [Boolean] True if the process was killed.
 				def memory_leak_detected(process_id, monitor)
+					Console.info(self, "Memory leak detected!", child: {process_id: process_id}, monitor: monitor)
+					
+					if @memory_sample
+						Console.info(self, "Capturing memory sample...", child: {process_id: process_id}, memory_sample: @memory_sample)
+
+						# We are tracking multiple connections to the same process:
+						connections = @processes[process_id]
+						
+						# Try to capture a memory sample:
+						connections.each do |connection|
+							result = connection.call(do: :memory_sample, **@memory_sample)
+							
+							Console.info(self, "Memory sample completed:", child: {process_id: process_id}, result: result)
+						end
+					end
+					
+					# Kill the process gently:
 					Console.info(self, "Killing process!", child: {process_id: process_id})
 					Process.kill(:INT, process_id)
 					

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

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
+require "securerandom"
+
 require_relative "connection"
 require_relative "endpoint"
 require_relative "dispatchable"
@@ -17,15 +19,23 @@ module Async
 				def initialize(monitors: [], endpoint: Supervisor.endpoint)
 					@monitors = monitors
 					@endpoint = endpoint
+					
+					@connections = {}
 				end
 				
 				attr :monitors
+				attr :connections
 				
 				include Dispatchable
 				
 				def do_register(call)
 					call.connection.state.merge!(call.message[:state])
 					
+					connection_id = SecureRandom.uuid
+					call.connection.state[:connection_id] = connection_id
+					
+					@connections[connection_id] = call.connection
+					
 					@monitors.each do |monitor|
 						monitor.register(call.connection)
 					rescue => error
@@ -35,6 +45,31 @@ module Async
 					call.finish
 				end
 				
+				# Forward an operation to a worker connection.
+				#
+				# @parameter call [Connection::Call] The call to handle.
+				# @parameter operation [Hash] The operation to forward, must include :do key.
+				# @parameter connection_id [String] The connection ID to target.
+				def do_forward(call)
+					operation = call[:operation]
+					connection_id = call[:connection_id]
+					
+					unless connection_id
+						call.fail(error: "Missing 'connection_id' parameter")
+						return
+					end
+					
+					connection = @connections[connection_id]
+					
+					unless connection
+						call.fail(error: "Connection not found", connection_id: connection_id)
+						return
+					end
+					
+					# Forward the call to the target connection
+					call.forward(connection, operation)
+				end
+				
 				# Restart the current process group, usually including the supervisor and any other processes.
 				#
 				# @parameter signal [Symbol] The signal to send to the process group.
@@ -48,14 +83,26 @@ module Async
 				end
 				
 				def do_status(call)
+					connections = @connections.map do |connection_id, connection|
+						{
+							connection_id: connection_id,
+							process_id: connection.state[:process_id],
+							state: connection.state,
+						}
+					end
+					
 					@monitors.each do |monitor|
 						monitor.status(call)
 					end
 					
-					call.finish
+					call.finish(connections: connections)
 				end
 				
 				def remove(connection)
+					if connection_id = connection.state[:connection_id]
+						@connections.delete(connection_id)
+					end
+					
 					@monitors.each do |monitor|
 						monitor.remove(connection)
 					rescue => error

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

@@ -6,7 +6,7 @@
 module Async
 	module Container
 		module Supervisor
-			VERSION = "0.6.3"
+			VERSION = "0.7.0"
 		end
 	end
 end

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

@@ -53,6 +53,44 @@ module Async
 					end
 				end
 				
+				# Sample memory allocations over a time period to identify potential leaks.
+				#
+				# This method is much lighter weight than {do_memory_dump} and focuses on
+				# retained objects allocated during the sampling period. Late-lifecycle
+				# allocations that are retained are likely memory leaks.
+				#
+				# @parameter call [Connection::Call] The call to respond to.
+				# @parameter duration [Numeric] The duration in seconds to sample for (default: 10).
+				def do_memory_sample(call)
+					require "memory"
+					
+					unless duration = call[:duration] and duration.positive?
+						raise ArgumentError, "Positive duration is required!"
+					end
+					
+					Console.info(self, "Starting memory sampling...", duration: duration)
+					
+					# Create a sampler to track allocations
+					sampler = Memory::Sampler.new
+					
+					# Start sampling
+					sampler.start
+					
+					# Sample for the specified duration
+					sleep(duration)
+					
+					# Stop sampling
+					sampler.stop
+					
+					Console.info(self, "Memory sampling completed, generating report...", sampler: sampler)
+					
+					# Generate a report focused on retained objects (likely leaks):
+					report = sampler.report
+					call.finish(report: report.as_json)
+				ensure
+					GC.start
+				end
+				
 				def do_thread_dump(call)
 					dump(call) do |file|
 						Thread.list.each do |thread|
@@ -68,11 +106,11 @@ module Async
 				end
 				
 				def do_garbage_profile_stop(call)
-					GC::Profiler.disable
-					
 					dump(connection, message) do |file|
 						file.puts GC::Profiler.result
 					end
+				ensure
+					GC::Profiler.disable
 				end
 				
 				protected def connected!(connection)

data/readme.md

@@ -22,6 +22,14 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
 Please see the [project releases](https://socketry.github.io/async-container-supervisor/releases/index) for all releases.
 
+### v0.7.0
+
+  - If a memory leak is detected, sample memory usage for 60 seconds before exiting.
+
+### v0.6.4
+
+  - Make client task (in supervised worker) transient, so that it doesn't keep the reactor alive unnecessarily. It also won't be stopped by default when SIGINT is received, so that the worker will remain connected to the supervisor until the worker is completely terminated.
+
 ### v0.6.3
 
   - Add agent context documentation.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.7.0
+
+  - If a memory leak is detected, sample memory usage for 60 seconds before exiting.
+
+## v0.6.4
+
+  - Make client task (in supervised worker) transient, so that it doesn't keep the reactor alive unnecessarily. It also won't be stopped by default when SIGINT is received, so that the worker will remain connected to the supervisor until the worker is completely terminated.
+
 ## v0.6.3
 
   - Add agent context documentation.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: memory
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: memory-leak
   requirement: !ruby/object:Gem::Requirement