memory-profiler 1.0.3 → 1.1.0

data/lib/memory/profiler/call_tree.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Memory
+	module Profiler
+		# Efficient tree structure for tracking allocation call paths.
+		# Each node represents a frame in the call stack, with counts of how many
+		# allocations occurred at this point in the call path.
+		class CallTree
+			# Represents a node in the call tree.
+			#
+			# Each node tracks how many allocations occurred at a specific point in a call path.
+			# Nodes form a tree structure where each path from root to leaf represents a unique
+			# call stack that led to allocations.
+			#
+			# Nodes now track both total allocations and currently retained (live) allocations.
+			class Node
+				# Create a new call tree node.
+				#
+				# @parameter location [Thread::Backtrace::Location] The source location for this frame.
+				# @parameter parent [Node] The parent node in the tree.
+				def initialize(location = nil, parent = nil)
+					@location = location
+					@parent = parent
+					@total_count = 0      # Total allocations (never decrements)
+					@retained_count = 0   # Current live objects (decrements on free)
+					@children = nil
+				end
+				
+				# @attribute [Thread::Backtrace::Location] The location of the call.
+				attr_reader :location, :parent, :children
+				attr_accessor :total_count, :retained_count
+				
+				# Increment both total and retained counts up the entire path to root.
+				def increment_path!
+					current = self
+					while current
+						current.total_count += 1
+						current.retained_count += 1
+						current = current.parent
+					end
+				end
+				
+				# Decrement retained count up the entire path to root.
+				def decrement_path!
+					current = self
+					while current
+						current.retained_count -= 1
+						current = current.parent
+					end
+				end
+				
+				# Check if this node is a leaf (end of a call path).
+				#
+				# @returns [Boolean] True if this node has no children.
+				def leaf?
+					@children.nil?
+				end
+				
+				# Find or create a child node for the given location.
+				#
+				# @parameter location [Thread::Backtrace::Location] The frame location for the child node.
+				# @returns [Node] The child node for this location.
+				def find_or_create_child(location)
+					@children ||= {}
+					@children[location.to_s] ||= Node.new(location, self)
+				end
+				
+				# Iterate over child nodes.
+				#
+				# @yields {|child| ...} If a block is given, yields each child node.
+				def each_child(&block)
+					@children&.each_value(&block)
+				end
+				
+				# Enumerate all paths from this node to leaves with their counts
+				#
+				# @parameter prefix [Array] The path prefix (nodes traversed so far).
+				# @yields {|path, total_count, retained_count| ...} For each leaf path.
+				def each_path(prefix = [], &block)
+					current = prefix + [self]
+					
+					if leaf?
+						yield current, @total_count, @retained_count
+					end
+					
+					@children&.each_value do |child|
+						child.each_path(current, &block)
+					end
+				end
+			end
+			
+			# Create a new call tree for tracking allocation paths.
+			def initialize
+				@root = Node.new
+			end
+			
+			# Record an allocation with the given caller locations.
+			#
+			# @parameter caller_locations [Array<Thread::Backtrace::Location>] The call stack.
+			# @returns [Node] The leaf node representing this allocation path.
+			def record(caller_locations)
+				return nil if caller_locations.empty?
+				
+				current = @root
+				
+				# Build tree path from root to leaf:
+				caller_locations.each do |location|
+					current = current.find_or_create_child(location)
+				end
+				
+				# Increment counts for entire path (from leaf back to root):
+				current.increment_path!
+				
+				# Return leaf node for object tracking:
+				current
+			end
+			
+			# Get the top N call paths by allocation count.
+			#
+			# @parameter limit [Integer] Maximum number of paths to return.
+			# @parameter by [Symbol] Sort by :total or :retained count.
+			# @returns [Array<Array>] Array of [locations, total_count, retained_count].
+			def top_paths(limit = 10, by: :retained)
+				paths = []
+				
+				@root.each_path do |path, total_count, retained_count|
+					# Filter out root node (has nil location) and map to location strings
+					locations = path.select(&:location).map {|node| node.location.to_s}
+					paths << [locations, total_count, retained_count] unless locations.empty?
+				end
+				
+				# Sort by the requested metric (default: retained, since that's what matters for leaks)
+				sort_index = (by == :total) ? 1 : 2
+				paths.sort_by {|path_data| -path_data[sort_index]}.first(limit)
+			end
+			
+			# Get hotspot locations (individual frames with highest counts).
+			#
+			# @parameter limit [Integer] Maximum number of hotspots to return.
+			# @parameter by [Symbol] Sort by :total or :retained count.
+			# @returns [Hash] Map of location => [total_count, retained_count].
+			def hotspots(limit = 20, by: :retained)
+				frames = Hash.new {|h, k| h[k] = [0, 0]}
+				
+				collect_frames(@root, frames)
+				
+				# Sort by the requested metric
+				sort_index = (by == :total) ? 0 : 1
+				frames.sort_by {|_, counts| -counts[sort_index]}.first(limit).to_h
+			end
+			
+			# Total number of allocations tracked.
+			#
+			# @returns [Integer] Total allocation count.
+			def total_allocations
+				@root.total_count
+			end
+			
+			# Number of currently retained (live) allocations.
+			#
+			# @returns [Integer] Retained allocation count.
+			def retained_allocations
+				@root.retained_count
+			end
+			
+			# Clear all tracking data
+			def clear!
+				@root = Node.new
+			end
+			
+		private
+			
+			def collect_frames(node, frames)
+				# Skip root node (has no location)
+				if node.location
+					location_str = node.location.to_s
+					frames[location_str][0] += node.total_count
+					frames[location_str][1] += node.retained_count
+				end
+				
+				node.each_child {|child| collect_frames(child, frames)}
+			end
+		end
+	end
+end
+

data/lib/memory/profiler/capture.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "Memory_Profiler"

data/lib/memory/profiler/sampler.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "capture"
+require_relative "call_tree"
+
+module Memory
+	module Profiler
+		# Periodic sampler for monitoring memory growth over time.
+		#
+		# Samples class allocation counts at regular intervals and detects potential memory leaks
+		# by tracking when counts increase beyond a threshold. When a class exceeds the increases
+		# threshold, automatically enables detailed call path tracking for diagnosis.
+		class Sampler
+			# Tracks memory growth for a specific class.
+			#
+			# Records allocation counts over time and detects sustained growth patterns
+			# that indicate potential memory leaks.
+			class Sample
+				# Create a new sample profiler for a class.
+				#
+				# @parameter target [Class] The class being sampled.
+				# @parameter size [Integer] Initial object count.
+				# @parameter threshold [Integer] Minimum increase to consider significant.
+				def initialize(target, size = 0, threshold: 1000)
+					@target = target
+					@current_size = size
+					@maximum_observed_size = size
+					@threshold = threshold
+					
+					@sample_count = 0
+					@increases = 0
+				end
+				
+				attr_reader :target, :current_size, :maximum_observed_size, :threshold, :sample_count, :increases
+				
+				# Record a new sample measurement.
+				#
+				# @parameter size [Integer] Current object count for this class.
+				# @returns [Boolean] True if count increased significantly.
+				def sample!(size)
+					@sample_count += 1
+					@current_size = size
+					
+					# @maximum_observed_count ratchets up in units of at least @threshold counts.
+					# When it does, we bump @increases to track a potential memory leak.
+					if @maximum_observed_size
+						delta = @current_size - @maximum_observed_size
+						if delta > @threshold
+							@maximum_observed_size = size
+							@increases += 1
+							
+							return true
+						end
+					else
+						@maximum_observed_size = size
+					end
+					
+					return false
+				end
+				
+				# Convert sample data to JSON-compatible hash.
+				#
+				# @returns [Hash] Sample data as a hash.
+				def as_json(...)
+					{
+						target: @target.name || "(anonymous class)",
+						current_size: @current_size,
+						maximum_observed_size: @maximum_observed_size,
+						increases: @increases,
+						sample_count: @sample_count,
+						threshold: @threshold,
+					}
+				end
+				
+				# Convert sample data to JSON string.
+				#
+				# @returns [String] Sample data as JSON.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+			end
+			
+			attr_reader :depth
+			
+			# Create a new memory sampler.
+			#
+			# @parameter depth [Integer] Number of stack frames to capture for call path analysis.
+			# @parameter filter [Proc] Optional filter to exclude frames from call paths.
+			# @parameter increases_threshold [Integer] Number of increases before enabling detailed tracking.
+			def initialize(depth: 10, filter: nil, increases_threshold: 10)
+				@depth = depth
+				@filter = filter || default_filter
+				@increases_threshold = increases_threshold
+				@capture = Capture.new
+				@call_trees = {}
+				@samples = {}
+			end
+			
+			# Start capturing allocations.
+			def start
+				@capture.start
+			end
+			
+			# Stop capturing allocations.
+			def stop
+				@capture.stop
+			end
+			
+			# Run periodic sampling in a loop.
+			#
+			# Samples allocation counts at the specified interval and reports when
+			# classes show sustained memory growth. Automatically tracks ALL classes
+			# that allocate objects - no need to specify them upfront.
+			#
+			# @parameter interval [Numeric] Seconds between samples.
+			# @yields {|sample| ...} Called when a class shows significant growth.
+			def run(interval: 60, &block)
+				start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+				
+				while true
+					sample!(&block)
+					
+					now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+					delta = interval - (now - start_time)
+					sleep(delta) if delta > 0
+					start_time = now
+				end
+			end
+			
+			# Take a single sample of memory usage for all tracked classes.
+			#
+			# @yields {|sample| ...} Called when a class shows significant growth.
+			def sample!
+				@capture.each do |klass, allocations|
+					count = allocations.retained_count
+					sample = @samples[klass] ||= Sample.new(klass, count)
+					
+					if sample.sample!(count)
+						# Check if we should enable detailed tracking
+						if sample.increases >= @increases_threshold && !@call_trees.key?(klass)
+							track_with_analysis_internal(klass, allocations)
+						end
+						
+						# Notify about growth if block given
+						yield sample if block_given?
+					end
+				end
+			end
+			
+			# Internal: Enable tracking with analysis using allocations object
+			private def track_with_analysis_internal(klass, allocations)
+				tree = @call_trees[klass] = CallTree.new
+				depth = @depth
+				filter = @filter
+				
+				# Register callback on allocations object with new signature:
+				# - On :newobj - returns state (leaf node) which C extension stores
+				# - On :freeobj - receives state back from C extension
+				allocations.track do |klass, event, state|
+					case event
+					when :newobj
+						# Capture call stack and record in tree
+						locations = caller_locations(1, depth)
+						filtered = locations.select(&filter)
+						unless filtered.empty?
+							# Record returns the leaf node - return it so C can store it
+							tree.record(filtered)
+						end
+						# Return nil or the node - C will store whatever we return
+					when :freeobj
+						# Decrement using the state (leaf node) passed back from C
+						if state
+							state.decrement_path!
+						end
+					end
+				rescue Exception => error
+					warn "Error in track_with_analysis_internal: #{error.message}\n#{error.backtrace.join("\n")}"
+				end
+			end
+			
+			# Start tracking allocations for a class (count only).
+			def track(klass)
+				return if @capture.tracking?(klass)
+				
+				@capture.track(klass)
+			end
+			
+			# Start tracking with call path analysis.
+			#
+			# @parameter klass [Class] The class to track with detailed analysis.
+			def track_with_analysis(klass)
+				# Track the class if not already tracked
+				unless @capture.tracking?(klass)
+					@capture.track(klass)
+				end
+				
+				# Enable analysis by setting callback on the allocations object
+				@capture.each do |tracked_klass, allocations|
+					if tracked_klass == klass
+						track_with_analysis_internal(klass, allocations)
+						break
+					end
+				end
+			end
+			
+			# Stop tracking a specific class.
+			def untrack(klass)
+				@capture.untrack(klass)
+				@call_trees.delete(klass)
+			end
+			
+			# Check if a class is being tracked.
+			def tracking?(klass)
+				@capture.tracking?(klass)
+			end
+			
+			# Get live object count for a class.
+			def count(klass)
+				@capture.count_for(klass)
+			end
+			
+			# Get the call tree for a specific class.
+			def call_tree(klass)
+				@call_trees[klass]
+			end
+			
+			# Get allocation statistics for a tracked class.
+			#
+			# @parameter klass [Class] The class to get statistics for.
+			# @returns [Hash] Statistics including total, retained, paths, and hotspots.
+			def statistics(klass)
+				tree = @call_trees[klass]
+				return nil unless tree
+				
+				{
+					live_count: @capture.count_for(klass),
+					total_allocations: tree.total_allocations,
+					retained_allocations: tree.retained_allocations,
+					top_paths: tree.top_paths(10).map {|path, total, retained| 
+						{ path: path, total_count: total, retained_count: retained }
+					},
+					hotspots: tree.hotspots(20).transform_values {|total, retained|
+						{ total_count: total, retained_count: retained }
+					}
+				}
+			end
+			
+			# Get statistics for all tracked classes.
+			def all_statistics
+				@call_trees.keys.each_with_object({}) do |klass, result|
+					result[klass] = statistics(klass) if tracking?(klass)
+				end
+			end
+			
+			# Clear tracking data for a class.
+			def clear(klass)
+				tree = @call_trees[klass]
+				tree&.clear!
+			end
+			
+			# Clear all tracking data.
+			def clear_all!
+				@call_trees.each_value(&:clear!)
+				@capture.clear
+			end
+			
+			# Stop all tracking and clean up.
+			def stop!
+				@capture.stop
+				@call_trees.each_key do |klass|
+					@capture.untrack(klass)
+				end
+				@capture.clear
+				@call_trees.clear
+			end
+			
+			private
+			
+			def default_filter
+				->(location) {path = location.path
+																		!path.include?("/gems/") && 
+																							!path.include?("/ruby/") &&
+																							!path.start_with?("(eval)")
+				}
+			end
+		end
+	end
+end
+

data/lib/memory/profiler/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# @namespace
+module Memory
+	# @namespace
+	module Profiler
+		VERSION = "1.1.0"
+	end
+end
+

data/lib/memory/tracker.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "profiler/version"
+require_relative "profiler/call_tree"
+require_relative "profiler/capture"
+require_relative "profiler/sampler"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,45 @@
+# Memory::Profiler
+
+Efficient memory allocation tracking focused on **retained objects only**. Automatically tracks allocations and cleans up when objects are freed, giving you precise data on memory leaks.
+
+[![Development Status](https://github.com/socketry/memory-profiler/workflows/Test/badge.svg)](https://github.com/socketry/memory-profiler/actions?workflow=Test)
+
+## Features
+
+  - **Retained Objects Only**: Uses `RUBY_INTERNAL_EVENT_NEWOBJ` and `RUBY_INTERNAL_EVENT_FREEOBJ` to automatically track only objects that survive GC.
+  - **O(1) Live Counts**: Maintains per-class counters updated on alloc/free - no heap enumeration needed\!
+  - **Tree-Based Analysis**: Deduplicates common call paths using an efficient tree structure.
+  - **Native C Extension**: **Required** - uses Ruby internal events not available in pure Ruby.
+  - **Configurable Depth**: Control how deep to capture call stacks.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/memory-profiler/) for more details.
+
+  - [Getting Started](https://socketry.github.io/memory-profiler/guides/getting-started/index) - This guide explains how to use `memory-profiler` to detect and diagnose memory leaks in Ruby applications.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/memory-profiler/releases/index) for all releases.
+
+### v0.1.0
+
+  - Initial implementation.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial implementation.

data.tar.gz.sig

@@ -0,0 +1 @@
+Ps#(�����{L��+n]-Sd,�9�u"��@.��~�+"��<�S��ύ���v�{\��Wf�;V%UK�Ϗe����.v���Py�k���xcF �(zZb�e�Lnd-Z�����2�6V���:=��ܑM\�~Kp��wGQa���l�1�F*l�`��A/��j���r|���p�wD��0�n�_��H�{�7]���
�{^c�a�)}�9å�J����a@o&��oi�k��d�����&sI�t���k�i�U�R�-�,�X�3���R��勖8����#�s:�����I�QٟM�ݼ�3=զy8~I%����M�e�G�KH��iH�`�����=ZnV#��>�\엝�YCu����wOv#�f!�rgmz/�K�