RubyMethodTracer is a lightweight Ruby mixin for targeted method tracing. It wraps instance methods, measures wall-clock runtime, flags errors, and can stream results to your logger without pulling in a full APM agent. Use it to surface slow paths in production or gather quick instrumentation while debugging.

• 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.

Add this line to your application's Gemfile:

gem "ruby_method_tracer"

And then execute:

bundle install

Or install it yourself as:

gem install ruby_method_tracer

For local development or experimentation:

git clone https://github.com/Seunadex/ruby_method_tracer.git
cd ruby_method_tracer
bundle exec rake install

Include RubyMethodTracer in any class whose instance methods you want to observe. Register the target methods with optional settings.

class Worker
  include RubyMethodTracer

  def perform(user_id)
    expensive_call(user_id)
  end

  private

  def expensive_call(id)
    # work...
  end
end

Worker.trace_methods(:perform, threshold: 0.005, auto_output: true)

Worker.new.perform(42)

With auto_output: true, each invocation prints a colorized summary:

TRACE: Worker#perform [OK] took 6.3ms

To inspect trace results programmatically, manage the tracer yourself:

tracer = RubyMethodTracer::SimpleTracer.new(Worker, threshold: 0.002)
tracer.trace_method(:perform)

Worker.new.perform(42)

pp tracer.fetch_results
# => {
#      total_calls: 1,
#      total_time: 0.0063,
#      calls: [
#        { method_name: "Worker#perform", execution_time: 0.0063, status: :success, ... }
#      ]
#    }

# Clear results when needed to free memory
tracer.clear_results

class OrderProcessor
  include RubyMethodTracer

  def process_order(order)
    # ... perform work ...
  end

  trace_methods :process_order, auto_output: true
end

# 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

Visualize hierarchical method call relationships with the EnhancedTracer:

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

• 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.

EnhancedTracer supports all SimpleTracer options plus:

• track_hierarchy (Boolean, default true): enable call tree tracking. Set to false to use EnhancedTracer like SimpleTracer.

• 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

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

After checking out the repo, run bin/setup to install dependencies. Then run rake spec to execute the test suite. You can also run bin/console for an interactive prompt.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version in lib/ruby_method_tracer/version.rb, and then run bundle exec rake release.

This project uses SimpleCov for code coverage analysis. Coverage reports are automatically generated when running tests:

bundle exec rspec

After running the tests, open coverage/index.html in your browser to view the detailed coverage report. The project maintains a minimum coverage threshold of 95% line coverage and 80% branch coverage.

Bug reports and pull requests are welcome on GitHub at https://github.com/Seunadex/ruby_method_tracer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License. See LICENSE.txt for details.

Everyone interacting in the RubyMethodTracer project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.