README.md in stack_tracy-0.1.3 vs README.md in stack_tracy-0.1.4
- old
+ new
@@ -8,11 +8,11 @@
The gem is partly written in C to reduce the application performance as minimal as possible.
-Watch ["**Using StackTracy within a small Sinatra application**"](https://vimeo.com/archan937/stacktracy) to see StackTracy in action!
+Watch the ["**Using StackTracy within a small Sinatra application**"](https://vimeo.com/archan937/stacktracy) **screencast** to see StackTracy in action!
## Installation
### Add `StackTracy` to your Gemfile
@@ -78,16 +78,19 @@
* `:exclude => ["Foo*", "FooBar"]` records everything except for `Foo`, `Foo::Bar`, `Foo::CandyBar` and `FooBar`
* `:only => "Foo* Kernel"` records `Foo`, `Foo::Bar`, `Foo::CandyBar` and `Kernel`
### Configure StackTracy
-You can configure the default stack tree reduction behaviour and dump directory of `StackTracy`:
+You can configure `StackTracy` regarding the default stack tree reduction behaviour, its dump directory and whether to include the source location when dumping recorded stack events:
StackTracy.configure do |c|
- c.dump_dir = "." #=> default: Dir::tmpdir
- c.only = "Foo*" #=> default: nil
- c.exclude = %w(Foo::Bar Foo::CandyBar) #=> default: nil
+ c.dump_dir = "." #=> default: Dir::tmpdir
+ c.dump_source_location = "." #=> default: false
+ c.limit = 1000 #=> default: 7500
+ c.threshold = 0.005 #=> default: 0.001
+ c.only = "Foo*" #=> default: nil
+ c.exclude = %w(Foo::Bar Foo::CandyBar) #=> default: nil
end
### Using recorded stack events
Once you have recorded stack events, you can call the following methods:
@@ -153,10 +156,18 @@
#### CSV sample file
This is what the contents of `result.csv` would look like:
+ event;;;singleton;object;method;nsec;call;depth;duration
+ c-call;;;false;Kernel;puts;1344466943040581120;Kernel#puts;0;0.000120832
+ c-call;;;false;IO;puts;1344466943040599040;IO#puts;1;9.1904e-05
+ c-call;;;false;IO;write;1344466943040613120;IO#write;2;3.2768e-05
+ c-call;;;false;IO;write;1344466943040658944;IO#write;2;1.9968e-05
+
+When invoking `StackTracy.dump "result.csv", true` and thus including the source location:
+
event;file;line;singleton;object;method;nsec;call;depth;duration
c-call;(pry);2;false;Kernel;puts;1344466943040581120;Kernel#puts;0;0.000120832
c-call;(pry);2;false;IO;puts;1344466943040599040;IO#puts;1;9.1904e-05
c-call;(pry);2;false;IO;write;1344466943040613120;IO#write;2;3.2768e-05
c-call;(pry);2;false;IO;write;1344466943040658944;IO#write;2;1.9968e-05
@@ -165,20 +176,36 @@
You can easily view the dumped stack events within your browser by either calling the following within Ruby:
[1] pry(main)> StackTracy.open "some/dir/file.csv"
-or the following within the Terminal:
-
- $ tracy "some/dir/file.csv"
-
Your default browser will be launched in which the stack events will be displayed.
-When passing no path, `tracy` will look for `stack_events-<random generated postfix>.csv` in either the default dump directory or in `Dir::tmpdir` and display it in the browser. When not found, it will display the last compiled stack tree when available:
+When passing no path, StackTracy will look for `stack_events-<random generated postfix>.csv` in either the default dump directory, the current directory or `Dir::tmpdir` and display it in the browser. When not found, it will display the last compiled stack tree when available:
$ tracy
+### Using the CLI (command line interface)
+
+Another way for viewing stack events in your browser is using the CLI `tracy` within the Terminal:
+
+ $ tracy #=> let StackTracy auto-determine which file to display
+ $ tracy . #=> display the last data file within the current directory
+ $ tracy foo/bar.csv #=> display foo/bar.csv
+
+To get info about its options, type `tracy help open`:
+
+ $ tracy help open
+ Usage:
+ tracy open [PATH]
+
+ Options:
+ -l, [--limit=LIMIT]
+ -t, [--threshold=THRESHOLD]
+
+ Display StackTracy data within the browser (PATH is optional)
+
### Kernel#stack_tracy
As already mentioned, there is a convenience method called `stack_tracy` convenience method. The following shows a couple variants with its equivalent "normal implementation".
#### Without passing an argument
@@ -266,30 +293,33 @@
Its equivalent:
[1] pry(main)> StackTracy.start
[2] pry(main)> puts "testing"
[3] pry(main)> StackTracy.stop
- [4] pry(main)> file = StackTracy.dump Dir::tmpdir
- [5] pry(main)> StackTracy.open file
+ [4] pry(main)> StackTracy.dump do |file|
+ [4] pry(main)> StackTracy.open file, true
+ [4] pry(main)> end
## Hooking into Sinatra requests
You can easily hook `StackTracy` into [Sinatra](http://www.sinatrarb.com) requests. This is a complete working example:
require "sinatra"
require "stack_tracy"
- use StackTracy::Sinatra
+ use StackTracy::Sinatra, :open
get "/" do
"Hello world!"
end
**Note**: Make sure you have the `sinatra` and `stack_tracy` gems installed.
-Open the Sinatra application in your browser at [http://localhost:4567](http://localhost:4567) and open [http://localhost:4567/tracy](http://localhost:4567/tracy) afterwards and the complete stack tree will be displayed in your browser! ^^
+Open the Sinatra application in your browser at [http://localhost:4567](http://localhost:4567) and the complete stack tree will be displayed in your browser! ^^
+You can also open [http://localhost:4567/tracy](http://localhost:4567/tracy) afterwards by the way.
+
### Taking more control
I can imagine that you don't want to hook into every Sinatra request. So you can pass a block which will be yielded before every request. The request will traced when it does **not** return either `false` or `nil`:
use StackTracy::Sinatra do |path, params|
@@ -352,9 +382,10 @@
## Credit
* Two functions within the StackTracy C implementation are taken from [ruby-prof](https://github.com/rdp/ruby-prof).
* The table sort within the Cumulatives tab is implemented with [TinySort](http://tinysort.sjeiti.com/).
+* Being able to improve browser performance when loading heavy HTML stack trace pages using Ravi Raj's ([@raviraj4u](https://twitter.com/raviraj4u)) blog post: [http://ravirajsblog.blogspot.nl/2010/12/another-hack-to-render-heavy-html-pages.html](http://ravirajsblog.blogspot.nl/2010/12/another-hack-to-render-heavy-html-pages.html)
## License
Copyright (c) 2012 Paul Engel, released under the MIT license
\ No newline at end of file