ruby_method_tracer 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 673fbc66c79fb1b2466d43fad6be1f738a8978630073283cda616b179beb8c8d
-  data.tar.gz: 92d557e3061f52f950747fd6a314c22facbd89ff3be790c223f71316ca50a69f
+  metadata.gz: e5fe5404bd1497820b14ca1e4bc041f778cfe9bc02402a4456329c88d0096206
+  data.tar.gz: cb08942010ab25a16a604d0edb973bd9f889e3c34ba2ae24ead8a0dcceed4ca8
 SHA512:
-  metadata.gz: cba38cde9f2ddf19a523abb9b1409832620ad9568b43dfb131bf0243119052134ec7b21e097fa8568d04801d32bf3918747844d87bbff54a4e06a39be3fecc74
-  data.tar.gz: c2f90be756be60ce89ba83348a38feb797922923bbe5434c2f421a492c890f3d51b8eff32b53506958fb554baafed58d7e15758803bbead740ef53b759390c0f
+  metadata.gz: f68e49cde1042577a5ed2f0054c263391070f29574d81bc58f6ec5db6f688f31411572372cce95eef010fbd6fc7cd981f38905cc01615eea914a680393af850a
+  data.tar.gz: 54b2ccc817924cd256dfdcfb66011acfa8641b76f66d2cb0ef59dab48e32f4d2bfa9d56d56d403f5bf60b53c627d784731984e0f61fc8ad01714576eba531620

data/CHANGELOG.md

@@ -1,6 +1,45 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-11-19
+
+### Added
+- **NEW: Hierarchical Call Tree Visualization** - `EnhancedTracer` class for tracking nested method calls
+- `CallTree` class for managing call hierarchy with parent-child relationships
+- `TreeFormatter` for beautiful tree visualization with proper indentation and tree characters
+- Statistics calculation: slowest methods, most called methods, max call depth
+- `print_tree()` method for outputting formatted call trees
+- `format_tree()` method for programmatic access to tree visualization
+- `fetch_enhanced_results()` for combined flat and hierarchical data
+- Thread-safe call stack management
+- Error tracking in call tree with full error messages
+- Color-coded tree output for better readability
+- 24 new comprehensive tests covering call tree functionality
+
+### Changed
+- Main module now auto-loads `EnhancedTracer` and formatting classes
+- README updated with call tree examples and usage guide
+- Documentation expanded with decision guide for choosing between SimpleTracer and EnhancedTracer
+
+## [0.2.0] - 2025-11-19
+
+### Added
+- Memory management with `max_calls` option (default: 1000) to prevent unbounded memory growth
+- `clear_results` public method to manually free stored trace data
+- Configurable logger via `logger` option for custom log destinations and formatting
+- Comprehensive test coverage for memory management and logger configuration
+
+### Fixed
+- Removed unnecessary `logger` gem dependency (now uses Ruby standard library)
+- Fixed gemspec URL casing inconsistencies for GitHub links
+
+### Changed
+- Default behavior now automatically limits stored calls to 1000 entries (oldest removed when exceeded)
+- Documentation updated with new configuration options and advanced usage examples
+
+## [0.1.1] - 2025-09-16
+
+- Bug fixes and improvements
+
 ## [0.1.0] - 2025-09-03
-## [0.1.0] - 2025-09-16
 
 - Initial release

data/README.md

@@ -7,40 +7,44 @@ RubyMethodTracer is a lightweight Ruby mixin for targeted method tracing. It wra
 ## Highlights
 - Wrap only the methods you care about; public, protected, and private methods are supported.
 - Records duration, success/error state, and timestamps with thread-safe storage.
+- **NEW: Hierarchical call tree visualization** to understand nested method calls and dependencies.
 - Configurable threshold to ignore fast calls and optional log streaming via `Logger`.
 - Zero dependencies beyond the Ruby standard library, keeping overhead minimal.
 
 ## Installation
 
-This project has not yet been published to RubyGems.
-
-Add it to your Gemfile directly from GitHub:
+Add this line to your application's Gemfile:
 
 ```ruby
-# Gemfile
-gem "ruby_method_tracer", github: "Seunadex/ruby_method_tracer"
+gem "ruby_method_tracer"
 ```
 
-Then install:
+And then execute:
 
 ```bash
 bundle install
 ```
 
+Or install it yourself as:
+
+```bash
+gem install ruby_method_tracer
+```
+
 For local development or experimentation:
 
 ```bash
 git clone https://github.com/Seunadex/ruby_method_tracer.git
-cd method_tracer
+cd ruby_method_tracer
 bundle exec rake install
 ```
 
 ## Usage
 
+### Example 1
 Include `RubyMethodTracer` in any class whose instance methods you want to observe. Register the target methods with optional settings.
 
 ```ruby
-require "ruby_method_tracer"
 
 class Worker
   include RubyMethodTracer
@@ -83,12 +87,165 @@ pp tracer.fetch_results
 #        { method_name: "Worker#perform", execution_time: 0.0063, status: :success, ... }
 #      ]
 #    }
+
+# Clear results when needed to free memory
+tracer.clear_results
 ```
 
-### Options
+### Example 2
+
+```ruby
+class OrderProcessor
+  include RubyMethodTracer
+
+  def process_order(order)
+    # ... perform work ...
+  end
+
+  trace_methods :process_order, auto_output: true
+end
+```
+
+### Example 3: Advanced Configuration
+
+```ruby
+# Use a custom logger to write traces to a file
+custom_logger = Logger.new('trace.log')
+custom_logger.level = Logger::INFO
+
+tracer = RubyMethodTracer::SimpleTracer.new(
+  MyService,
+  threshold: 0.01,           # Only record calls over 10ms
+  auto_output: true,         # Log each call
+  max_calls: 500,            # Keep only last 500 calls in memory
+  logger: custom_logger      # Use custom logger
+)
+tracer.trace_method(:expensive_operation)
+
+# Later, clear results to free memory
+tracer.clear_results
+```
+
+### Example 4: Call Tree Visualization (NEW!)
+
+Visualize hierarchical method call relationships with the `EnhancedTracer`:
+
+```ruby
+class OrderProcessor
+  def process_order(order)
+    validate_order(order)
+    charge_payment(order)
+    send_confirmation(order)
+  end
+
+  def validate_order(order)
+    check_inventory(order.items)
+  end
+
+  def charge_payment(order)
+    # Payment processing...
+  end
+
+  def send_confirmation(order)
+    # Email sending...
+  end
+
+  private
+
+  def check_inventory(items)
+    # Inventory check...
+  end
+end
+
+# Use EnhancedTracer for call tree tracking
+tracer = RubyMethodTracer::EnhancedTracer.new(OrderProcessor, threshold: 0.0)
+tracer.trace_method(:process_order)
+tracer.trace_method(:validate_order)
+tracer.trace_method(:charge_payment)
+tracer.trace_method(:send_confirmation)
+tracer.trace_method(:check_inventory)
+
+processor = OrderProcessor.new
+processor.process_order(order)
+
+# Print beautiful call tree visualization
+tracer.print_tree
+```
+
+This outputs a hierarchical tree showing nested calls:
+
+```
+METHOD CALL TREE
+============================================================
+└── OrderProcessor#process_order (125.3ms)
+    ├── OrderProcessor#validate_order (15.2ms)
+    │   └── OrderProcessor#check_inventory (12.1ms)
+    ├── OrderProcessor#charge_payment (85.4ms)
+    └── OrderProcessor#send_confirmation (24.7ms)
+============================================================
+
+STATISTICS
+------------------------------------------------------------
+Total Calls: 5
+Total Time: 250.6ms
+Unique Methods: 5
+Max Depth: 2
+
+Slowest Methods (by average time):
+  1. OrderProcessor#process_order - 125.3ms
+  2. OrderProcessor#charge_payment - 85.4ms
+  3. OrderProcessor#send_confirmation - 24.7ms
+  4. OrderProcessor#validate_order - 15.2ms
+  5. OrderProcessor#check_inventory - 12.1ms
+
+Most Called Methods:
+  1. OrderProcessor#process_order - 1 calls
+  2. OrderProcessor#validate_order - 1 calls
+  ...
+```
+
+**Call Tree Features:**
+- Shows parent-child relationships between methods
+- Visual tree structure with proper indentation
+- Execution times for each method call
+- Statistics summary (slowest methods, most called, max depth)
+- Error indicators with full error messages
+- Color-coded output for better readability
+
+
+### Options (SimpleTracer)
 
 - `threshold` (Float, default `0.001`): minimum duration (in seconds) to record.
 - `auto_output` (Boolean, default `false`): emit a log line using `Logger` for each recorded call.
+- `max_calls` (Integer, default `1000`): maximum number of calls to store in memory. When exceeded, the oldest calls are automatically removed to prevent memory leaks.
+- `logger` (Logger, default `Logger.new($stdout)`): custom logger instance for output. Useful for directing logs to files or custom log handlers.
+
+### Options (EnhancedTracer)
+
+EnhancedTracer supports all SimpleTracer options plus:
+
+- `track_hierarchy` (Boolean, default `true`): enable call tree tracking. Set to `false` to use EnhancedTracer like SimpleTracer.
+
+### API Methods (EnhancedTracer)
+
+- `print_tree(options = {})` - Print formatted call tree to stdout
+  - Options: `colorize: true/false`, `show_errors: true/false`
+- `format_tree(options = {})` - Get formatted call tree as string
+- `fetch_enhanced_results` - Get hash with `:flat_calls`, `:call_hierarchy`, and `:statistics`
+- `clear_results` - Clear both flat results and call tree
+
+## Choosing Between SimpleTracer and EnhancedTracer
+
+**Use SimpleTracer when:**
+- You only need flat timing data
+- You want minimal overhead
+- You're tracing independent methods
+
+**Use EnhancedTracer when:**
+- You need to understand call hierarchies
+- You want to visualize nested method calls
+- You're debugging complex call flows
+- You need statistics on method relationships
 
 ## Development
 

data/lib/ruby_method_tracer/simple_tracer.rb

@@ -12,6 +12,8 @@ module RubyMethodTracer
   # Options:
   # - :threshold (Float): Minimum duration in seconds to record; defaults to 0.001 (1ms).
   # - :auto_output (Boolean): When true, prints each call summary; defaults to false.
+  # - :max_calls (Integer): Maximum number of calls to store; defaults to 1000. When exceeded, oldest calls are removed.
+  # - :logger (Logger): Custom logger instance; defaults to Logger.new($stdout).
   #
   # Usage:
   #   tracer = RubyMethodTracer::SimpleTracer.new(MyClass, threshold: 0.005)
@@ -24,7 +26,7 @@ module RubyMethodTracer
       @calls = []
       @lock  = Mutex.new # Mutex to make writes to @calls thread safe.
       @wrapped_methods = Set.new
-      @logger = Logger.new($stdout)
+      @logger = @options[:logger] || Logger.new($stdout)
     end
 
     def trace_method(name)
@@ -56,7 +58,11 @@ module RubyMethodTracer
         timestamp: Time.now
       }
 
-      @lock.synchronize { @calls << call_details } # Thread safe append to shared results arrray.
+      @lock.synchronize do
+        @calls << call_details
+        # Enforce max_calls limit by removing oldest entries
+        @calls.shift if @calls.size > @options[:max_calls]
+      end
 
       output_call(call_details) if @options[:auto_output]
     end
@@ -72,12 +78,18 @@ module RubyMethodTracer
       }
     end
 
+    def clear_results
+      @lock.synchronize { @calls.clear }
+    end
+
     private
 
     def default_options
       {
         threshold: 0.001,
-        auto_output: false
+        auto_output: false,
+        max_calls: 1000,
+        logger: nil
       }
     end
 

data/lib/ruby_method_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyMethodTracer
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/ruby_method_tracer.rb

@@ -2,6 +2,10 @@
 
 require_relative "ruby_method_tracer/version"
 require_relative "ruby_method_tracer/simple_tracer"
+require_relative "ruby_method_tracer/call_tree"
+require_relative "ruby_method_tracer/enhanced_tracer"
+require_relative "ruby_method_tracer/formatters/base_formatter"
+require_relative "ruby_method_tracer/formatters/tree_formatter"
 
 # Public: Mixin that adds lightweight method tracing to classes.
 #

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ruby_method_tracer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Seun Adekunle
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-12 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: logger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.7.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.7.0
+date: 2025-11-19 00:00:00.000000000 Z
+dependencies: []
 description: A developer-friendly gem for tracing method calls, execution times, with
   minimal overhead.
 email:
@@ -43,14 +29,14 @@ files:
 - lib/ruby_method_tracer/simple_tracer.rb
 - lib/ruby_method_tracer/version.rb
 - sig/ruby_method_tracer.rbs
-homepage: https://github.com/seunadex/ruby_method_tracer
+homepage: https://github.com/Seunadex/ruby_method_tracer
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/Seunadex/ruby_method_tracer/blob/main/README.md
-  source_code_uri: https://github.com/seunadex/ruby_method_tracer
-  changelog_uri: https://github.com/seunadex/ruby_method_tracer/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/Seunadex/ruby_method_tracer
+  changelog_uri: https://github.com/Seunadex/ruby_method_tracer/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []