backtracer: gem to output higher quality backtraces if an unhandled exception occurs.  


If you've ever seen 
...24 levels... 
and disliked it, this is the gem for you.

If you've ever wished the exception trace would display the code of each line (a la Python), then this gem is for you.

It displays the full back trace (no ...'s), along with the code from each line!  It can even display local variables at each level of the call stack, if desired.

Examples:

a script that once output:
$ ruby crash.rb
crash.rb:2:in `go2': unhandled exception
        from crash.rb:6:in `go'
        from crash.rb:9

Now outputs:

$ backtracer crash.rb

   RuntimeError
crash.rb:2:in `go2'
        raise
crash.rb:7:in `go'
        go2(a, 55)
crash.rb:10
        go '3'


(Now has the code lines, and if there had been ...'s, would have ovecome them).

or use the --locals option

$ backtracer --locals crash.rb

unhandled exception: crash.rb:2:   raise
        locals: {"a"=>"3", "b"=>55}
          from:
        crash.rb:1 go2(a=>3, b=>55)
                locals: {"a"=>"3", "b"=>55}
        crash.rb:5 go(a=>3)
                locals: {"a"=>"3"}

(displays locals, parameters as current value)

Also included are several other options.  One is --ping, which periodically dumps current threads' backtrace(s) (quite useful for profiling to see where you code is spending a lot of its time (thanks xray gem!)).  There is also an option that will print out thread dumps whenever you hit ctrl+c.

To see all possible backtrace options run
$ backtracer -h
or
$ backtracer --help

More examples can be found here:

http://github.com/rdp/backtracer/blob/master/examples/example_test_all_output
http://github.com/rdp/backtracer/blob/master/examples/example_test_large_output
http://github.com/rdp/backtracer/blob/master/examples/pinger_example

== Screencast == 

http://www.rubypulse.com/episode-0.18_backtracer.html
[thanks aaalex!]

== Installation ==

== 1.8.x ==

$ gem install ruby-debug # only necessary for the --locals option
$ gem install jeweler && jeweler tumble # if necessary
$ gem install backtracer

now run like

$ backtracer script_name.rb
$ backtracer --locals script_name.rb arg1 arg2

== 1.9.1 ==

$ gem install ruby-debug19 # only necessary for the --locals option
$ gem install jeweler && jeweler tumble # if necessary
$ gem install backtracer

run as above (backtracer executable), or as a ruby require:
$ ruby -rbacktracer script_name
$ ruby -rbacktracer_locals script_name

== Other ==

Note that you can load backtracing capability within a script itself by:

require 'backtracer'

which will cause it to output a coded backtrace at exit time, if an unhandled exception occurs.  Backtracer default and backtracer_simple don't cause runtime slowdown, so sometimes you just want to add this by default.  If so, then add it to your RUBYOPT variable.  (Once I did this, I wondered why I would ever want anything else).  Here's how:

1.9:

$ export RUBYOPT=-rbacktracer
or
$ export RUBYOPT=-rbacktracer_simple # or whichever one you want

1.8:

you'll need to install a helper gem since rubygems can't load both itself and a gem on the command line for some reason.

$ sudo gem install faster_rubygems # the helper--installs faster_rubygems.rb and some other files to your site_ruby dir
$ export RUBYOPT='-rfaster_rubygems -rbacktracer'
or
$ export RUBYOPT='-rfaster_rubygems -rbacktracer_simple'

Enjoy.

== Other related projects ==

unroller, http://eigenclass.org/hiki/method+arguments+via+introspection, liveconsole, ruby-debug (thanks guys!)

Comments welcome.

http://github.com/rdp/backtracer