backtracer: ruby gem to output higher quality backtraces if an unhandled exception is thrown.  


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

It displays the full back trace, with or without code and/or local variables, etc.

There are several options available.

example:

a script that used to output:

>ruby crash.rb
crash.rb:2:in `go2': unhandled exception
        from crash.rb:6:in `go'
        from crash.rb:9

Now outputs:
>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"}
or
>backtracer crash.rb
====
crash.rb:2:in `go2'
        raise
crash.rb:7:in `go'
        go2(a, 55)
crash.rb:10
        go '3'
====
crash.rb:2:in `go2': unhandled exception
        from crash.rb:7:in `go'
        from crash.rb:10

Also included is a --ping option which periodically dumps the current running threads' backtrace(s)--quite useful for figuring out where you code is spending a lot of its time.

To see all possible options run
$ backtracer -h

== Installation ==

== 1.8.x ==

$ gem install ruby-debug
$ gem sources add http://gemcutter.org # if necessary
$ gem install backtracer

now run like
$ backtracer script_name
$ backtracer --locals script_name

== 1.9.1 ==

$ gem install ruby-debug19 # if you want some of the more exotic backtraces
$ gem sources add http://gemcutter.org # if necessary
$ gem install backtracer

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

== Descriptions ==

Try out the options:
create a file like

  def go(a)
   raise
  end
  go(3)

then run backtracer against it.

== Other ==

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

require 'backtracer'

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.

You can also add it to your RUBYOPT variable if you always want it to run against all scripts (backtracer_simple and backtracer don't cause any slowdowns).
Here's how:
1.9:

$ export RUBYOPT=-rbacktracer

1.8.7:
you'll need to install a helper loader since gems can't load 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
$ export RUBYOPT='-rfaster_rubygems -rbacktracer'

Enjoy.

== Related projects ==
unroller, http://eigenclass.org/hiki/method+arguments+via+introspection, liveconsole, ruby-debug

Comments welcome 
rdp on github.

http://github.com/rdp/backtracer