README.md in stackprof-0.2.11 vs README.md in stackprof-0.2.12
- old
+ new
@@ -1,26 +1,30 @@
-## stackprof
+# Stackprof
-a sampling call-stack profiler for ruby 2.1+
+A sampling call-stack profiler for Ruby.
-inspired heavily by [gperftools](https://code.google.com/p/gperftools/),
-and written as a replacement for [perftools.rb](https://github.com/tmm1/perftools.rb)
+Inspired heavily by [gperftools](https://code.google.com/p/gperftools/), and written as a replacement for [perftools.rb](https://github.com/tmm1/perftools.rb).
-### getting started
+## Requirements
-#### Install
+* Ruby 2.1+
+* Linux-based OS
+## Getting Started
+
+### Install
+
In your Gemfile add:
```ruby
gem 'stackprof'
```
Then run `$ bundle install`. Alternatively you can run `$ gem install stackprof`.
-#### Run
+### Run
in ruby:
``` ruby
StackProf.run(mode: :cpu, out: 'tmp/stackprof-cpu-myapp.dump') do
@@ -91,11 +95,11 @@
The `--flamegraph-viewer` command will output the exact shell command you need to run to open the `tmp/flamegraph` you generated with the built in stackprof flamegraph viewer:
-### sampling
+## Sampling
four sampling modes are supported:
- :wall (using `ITIMER_REAL` and `SIGALRM`)
- :cpu (using `ITIMER_PROF` and `SIGPROF`) [default mode]
@@ -140,11 +144,11 @@
callstacks in allocation mode.
- in allocation mode, samples are taken via `rb_tracepoint_new(RUBY_INTERNAL_EVENT_NEWOBJ)`,
which provides a notification every time the VM allocates a new object.
-### Aggregation
+## Aggregation
each sample consists of N stack frames, where a frame looks something like `MyClass#method` or `block in MySingleton.method`.
for each of these frames in the sample, the profiler collects a few pieces of metadata:
- samples: number of samples where this was the topmost frame
@@ -173,18 +177,18 @@
this technique builds up an incremental callgraph from the samples. on any given frame,
the sum of the outbound edge weights is equal to total samples collected on that frame
(`frame.total_samples == frame.edges.values.sum`).
-### reporting
+## Reporting
multiple reporting modes are supported:
- text
- dotgraph
- source annotation
-#### `StackProf::Report.new(data).print_text`
+### `StackProf::Report.new(data).print_text`
```
TOTAL (pct) SAMPLES (pct) FRAME
91 (48.4%) 91 (48.4%) A#pow
58 (30.9%) 58 (30.9%) A.newobj
@@ -195,11 +199,11 @@
188 (100.0%) 0 (0.0%) <main>
188 (100.0%) 0 (0.0%) block in <main>
188 (100.0%) 0 (0.0%) <main>
```
-#### `StackProf::Report.new(data).print_graphviz`
+### `StackProf::Report.new(data).print_graphviz`
```
digraph profile {
@@ -221,11 +225,11 @@
70346498325080 [size=10.0] [fontsize=10.0] [shape=box] [label="<main>\n0 (0.0%)\rof 188 (100.0%)\r"];
70346498325080 -> 70346498324300 [label="188"];
}
```
-#### `StackProf::Report.new(data).print_method(/pow|newobj|math/)`
+### `StackProf::Report.new(data).print_method(/pow|newobj|math/)`
```
A#pow (/Users/tmm1/code/stackprof/sample.rb:11)
| 11 | def pow
91 (48.4% / 100.0%) | 12 | 2 ** 100
@@ -243,11 +247,11 @@
| 21 | 2.times do
34 (18.1% / 100.0%) | 22 | 2 + 3 * 4 ^ 5 / 6
| 23 | end
```
-### usage
+## Usage
the profiler is compiled as a C-extension and exposes a simple api: `StackProf.run(mode: [:cpu|:wall|:object])`.
the `run` method takes a block of code and returns a profile as a simple hash.
``` ruby
@@ -293,11 +297,11 @@
`A#initialize` was in 185 samples, but it was at the top of the stack in only 1 sample. the rest of the samples are
divided up between its callee edges. all 91 calls to `A#pow` came from `A#initialize`, as seen by the edge numbered
`70346498324780`.
-### advanced usage
+## Advanced usage
the profiler can be started and stopped manually. results are accumulated until retrieval, across
multiple start/stop invocations.
``` ruby
@@ -305,11 +309,11 @@
StackProf.start(mode: :cpu)
StackProf.stop
StackProf.results('/tmp/some.file')
```
-### all options
+## All options
`StackProf.run` accepts an options hash. Currently, the following options are recognized:
Option | Meaning
------- | ---------
@@ -318,9 +322,9 @@
`interval` | mode-relative sample rate [c.f.](#sampling)
`aggregate` | defaults: `true` - if `false` disables [aggregation](#aggregation)
`raw` | defaults `false` - if `true` collects the extra data required by the `--flamegraph` and `--stackcollapse` report types
`save_every`| (rack middleware only) write the target file after this many requests
-### todo
+## Todo
* file/iseq blacklist
* restore signal handlers on stop