Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
121 lines (78 sloc) 3.52 KB
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.
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
crash.rb:2:in `go2'
crash.rb:7:in `go'
go2(a, 55)
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}
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
$ backtracer --help
More examples can be found here:
== Screencast ==
[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:
$ export RUBYOPT=-rbacktracer
$ export RUBYOPT=-rbacktracer_simple # or whichever one you want
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'
$ export RUBYOPT='-rfaster_rubygems -rbacktracer_simple'
== Other related projects ==
unroller,, liveconsole, ruby-debug (thanks guys!)
Comments welcome.