Backtrace (Stack traces) are essential information for debugging our applications. However, they only tell us what the program did, but don't tell us what it had (the arguments, local variables...etc.). So it's very often that we'd need to visit each call site, rerun the program, and try to print out the variables. To me, It's like the Google map's navigation only tells us the name of the roads, but not showing us the map along with them.
So I hope to solve this problem by adding some additional runtime info to the backtrace, and save us the work to manually look them up.
Please Don't Use It On Production
Add this line to your application's Gemfile:
gem 'power_trace', group: [:test, :development]
And then execute:
$ bundle install
Or install it yourself as:
$ gem install power_trace
If you call
power_trace directly, it'll return a
PowerTrace::Stack instance that contains all the processed traces. You can then use it in 3 different ways:
- Print it directly
- Access each trace (
- Convert it into backtraces (an array of strings)
Print It Directly
You can use
puts(power_trace) to print the beautiful output to stdout:
It should look just like the normal
puts(caller), just colorized and with more helpful info.
Access Individual Entries
Except for the call site, each entry also contains rich information about the runtime context. You can build your own debugging tool with that information easily.
Every entry has these attributes:
receiver- the receiver object
frame- the call frame (
locals- local variables in that frame
- the method call's arguments
- will be empty for
Convert It Into Backtraces
You can do it by calling
power_trace.to_backtrace. The major usage is to replace an exception object's backtrace like
I don't recommend using it like this for other purposes, though. Because by default, all entries will be color-encoded strings. Also, the embedded arguments/locals aren't easily parseable. For other uses, you should either print it directly or process the traces without calling
colorize- to decide whether to colorize each entry in their string format. Default is
power_tracetruncates every argument/local variable's value to avoid creating too much noise. Default is
By default, extra info sections (locals/arguments) are indented with
4 spaces. Like:
/Users/st0012/projects/power_trace/spec/fixtures.rb:23:in `forth_call' (Arguments) num1: 20 num2: 10
You can change this indentation with the
extra_info_indent: Int option. It's useful when you need to adjust the output from some formatting tools (like
Use It With StandardError (Experimental)
If you set
PowerTrace.replace_backtrace = true
it will replace every
StandardError exception's backtrace with the
power_trace.to_backtrace. So most of the error traces you see will also contain the colorized environment information!
This is still an experimental feature for now, as it has a very wide impact on all the libraries and your own code. Don't try this on production!!!!
power_trace Manually From A StandardError Exception
If you think the above feature is too aggressive. You can access an exception object's enhanced backtrace manually with the
begin perform_a_call rescue => e e.power_trace # <= like this end
This feature doesn't require any flag to enable, as the information is added as an extra field and doesn't override anything.
Use It With RSpec
You can also prettify RSpec's error messages with
power_trace, just use the below config:
PowerTrace.power_rspec_trace = true
Inspirations & Helpful Tools
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/st0012/power_trace. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the PowerTrace project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.