README.md in stack_tracy-0.1.4 vs README.md in stack_tracy-0.1.5

- old
+ new

@@ -33,35 +33,36 @@ [3] pry(main)> StackTracy.stop Or you can use the `stack_tracy` convenience method which records stack events within the passed block. [1] pry(main)> stack_tracy do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end ### Reducing recorded stack events -As StackTracy records every `call` and `return` event, the resulted stack tree can get immense huge. Fortunately, you can reduce the recorded stack events by passing options to `StackTracy.start` or `stack_tracy`. +As StackTracy records every `call` and `return` event, the resulted stack tree can get immense huge. Especially when dealing with complicated or extensive applications. If this is the case, I **really** recommend using following options which instructs StackTracy to reduce the recorded stack events. -They accept an options `Hash` with at least one of the following keys: +It accepts an options `Hash` with at least one of the following keys: -* `:only` - Matching events will be recorded +* `:only` - Only matching events will be recorded * `:exclude` - Matching events will be ignored The value can be either a String (optionally whitespace-delimited) or an array of strings containing `class` and/or `module` names. You can use the wildcard (`*`) for matching classes and/or modules within that namespace. #### Some examples You can pass options as follows: [1] pry(main)> StackTracy.start :only => ["Foo"] + [2] pry(main)> StackTracy.start :exclude => [:core] When using the convenience method: - [2] pry(main)> stack_tracy(:only => "Foo") { puts "testing" } - [3] pry(main)> stack_tracy(:dump, {:only => "Foo*"}) { puts "testing" } - [4] pry(main)> stack_tracy(:open, {:exclude => ["Array", "Hash"]}) { puts "testing" } + [3] pry(main)> stack_tracy(:only => "Foo") { puts "testing" } + [4] pry(main)> stack_tracy(:dump, {:only => "Foo*"}) { puts "testing" } + [5] pry(main)> stack_tracy(:open, {:exclude => ["Array", "Hash"]}) { puts "testing" } Let's say that you have the following code: class Foo class Bar; end @@ -75,24 +76,73 @@ * `:only => "Foo"` records `Foo` * `:only => "Foo*"` records `Foo`, `Foo::Bar` and `Foo::CandyBar` * `:only => "Foo*", :exclude => "Foo::Bar"` records `Foo` and `Foo::CandyBar` * `: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` +* `:exclude => :core` records everything except for Ruby core classes and modules (see [stack_tracy.rb](https://github.com/archan937/stack_tracy/blob/master/lib/stack_tracy.rb#L16) for more details) +### Add trace messages + +Sometimes you want to add marks to the stack tree in order to recognize certain events. You can do this by adding trace messages by using the `String#tracy` method: + + [1] pry(main)> stack_tracy(:print) do + [1] pry(main)* "Putting string".tracy + [1] pry(main)* puts "Hello world!" + [1] pry(main)* "Done putting string".tracy + [1] pry(main)* end + Hello world! + "Putting string" <0.000007> + Kernel#puts <0.000038> + IO#puts <0.000034> + IO#write <0.000017> + IO#write <0.000009> + "Done putting string" <0.000003> + => nil + +You can also encapsulate trace messages by executing code within a block: + + [1] pry(main)> stack_tracy(:print) do + [1] pry(main)* "Doing things".tracy do + [1] pry(main)* "" * 10 + [1] pry(main)* "Putting string".tracy do + [1] pry(main)* puts "Hello world!" + [1] pry(main)* end + [1] pry(main)* end + [1] pry(main)* end + Hello world! + "Doing things" <0.000057> + String#* <0.000003> + "Putting string" <0.000043> + Kernel#puts <0.000038> + IO#puts <0.000033> + IO#write <0.000017> + IO#write <0.000009> + => nil + ### Configure 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.dump_source_location = "." #=> default: false c.limit = 1000 #=> default: 7500 c.threshold = 0.005 #=> default: 0.001 + c.messages_only = true #=> default: false + c.slows_only = false #=> default: false c.only = "Foo*" #=> default: nil c.exclude = %w(Foo::Bar Foo::CandyBar) #=> default: nil end +As already mentioned, recorded stack traces can easily get very huge. So StackTracy will use the `:limit` and `:threshold` options when generating the HTML stack trace page (after having invoked `StackTracy.open`). + +When the amount of calls within the stack trace exceeds the specified `:limit`, StackTracy will automatically filter out Ruby core classes and modules calls and it will also apply the `:threshold` option. + +When applying the `:threshold`, calls with a duration **below** the `:threshold` will be folded at default within the stack tree which saves **a lot** of heavy browser rendering on page load as the 'child calls' will be rendered as comment. See [this commit](https://github.com/archan937/stack_tracy/commit/0bb49669015b44cd24715988bf9f7e4cf03a5dad) for more information. + +As of version v0.1.5, `StackTracy.open` (and thus the CLI) is provided with the options `:messages_only` and `:slows_only`. When having set `:messages_only` to `true`, the display stack tree will only include trace messages. If you have set `:slows_only` to `true`, then the stack tree will only include slow calls (duration > threshold) **and** trace messages. + ### Using recorded stack events Once you have recorded stack events, you can call the following methods: `StackTracy.stack_trace` - returns all recorded stack events (`array` of `StackTracy::EventInfo` instances) @@ -180,11 +230,11 @@ Your default browser will be launched in which the stack events will be displayed. 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 + [2] pry(main)> StackTracy.open ### Using the CLI (command line interface) Another way for viewing stack events in your browser is using the CLI `tracy` within the Terminal: @@ -197,12 +247,14 @@ $ tracy help open Usage: tracy open [PATH] Options: - -l, [--limit=LIMIT] - -t, [--threshold=THRESHOLD] + -l, [--limit=N] + -t, [--threshold=N] + -m, [--messages-only=MESSAGES_ONLY] + -s, [--slows-only=SLOWS_ONLY] Display StackTracy data within the browser (PATH is optional) ### Kernel#stack_tracy @@ -211,12 +263,12 @@ #### Without passing an argument Record stack events executed within a block: [1] pry(main)> stack_tracy do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" @@ -225,12 +277,12 @@ #### Passing `:print` Record stack events executed within a block and print the stack tree: [1] pry(main)> stack_tracy :print do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" @@ -240,12 +292,12 @@ #### Passing `:dump` Record stack events executed within a block and write the obtained data to `<default dump directory>/stack_events-<random generated postfix>.csv`: [1] pry(main)> stack_tracy :dump do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" @@ -255,12 +307,12 @@ #### Passing a target directory Record stack events executed within a block and write the obtained data to `<passed directory>/stack_events-<random generated postfix>.csv`: [1] pry(main)> stack_tracy Dir::tmpdir do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" @@ -270,12 +322,12 @@ #### Passing a CSV file path Record stack events executed within a block and write the obtained data to the passed file path: [1] pry(main)> stack_tracy "some/file.csv" do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" @@ -285,21 +337,21 @@ #### Passing `:open` Record stack events executed within a block and open the stack tree in your browser: [1] pry(main)> stack_tracy :open do - [1] pry(main)> puts "testing" - [1] pry(main)> end + [1] pry(main)* puts "testing" + [1] pry(main)* end Its equivalent: [1] pry(main)> StackTracy.start [2] pry(main)> puts "testing" [3] pry(main)> StackTracy.stop [4] pry(main)> StackTracy.dump do |file| - [4] pry(main)> StackTracy.open file, true - [4] pry(main)> end + [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: @@ -318,11 +370,11 @@ 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`: +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 only be traced when the block does **not** return either `false` or `nil`: use StackTracy::Sinatra do |path, params| path == "/" #=> only trace "http://localhost:4567" end @@ -345,11 +397,11 @@ The StackTracy repo is provided with `script/console` which you can use for development / testing purposes. Run the following command in your console: $ script/console - Loading development environment (StackTracy 0.1.0) + Loading development environment (StackTracy 0.1.5) [1] pry(main)> stack_tracy :print do [1] pry(main)* puts "testing" [1] pry(main)* end testing Kernel#puts <0.000121> @@ -363,10 +415,10 @@ Run the following command for testing: $ rake -You can also run a single test: +You can also run a single test file: $ ruby test/unit/test_tracy.rb ## TODO \ No newline at end of file