memory-profiler 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9dc143b51ee61fd99bfbe646490321b4dc106981
-  data.tar.gz: 679e188284bee7611d02e3bdf79b19a2ba2902e7
+SHA256:
+  metadata.gz: 72517cae4d567a611d0fb3a2265ac2dd443fd3abae577ddbee0ec5e9b1d0f611
+  data.tar.gz: 003571cf8650a518d5a73ff0a30f4fba92ef0ee4572ff928ec261dce5fc6b2f0
 SHA512:
-  metadata.gz: 9ee3cde0472d1c96deb9d30ed7f180ceae46046000bb54f676f19179f5c185a1cc34ab0ce01cf497b3465c2603b03f5541632706d10cacd994a6212de3a943ba
-  data.tar.gz: 9002ee4f5c8d1444c833ddf25930918c9645af00f82859b839cd93a1301bc46d489b648bfd501649944d9d7494d88126c023f26e2b47e2dfc4b9f26d33b350fa
+  metadata.gz: 1920d0e7762f0ee1132555dea5aaab002a9afa9c14f9fda4e4ca763ab043b756b620b8379250e47c279f6a3d2e54de6720016cfb7e415ce30e561b89616b8911
+  data.tar.gz: d36826fb4449de4569357a71f4613dac7f0d5db5a5b39ea116980e65e27a95da7626c3cbf51eec1811eae92b214119c93c53c17fee2646ad9ed8462080ab9be5

data/context/getting-started.md

@@ -0,0 +1,229 @@
+# Getting Started
+
+This guide explains how to use `memory-profiler` to detect and diagnose memory leaks in Ruby applications.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add memory-profiler
+~~~
+
+## Core Concepts
+
+Memory leaks happen when your application creates objects that should be garbage collected but remain referenced indefinitely. Over time, this causes memory usage to grow unbounded, eventually leading to performance degradation or out-of-memory crashes.
+
+`memory-profiler` helps you find memory leaks by tracking object allocations in real-time:
+
+- **{ruby Memory::Profiler::Capture}** monitors allocations using Ruby's internal NEWOBJ/FREEOBJ events.
+- **{ruby Memory::Profiler::CallTree}** aggregates allocation call paths to identify leak sources.
+- **No heap enumeration** - uses O(1) counters updated automatically by the VM.
+
+## Usage
+
+### Monitor Memory Growth
+
+Start by identifying which classes are accumulating objects:
+
+~~~ ruby
+require 'memory/profiler'
+
+# Create a capture instance:
+capture = Memory::Profiler::Capture.new
+
+# Start tracking all object allocations:
+capture.start
+
+# Run your application code...
+run_your_app
+
+# Check live object counts for common classes:
+puts "Hashes: #{capture.count_for(Hash)}"
+puts "Arrays: #{capture.count_for(Array)}"
+puts "Strings: #{capture.count_for(String)}"
+
+capture.stop
+~~~
+
+**What this tells you**: Which object types are growing over time. If Hash count keeps increasing across multiple samples, you likely have a Hash leak.
+
+### Find the Leak Source
+
+Once you've identified a leaking class, use call path analysis to find WHERE allocations come from:
+
+~~~ ruby
+# Create a sampler with call path analysis:
+sampler = Memory::Profiler::Sampler.new(depth: 10)
+
+# Track the leaking class with analysis:
+sampler.track_with_analysis(Hash)
+sampler.start
+
+# Run code that triggers the leak:
+simulate_leak
+
+# Analyze where allocations come from:
+statistics = sampler.statistics(Hash)
+
+puts "Live objects: #{statistics[:live_count]}"
+puts "\nTop allocation sources:"
+statistics[:top_paths].first(5).each do |path_data|
+  puts "\n#{path_data[:count]} allocations from:"
+  path_data[:path].each { |frame| puts "  #{frame}" }
+end
+
+sampler.stop
+~~~
+
+**What this shows**: The complete call stacks that led to Hash allocations. Look for unexpected paths or paths that appear repeatedly.
+
+## Real-World Example
+
+Let's say you notice your app's memory growing over time. Here's how to diagnose it:
+
+~~~ ruby
+require 'memory/profiler'
+
+# Setup monitoring:
+capture = Memory::Profiler::Capture.new
+capture.start
+
+# Take baseline measurement:
+GC.start  # Clean up old objects first
+baseline = {
+  hashes: capture.count_for(Hash),
+  arrays: capture.count_for(Array),
+  strings: capture.count_for(String)
+}
+
+# Run your application for a period:
+# In production: sample periodically (every 60 seconds)
+# In development: run through typical workflows
+sleep 60
+
+# Check what grew:
+current = {
+  hashes: capture.count_for(Hash),
+  arrays: capture.count_for(Array),
+  strings: capture.count_for(String)
+}
+
+# Report growth:
+current.each do |type, count|
+  growth = count - baseline[type]
+  if growth > 100
+    puts "⚠️  #{type} grew by #{growth} objects"
+  end
+end
+
+capture.stop
+~~~
+
+If Hashes grew significantly, enable detailed tracking:
+
+~~~ ruby
+# Create detailed sampler:
+sampler = Memory::Profiler::Sampler.new(depth: 15)
+sampler.track_with_analysis(Hash)
+sampler.start
+
+# Run suspicious code path:
+process_user_requests(1000)
+
+# Find the culprits:
+statistics = sampler.statistics(Hash)
+statistics[:top_paths].first(3).each_with_index do |path_data, i|
+  puts "\n#{i+1}. #{path_data[:count]} Hash allocations:"
+  path_data[:path].first(5).each { |frame| puts "     #{frame}" }
+end
+
+sampler.stop
+~~~
+
+## Best Practices
+
+### When Tracking in Production
+
+1. **Start tracking AFTER startup**: Call `GC.start` before `capture.start` to avoid counting initialization objects
+2. **Use count-only mode for monitoring**: `capture.track(Hash)` (no callback) has minimal overhead
+3. **Enable analysis only when investigating**: Call path analysis has higher overhead
+4. **Sample periodically**: Take measurements every 60 seconds rather than continuously
+5. **Stop when done**: Always call `stop()` to remove event hooks
+
+### Performance Considerations
+
+**Count-only tracking** (no callback):
+- Minimal overhead (~5-10% on allocation hotpath)
+- Safe for production monitoring
+- Tracks all classes automatically
+
+**Call path analysis** (with callback):
+- Higher overhead (captures `caller_locations` on every allocation)  
+- Use during investigation, not continuous monitoring
+- Only track specific classes you're investigating
+
+### Avoiding False Positives
+
+Objects allocated before tracking starts but freed after will show as negative or zero:
+
+~~~ ruby
+# ❌ Wrong - counts existing objects:
+capture.start
+100.times { {} }
+GC.start  # Frees old + new objects → underflow
+
+# ✅ Right - clean slate first:
+GC.start  # Clear old objects
+capture.start
+100.times { {} }
+~~~
+
+## Common Scenarios
+
+### Detecting Cache Leaks
+
+~~~ ruby
+# Monitor your cache class:
+capture = Memory::Profiler::Capture.new
+capture.start
+
+cache_baseline = capture.count_for(CacheEntry)
+
+# Run for a period:
+sleep 300  # 5 minutes
+
+cache_current = capture.count_for(CacheEntry)
+
+if cache_current > cache_baseline * 2
+  puts "⚠️  Cache is leaking! #{cache_current - cache_baseline} entries added"
+  # Enable detailed tracking to find the source
+end
+~~~
+
+### Finding Retention in Request Processing
+
+~~~ ruby
+# Track during request processing:
+sampler = Memory::Profiler::Sampler.new
+sampler.track_with_analysis(Hash)
+sampler.start
+
+# Process requests:
+1000.times do
+  process_request
+end
+
+# Check if Hashes are being retained:
+statistics = sampler.statistics(Hash)
+
+if statistics[:live_count] > 1000
+  puts "Leaking #{statistics[:live_count]} Hashes per 1000 requests!"
+  statistics[:top_paths].first(3).each do |path_data|
+    puts "\n#{path_data[:count]}x from:"
+    puts path_data[:path].join("\n  ")
+  end
+end
+
+sampler.stop
+~~~

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Efficient memory allocation tracking with call path analysis.
+metadata:
+  documentation_uri: https://socketry.github.io/memory-profiler/
+  source_code_uri: https://github.com/socketry/memory-profiler
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `memory-profiler` to detect and diagnose
+    memory leaks in Ruby applications.

data/ext/extconf.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "mkmf"
+
+extension_name = "Memory_Profiler"
+
+append_cflags(["-Wall", "-Wno-unknown-pragmas", "-std=c99"])
+
+if ENV.key?("RUBY_DEBUG")
+	$stderr.puts "Enabling debug mode..."
+	
+	append_cflags(["-DRUBY_DEBUG", "-O0"])
+end
+
+$srcs = ["memory/profiler/profiler.c", "memory/profiler/capture.c"]
+$VPATH << "$(srcdir)/memory/profiler"
+
+# Check for required headers
+have_header("ruby/debug.h") or abort "ruby/debug.h is required"
+have_func("rb_ext_ractor_safe")
+
+if ENV.key?("RUBY_SANITIZE")
+	$stderr.puts "Enabling sanitizers..."
+	
+	# Add address and undefined behaviour sanitizers:
+	$CFLAGS << " -fsanitize=address -fsanitize=undefined -fno-omit-frame-pointer"
+	$LDFLAGS << " -fsanitize=address -fsanitize=undefined"
+end
+
+create_header
+
+# Generate the makefile to compile the native binary into `lib`:
+create_makefile(extension_name)