memory-tracker-x 0.1.0

data/lib/memory/tracker/sampler.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "capture"
+require_relative "call_tree"
+
+module Memory
+	module Tracker
+		# 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 tracker 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
+				allocations.track do |obj_klass|
+					# Callback captures caller_locations with desired depth
+					locations = caller_locations(1, depth)
+					filtered = locations.select(&filter)
+					tree.record(filtered) unless filtered.empty?
+				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.
+			def statistics(klass)
+				tree = @call_trees[klass]
+				return nil unless tree
+				
+				{
+					live_count: @capture.count_for(klass),
+					total_allocations: tree.total_allocations,
+					top_paths: tree.top_paths(10).map {|path, count| 
+						{ path: path, count: count }
+					},
+					hotspots: tree.hotspots(20)
+				}
+			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/tracker/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 Tracker
+		VERSION = "0.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 "tracker/version"
+require_relative "tracker/call_tree"
+require_relative "tracker/capture"
+require_relative "tracker/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::Tracker
+
+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-tracker/workflows/Test/badge.svg)](https://github.com/socketry/memory-tracker/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-tracker/) for more details.
+
+  - [Getting Started](https://socketry.github.io/memory-tracker/guides/getting-started/index) - This guide explains how to use `memory-tracker` to detect and diagnose memory leaks in Ruby applications.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/memory-tracker/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.

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: memory-tracker-x
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions:
+- ext/extconf.rb
+extra_rdoc_files: []
+files:
+- context/getting-started.md
+- context/index.yaml
+- ext/extconf.rb
+- ext/memory/tracker/capture.c
+- ext/memory/tracker/capture.h
+- ext/memory/tracker/tracker.c
+- lib/memory/tracker.rb
+- lib/memory/tracker/call_tree.rb
+- lib/memory/tracker/capture.rb
+- lib/memory/tracker/sampler.rb
+- lib/memory/tracker/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/memory-tracker
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/memory-tracker/
+  source_code_uri: https://github.com/socketry/memory-tracker
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Efficient memory allocation tracking with call path analysis.
+test_files: []