h1. Ruby Minstrel
Minstrel allows you to wrap every method call for a given class so you can more easily observe how a class and its methods are being used.
h2. Get it
- gem install minstrel
- or download versions here: http://rubygems.org/gems/minstrel
- or github: https://github.com/jordansissel/ruby-minstrel
h2. Why?
Fun. Also, sometimes ruby-prof and similar tools are overkill when I am trying to debug or dig into how a piece of code works.
It's a lot like strace/tcpdump/dtrace for ruby, or aims to be, anyway.
I wanted a tool that was useful for my own code as well as for helping understand and debug other code (puppet, mcollective, rails, activerecord, sinatra, etc...).
h2. Examples
h3. From the commandline
You can use minstrel to wrap classes with a default 'print' wrapper that simply prints what is called. For example:
h3. The 'minstrel' tool
Since the following doesn't work as expected in ruby 1.8 (or maybe all rubies): ruby -rrubygems -rminstrel ..., I provide 'minstrel' as a way to run ruby programs with minstrel preloaded.
h4. Example: Tracing puppet storeconfigs (aka Tracing ActiveRecord queries)
ActiveRecord has a base class for most things query-related. Let's trace that:
So easy :)
h3. From ruby
Boilerplate:
Example:
Output:
h3. From ruby (deferred loading)
Sometimes you don't know when a class is going to be defined. To solve this, you must use Minstrel::Instrument#wrap_classname. For example:
Minstrel will wrap 'require' and check for classes you want wrapped at each require until it finds all the classes you asked to be wrapped.
h2. Caveats
Metaprogramming will not be often caught, necessarily, by minstrel, because they don't show usuall up as methods. However, the things invoking metaprogramming are usually methods so in most cases you'll get lucky enough to see what's going on.
Some cases of metaprogramming (dynamic method generation, DSLs, etc) can be caught if you call Minstrel::Instrument#wrap() late enough in the lifetime of the program that the dynamic methods have been created.
h2. Bugs?
If you find bugs, have feature suggestions, etc, feel free to open bugs here on github (https://github.com/jordansissel/ruby-minstrel/issues). I also read email: [email protected]