stackprof 0.2.14 → 0.2.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50313d95bc2bb3257ea5d4bc6b4c1889f7d6c4c2612b35b7a289de1d8abddaf8
-  data.tar.gz: ac748642b2298f1d23a0c950eed379dd6670eaef7ad300bc5ab5341886d22b39
+  metadata.gz: 2c802ba8d0dfa813e939679507d70376e7dc33924369bb9d767523cfa5faed31
+  data.tar.gz: 5defbe29a222a82e3b6901ed10b0c73d962ed6a650b14b0c3cd3c231c27c0e39
 SHA512:
-  metadata.gz: d790c7c34cc8f12e5e3d12cfc2476e94801e62f79a8ccb747b3d0743b9b8d0bb8ec8fd92757c5696814c028ddeaa4044bbaa0d242fe5796079f741d2fdbef2d6
-  data.tar.gz: b3e5d358816564a6a3a72bfd68c2d94f184a27430b9b75765cf733c4c5104e7c4020ce72bfdf6d3698bbf0456ca487314fb094a0faf6eed7040bce10726df017
+  metadata.gz: 0e585cf066f4008907975726f22185184210e375ca6fe28e51fe44fca7fe53e2cdc414482dcba3e413da2238a879cb5fa58530106ad5f8cb217fc6cee1bf4a2b
+  data.tar.gz: 7b2d08fbd2d70c803f06f42c15e7978871f01c343f3d149f2a63b781d4e074542f445e9a809bdaab1921e779ec9d868159fedc752103faf86c45ddfe7239b74a

data/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  rubies:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ ruby-head, '3.0', '2.7', '2.6', '2.5', '2.4', '2.3', '2.2' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run test
+        run: rake
+      - name: Install gem
+        run: rake install
+  platforms:
+    strategy:
+      matrix:
+        os: [macos]
+        ruby: ['3.0']
+    runs-on: ${{ matrix.os }}-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run test
+        run: rake
+      - name: Install gem
+        run: rake install

data/.gitignore

@@ -3,3 +3,4 @@
 /lib/stackprof/stackprof.so
 *.sw?
 /pkg
+/Gemfile.lock

data/CHANGELOG.md

@@ -1,7 +1,14 @@
-# 0.2.14
+# 0.2.16
 
-* Relax threshold of missed_samples to <= 25 in GC test
-* Support custom metadata option in stackprof
-* Drop support for Ruby 2.1
-* More generic handling of "fake" frame names
-* Record marking and sweeping as fake gc calls
+* [flamegraph.pl] Update to latest version
+* Add option to ignore GC frames
+* Handle source code not being available
+* Freeze strings in report.rb
+* Use a cursor object instead of array slicing
+* ArgumentError on interval <1 or >1m
+* fix variable name.
+* Fix default mode comment in readme
+
+# 0.2.15
+
+* Mark the metadata object before the GC is invoked to prevent it from being garbage collected.

data/README.md

@@ -81,21 +81,21 @@ $ stackprof tmp/stackprof-cpu-*.dump --method 'Object#present?'
 
 For an experimental version of WebUI reporting of stackprof, see [stackprof-webnav](https://github.com/alisnic/stackprof-webnav)
 
-You can generate a flamegraph however additional data must be collected using the `raw: true` flag. Once you've collected results with this flag enabled you can generate a flamegraph:
+To generate flamegraphs with Stackprof, additional data must be collected using the `raw: true` flag. Once you've collected results with this flag enabled, generate a flamegraph with:
 
 ```
 $ stackprof --flamegraph tmp/stackprof-cpu-myapp.dump > tmp/flamegraph
 ```
 
-Once the flamegraph has been generated you can generate a viewer command with:
+After the flamegraph has been generated, you can generate a viewer command with:
 
 ```
 $ stackprof --flamegraph-viewer=tmp/flamegraph
 ```
 
-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:
+The `--flamegraph-viewer` command will output the exact shell command you need to run in order to open the `tmp/flamegraph` you generated with the built-in stackprof flamegraph viewer:
 
-![](http://i.imgur.com/EwndrgD.png)
+![Flamegraph Viewer](http://i.imgur.com/EwndrgD.png)
 
 Alternatively, you can generate a flamegraph that uses [d3-flame-graph](https://github.com/spiermar/d3-flame-graph):
 
@@ -107,16 +107,16 @@ And just open the result by your browser.
 
 ## Sampling
 
-four sampling modes are supported:
+Four sampling modes are supported:
 
-  - :wall (using `ITIMER_REAL` and `SIGALRM`)
-  - :cpu (using `ITIMER_PROF` and `SIGPROF`) [default mode]
-  - :object (using `RUBY_INTERNAL_EVENT_NEWOBJ`)
-  - :custom (user-defined via `StackProf.sample`)
+  - `:wall` (using `ITIMER_REAL` and `SIGALRM`) [default mode]
+  - `:cpu` (using `ITIMER_PROF` and `SIGPROF`)
+  - `:object` (using `RUBY_INTERNAL_EVENT_NEWOBJ`)
+  - `:custom` (user-defined via `StackProf.sample`)
 
-samplers have a tuneable interval which can be used to reduce overhead or increase granularity:
+Samplers have a tuneable interval which can be used to reduce overhead or increase granularity:
 
-  - wall time: sample every _interval_ microseconds of wallclock time (default: 1000)
+  - Wall time: sample every _interval_ microseconds of wallclock time (default: 1000)
 
 ```ruby
 StackProf.run(mode: :wall, out: 'tmp/stackprof.dump', interval: 1000) do
@@ -124,7 +124,7 @@ StackProf.run(mode: :wall, out: 'tmp/stackprof.dump', interval: 1000) do
 end
 ```
 
-  - cpu time: sample every _interval_ microseconds of cpu activity (default: 1000 = 1 millisecond)
+  - CPU time: sample every _interval_ microseconds of CPU activity (default: 1000 = 1 millisecond)
 
 ```ruby
 StackProf.run(mode: :cpu, out: 'tmp/stackprof.dump', interval: 1000) do
@@ -132,7 +132,7 @@ StackProf.run(mode: :cpu, out: 'tmp/stackprof.dump', interval: 1000) do
 end
 ```
 
-  - object allocation: sample every _interval_ allocations (default: 1)
+  - Object allocation: sample every _interval_ allocations (default: 1)
 
 
 ```ruby
@@ -141,30 +141,36 @@ StackProf.run(mode: :object, out: 'tmp/stackprof.dump', interval: 1) do
 end
 ```
 
-samples are taken using a combination of three new C-APIs in ruby 2.1:
+By default, samples taken during garbage collection will show as garbage collection frames
+including both mark and sweep phases. For longer traces, these can leave gaps in a flamegraph
+that are hard to follow. They can be disabled by setting the `ignore_gc` option to true.
+Garbage collection time will still be present in the profile but not explicitly marked with
+its own frame.
 
-  - signal handlers enqueue a sampling job using `rb_postponed_job_register_one`.
+Samples are taken using a combination of three new C-APIs in ruby 2.1:
+
+  - Signal handlers enqueue a sampling job using `rb_postponed_job_register_one`.
     this ensures callstack samples can be taken safely, in case the VM is garbage collecting
     or in some other inconsistent state during the interruption.
 
-  - stack frames are collected via `rb_profile_frames`, which provides low-overhead C-API access
-    to the VM's call stack. no object allocations occur in this path, allowing stackprof to collect
+  - Stack frames are collected via `rb_profile_frames`, which provides low-overhead C-API access
+    to the VM's call stack. No object allocations occur in this path, allowing stackprof to collect
     callstacks in allocation mode.
 
-  - in allocation mode, samples are taken via `rb_tracepoint_new(RUBY_INTERNAL_EVENT_NEWOBJ)`,
+  - 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
 
-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:
+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
-  - total_samples: samples where this frame was in the stack
-  - lines: samples per line number in this frame
-  - edges: samples per callee frame (methods invoked by this frame)
+  - `samples`: Number of samples where this was the topmost frame
+  - `total_samples`: Samples where this frame was in the stack
+  - `lines`: Samples per line number in this frame
+  - `edges`: Samples per callee frame (methods invoked by this frame)
 
-the aggregation algorithm is roughly equivalent to the following pseudo code:
+The aggregation algorithm is roughly equivalent to the following pseudo code:
 
 ``` ruby
 trap('PROF') do
@@ -183,16 +189,16 @@ trap('PROF') do
 end
 ```
 
-this technique builds up an incremental callgraph from the samples. on any given frame,
+This technique builds up an incremental call graph 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
 
-multiple reporting modes are supported:
-  - text
-  - dotgraph
-  - source annotation
+Multiple reporting modes are supported:
+  - Text
+  - Dotgraph
+  - Source annotation
 
 ### `StackProf::Report.new(data).print_text`
 
@@ -211,8 +217,6 @@ multiple reporting modes are supported:
 
 ### `StackProf::Report.new(data).print_graphviz`
 
-![](http://cl.ly/image/2t3l2q0l0B0A/content)
-
 ```
 digraph profile {
   70346498324780 [size=23.5531914893617] [fontsize=23.5531914893617] [shape=box] [label="A#pow\n91 (48.4%)\r"];
@@ -259,8 +263,8 @@ block in A#math (/Users/tmm1/code/stackprof/sample.rb:21)
 
 ## 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.
+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
 # sample after every 1ms of cpu activity
@@ -269,12 +273,12 @@ profile = StackProf.run(mode: :cpu, interval: 1000) do
 end
 ```
 
-this profile data structure is part of the public API, and is intended to be saved
-(as json/marshal for example) for later processing. the reports above can be generated
+This profile data structure is part of the public API, and is intended to be saved
+(as json/marshal for example) for later processing. The reports above can be generated
 by passing this structure into `StackProf::Report.new`.
 
-the format itself is very simple. it contains a header and a list of frames. each frame has a unique id and
-identifying information such as its name, file and line. the frame also contains sampling data, including per-line
+The format itself is very simple. It contains a header and a list of frames. Each frame has a unique ID and
+identifying information such as its name, file, and line. The frame also contains sampling data, including per-line
 samples, and a list of relationships to other frames represented as weighted edges.
 
 ``` ruby
@@ -301,20 +305,21 @@ samples, and a list of relationships to other frames represented as weighted edg
      :lines=>{8=>1}},
 ```
 
-above, `A#pow` was involved in 91 samples, and in all cases it was at the top of the stack on line 12.
+Above, `A#pow` was involved in 91 samples, and in all cases it was at the top of the stack on line 12.
 
-`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
+`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
 
-the profiler can be started and stopped manually. results are accumulated until retrieval, across
-multiple start/stop invocations.
+The profiler can be started and stopped manually. Results are accumulated until retrieval, across
+multiple `start`/`stop` invocations.
 
 ``` ruby
-StackProf.running?
+StackProf.running? # => false
 StackProf.start(mode: :cpu)
+StackProf.running? # => true
 StackProf.stop
 StackProf.results('/tmp/some.file')
 ```
@@ -325,13 +330,14 @@ StackProf.results('/tmp/some.file')
 
 Option      | Meaning
 -------     | ---------
-`mode`      | mode of sampling: `:cpu`, `:wall`, `:object`, or `:custom` [c.f.](#sampling)
-`out`       | the target file, which will be overwritten
-`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
-`metadata`  | defaults to `{}`. Must be a `Hash`. metadata associated with this profile
-`save_every`| (rack middleware only) write the target file after this many requests
+`mode`      | Mode of sampling: `:cpu`, `:wall`, `:object`, or `:custom` [c.f.](#sampling)
+`out`       | The target file, which will be overwritten
+`interval`  | Mode-relative sample rate [c.f.](#sampling)
+`ignore_gc` | Ignore garbage collection frames
+`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
+`metadata`  | Defaults to `{}`. Must be a `Hash`. metadata associated with this profile
+`save_every`| (Rack middleware only) write the target file after this many requests
 
 ## Todo
 

data/Rakefile

@@ -1,31 +1,17 @@
-task :default => :test
+require "bundler/gem_tasks"
+require "rake/testtask"
 
-# ==========================================================
-# Packaging
-# ==========================================================
-
-GEMSPEC = Gem::Specification::load('stackprof.gemspec')
-
-require 'rubygems/package_task'
-Gem::PackageTask.new(GEMSPEC) do |pkg|
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
 end
 
-# ==========================================================
-# Ruby Extension
-# ==========================================================
+require "rake/extensiontask"
 
-require 'rake/extensiontask'
-Rake::ExtensionTask.new('stackprof', GEMSPEC) do |ext|
-  ext.lib_dir = 'lib/stackprof'
+Rake::ExtensionTask.new("stackprof") do |ext|
+  ext.ext_dir = "ext/stackprof"
+  ext.lib_dir = "lib/stackprof"
 end
-task :build => :compile
 
-# ==========================================================
-# Testing
-# ==========================================================
-
-require 'rake/testtask'
-Rake::TestTask.new 'test' do |t|
-  t.test_files = FileList['test/test_*.rb']
-end
-task :test => :build
+task default: %i(compile test)