rperf 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f19061984f2ea33bbcd569c43e8a7ece03071b8fbb442ebe108468eb07d96a14
-  data.tar.gz: 66bee438bd8459db8ce89129cef39bdaaba3ad82e348012c5d220fb5b6f3963f
+  metadata.gz: 7182c353301aa38afde2d65928219c46cee3e777b49842bf60331dd40e7b3ab2
+  data.tar.gz: ebb30b807d9b86a7ff48090bc5990d6bdcc0c9951f80b21758df2413bdbd39f2
 SHA512:
-  metadata.gz: 3a9468eadacbb41afbc751bd767141a3db785a2eaa51e33549503fe160a8adb25f6612c0cc4c61381b8f8442836a970a23d29cda4fe696488ca85d2b048518a2
-  data.tar.gz: 5e8e6c6c24fbb264f352c98511481e5d448b6a07e390c72cc31beeab2aa03699cde22f2f04268531ab50572e7cfd54cab7235359915caa6c6b3c9eb40f26d4e9
+  metadata.gz: d70dde1af1a4c3c9cec02e20981038c465facea4d3da32c32ce26e16cfc402de01f594c0b41386e3095f53603631f930fb2bd133d23b8a5757662d40f117d2a5
+  data.tar.gz: b7868f0237f84a47bda6286c99b7056f47738fb235ede0d21ac8f950feb9b891b1677dff38f25294393766cbe4f742b2eeffe73a43dded92562926db8d5bd392

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koichi Sasada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  pprof / collapsed stacks / text report &nbsp;·&nbsp; CPU mode & wall mode (GVL + GC tracking)
+  Built-in flamegraph viewer &nbsp;·&nbsp; CPU mode & wall mode (GVL + GC tracking)
 </p>
 
 <p align="center">
@@ -29,29 +29,34 @@
 ## See It in Action
 
 ```bash
-$ gem install rperf
 $ rperf exec ruby fib.rb
 
  Performance stats for 'ruby fib.rb':
 
-         2,326.0 ms   user
-            64.5 ms   sys
-         2,035.5 ms   real
+         2,023.3 ms   user
+             4.3 ms   sys
+         2,001.8 ms   real
 
-         2,034.2 ms 100.0%  CPU execution
-               1            [Ruby] detected threads
-             7.0 ms         [Ruby] GC time (7 count: 5 minor, 2 major)
-         106,078            [Ruby] allocated objects
-              22 MB         [OS] peak memory (maxrss)
+         2,000.3 ms 100.0%  [Rperf] CPU execution
+             3.0 ms         [Ruby ] GC time (4 count: 2 minor, 2 major)
+          48,741            [Ruby ] allocated objects
+          27,034            [Ruby ] freed objects
+               1            [Ruby ] detected threads
+              16 MB         [OS   ] peak memory (maxrss)
+           5,784            [OS   ] page faults (5,783 minor, 1 major)
+              22            [OS   ] context switches (13 voluntary, 9 involuntary)
+               0 MB         [OS   ] disk I/O (0 MB read, 0 MB write)
 
  Flat:
-         2,034.2 ms 100.0%  Object#fibonacci (fib.rb)
+         1,998.4 ms  99.9%  Object#fibonacci (fib.rb)
+             1.9 ms   0.1%  Module#method_added (<C method>)
 
  Cumulative:
-         2,034.2 ms 100.0%  Object#fibonacci (fib.rb)
-         2,034.2 ms 100.0%  <main> (fib.rb)
+         2,000.3 ms 100.0%  <main> (fib.rb)
+         1,998.4 ms  99.9%  Object#fibonacci (fib.rb)
+             1.9 ms   0.1%  Module#method_added (<C method>)
 
-  2034 samples / 2034 triggers, 0.1% profiler overhead
+  1999 samples / 1999 triggers, 0.1% profiler overhead
 ```
 
 ## Quick Start
@@ -60,26 +65,27 @@ $ rperf exec ruby fib.rb
 # Performance summary (wall mode, prints to stderr)
 rperf stat ruby app.rb
 
-# Record a pprof profile to file
-rperf record ruby app.rb                              # → rperf.data (cpu mode)
-rperf record -m wall -o profile.pb.gz ruby server.rb   # wall mode, custom output
+# Record a profile to file
+rperf record ruby app.rb                     # → rperf.json.gz (cpu mode, default)
+rperf record -m wall ruby server.rb          # wall mode
 
-# View results (report/diff require Go: https://go.dev/dl/)
-rperf report                      # open rperf.data in browser
-rperf report --top profile.pb.gz  # print top functions to terminal
+# View results in browser
+rperf report                                 # open rperf.json.gz in viewer
+rperf report --top profile.json.gz           # print top functions to terminal
 
-# Compare two profiles
-rperf diff before.pb.gz after.pb.gz        # open diff in browser
-rperf diff --top before.pb.gz after.pb.gz  # print diff to terminal
+# Compare two profiles (requires Go)
+rperf diff before.json.gz after.json.gz      # open diff in browser
 ```
 
+On `rperf report`, you can see the profile result like this page: [rprof viewer](https://ko1.github.io/rperf/examples/cpu_intensive_profile.html)
+
 ### Ruby API
 
 ```ruby
 require "rperf"
 
 # Block form — profiles and saves to file
-Rperf.start(output: "profile.pb.gz", frequency: 500, mode: :cpu) do
+Rperf.start(output: "profile.json.gz", frequency: 500, mode: :cpu) do
   # code to profile
 end
 
@@ -87,18 +93,37 @@ end
 Rperf.start(frequency: 1000, mode: :wall)
 # ...
 data = Rperf.stop
-Rperf.save("profile.pb.gz", data)
+Rperf.save("profile.json.gz", data)
+```
+
+### In-browser Viewer
+
+```ruby
+# config.ru
+require "rperf/viewer"
+require "rperf/rack"
+
+Rperf.start(mode: :wall, defer: true)
+use Rperf::Viewer           # visit /rperf/ for flamegraph UI
+use Rperf::RackMiddleware   # labels each request
+run MyApp
+
+# Snapshot every 60 minutes
+Thread.new { loop { sleep 3600; Rperf::Viewer.instance&.take_snapshot! } }
 ```
 
+> **Note:** `Rperf::Viewer` has no built-in authentication. In production, restrict access with your framework's auth mechanisms (e.g., route constraints in Rails). See the [manual](https://ko1.github.io/rperf/docs/manual/) for examples.
+
 ### Environment Variables
 
 Profile without code changes (e.g., Rails):
 
 ```bash
-RPERF_ENABLED=1 RPERF_MODE=wall RPERF_OUTPUT=profile.pb.gz ruby app.rb
+RPERF_ENABLED=1 RPERF_MODE=wall ruby app.rb    # → rperf.json.gz
+rperf report                                    # open in viewer
 ```
 
-Run `rperf help` for full documentation, or see the [online manual](https://ko1.github.io/rperf/).
+Run `rperf help` for full documentation, or see the [online manual](https://ko1.github.io/rperf/docs/manual/).
 
 ## Subcommands
 
@@ -106,11 +131,11 @@ Inspired by Linux `perf` — familiar subcommand interface for profiling workflo
 
 | Command | Description |
 |---------|-------------|
-| `rperf record` | Profile a command and save to file |
+| `rperf record` | Profile a command and save to file (default: `.json.gz`) |
 | `rperf stat` | Profile a command and print summary to stderr |
 | `rperf exec` | Profile a command and print full report to stderr |
-| `rperf report` | Open pprof profile with `go tool pprof` (requires Go) |
-| `rperf diff` | Compare two pprof profiles (requires Go) |
+| `rperf report` | Open viewer for `.json.gz`; wraps `go tool pprof` for `.pb.gz` (requires Go) |
+| `rperf diff` | Compare two profiles (requires Go) |
 | `rperf help` | Show full reference documentation |
 
 ## How It Works
@@ -133,7 +158,7 @@ Timer (signal or thread)         VM thread (postponed job)
                                       record(backtrace, weight)
 ```
 
-On Linux, the timer uses `timer_create` + signal delivery (no extra thread).
+On Linux, the timer uses `timer_create` + signal delivery to a dedicated worker thread.
 On other platforms, a dedicated pthread with `nanosleep` is used.
 
 If a safepoint is delayed, the sample carries proportionally more weight. The total weight equals the total time, accurately distributed across call stacks.
@@ -147,44 +172,45 @@ If a safepoint is delayed, the sample carries proportionally more weight. The to
 
 Use `cpu` to find what consumes CPU. Use `wall` to find what makes things slow (I/O, GVL contention, GC).
 
-### Synthetic Frames (wall mode)
+### GVL and GC Labels
 
-rperf hooks GVL and GC events to attribute non-CPU time:
+rperf hooks GVL and GC events to attribute non-CPU time. These are recorded as labels on samples rather than synthetic stack frames:
 
-| Frame | Meaning |
-|-------|---------|
-| `[GVL blocked]` | Off-GVL time (I/O, sleep, C extension releasing GVL) |
-| `[GVL wait]` | Waiting to reacquire the GVL (contention) |
-| `[GC marking]` | Time in GC mark phase |
-| `[GC sweeping]` | Time in GC sweep phase |
+| Label (key=value) | Mode | Meaning |
+|-------|------|---------|
+| `%GVL=blocked` | wall only | Off-GVL time (I/O, sleep, C extension releasing GVL) |
+| `%GVL=wait` | wall only | Waiting to reacquire the GVL (contention) |
+| `%GC=mark` | cpu and wall | Time in GC mark phase (wall time) |
+| `%GC=sweep` | cpu and wall | Time in GC sweep phase (wall time) |
 
 ## Why rperf?
 
 - **Accurate despite safepoints** — Safepoint sampling is *safer* (no async-signal-safety issues), but normally *inaccurate*. rperf compensates with real time-delta weights, so profiles faithfully reflect where time is actually spent.
-- **See the whole picture** (wall mode) — GVL contention, off-GVL I/O, GC marking/sweeping — all attributed to the call stacks responsible, via synthetic frames.
-- **Low overhead** — Signal-based timer on Linux (no extra thread). ~1–5 µs per sample.
-- **pprof compatible** — Works with `go tool pprof`, speedscope, and other standard tools out of the box.
+- **See the whole picture** (wall mode) — GVL contention, off-GVL I/O, GC marking/sweeping — all attributed to the call stacks responsible, via sample labels.
+- **Built-in viewer** — Flamegraph, Top, Tags tabs with interactive tag filtering. No external tools needed to analyze profiles.
+- **Low overhead** — Signal-based timer on Linux (no extra thread). ~1–5 us per sample.
 - **Zero code changes** — Profile any Ruby program via CLI or environment variables. Drop-in for Rails, too.
 - **`perf`-like CLI** — `record`, `stat`, `report`, `diff` — if you know Linux perf, you already know rperf.
+- **Multi-process** — automatically profiles forked/spawned Ruby child processes (e.g., Unicorn/Puma workers). Use `--no-inherit` to disable.
 
 ### Limitations
 
 - **Method-level only** — no line-level granularity.
 - **Ruby >= 3.4.0** — uses recent VM internals (postponed jobs, thread event hooks).
 - **POSIX only** — Linux, macOS. No Windows.
-- **No fork support** — profiling does not follow fork(2) child processes.
 
 
 ## Output Formats
 
-| Format | Extension | Use case |
-|--------|-----------|----------|
-| pprof (default) | `.pb.gz` | `rperf report`, `go tool pprof`, speedscope |
-| collapsed | `.collapsed` | FlameGraph (`flamegraph.pl`), speedscope |
-| text | `.txt` | Human/AI-readable flat + cumulative report |
+| Format | Extension | Viewer |
+|--------|-----------|--------|
+| JSON (default) | `.json.gz` | `rperf report` (built-in viewer), `Rperf.load`, any JSON tool |
+| pprof | `.pb.gz` | `go tool pprof` (requires Go), speedscope |
+| collapsed | `.collapsed` | FlameGraph, speedscope |
+| text | `.txt` | any text viewer |
 
 Format is auto-detected from extension, or set explicitly with `--format`.
 
 ## License
 
-MIT
+MIT