MethodTracer

MethodTracer is a tool for detecting lines in an application that call certain methods, somewhat akin to the syscall monitoring functionality of strace(1). The methods to be traced are specified by file pattern, which makes it simple to trace an entire gem¹. The most common use case is helping developers and testers focus their efforts when upgrading or changing gems in large applications.

¹ Designating traced methods by file lets you trace methods defined in the "namespace" of a different gem. For example, if a hypothetical gem activerecord-extension defines some methods on the class ActiveRecord, we still have the ability to trace only the methods from activerecord-extension without capturing the methods from activerecord.

Usage

To attach tracers to methods, instantiate MethodTracer::Tracer objects. For Rails applications, these can be placed in the provided initializer.

# Trace all methods defined by the system installation of gibbon:
MethodTracer::Tracer.new('/var/lib/gems/2.3.0/gems/gibbon-2.2.4/')

# Trace all methods defined by rbenv's 2.3.3 installation of activerecord:
MethodTracer::Tracer.new('/home/eddie/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/activerecord-5.0.7/')

With tracers attached, exercise as much of the application as possible. Perhaps run the comprehensive test suite that you of course have.

Configuration

MethodTracer supports the following configuration options:

MethodTracer::Config.app_path: The path of the application to trace calls from. MethodTracer will only report portions of call chains that are inside this path. Set it to Rails.application.paths.path.to_s for Rails applications. Set it to '/' or '' to report all calls.

MethodTracer::Config.output_file: A filename or IO or StringIO object where the report output should be sent. Defaults to $stdout.

Limitations

MethodTracer theoretically does not interfere with the original behavior of methods being traced. However, certain gems are known to misbehave when the tracing logic is monkeypatched in, and MethodTracer will refuse to trace those gems. Furthermore, any methods defined after the MethodTracer::Tracer is instantiated will remain untraced.

Installation

Add this line to your application's Gemfile:

gem 'method_tracer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install method_tracer

If you are using it with Rails, run the installation generator to install an example config initializer:

$ rails generate method_tracer:install

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/elebow/method_tracer.

License

This gem is dedicated to the public domain. In jurisdictions where this is not possible, this gem is licensed to all under the least restrictive terms possible, and the author waives all waivable copyright rights.