rperf 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 497392cfda8e82d1c37aadd0953b4c73b6bfb09870e6c612c1fd5fced0e3d24f
-  data.tar.gz: 6960be209fc3d4aac0f268378c5b7e1399027da0c5b7f498bcb4be0662012d62
+  metadata.gz: 520b1f5fd883bd68232c2b714aa1a66dbf811a3f3d2b2b54c212233f4a97d1c4
+  data.tar.gz: 11f5a6f52444abebc28a41055726eab246d623457c85001ba737fcb790b20cea
 SHA512:
-  metadata.gz: '09fc32b7577ac9544a846c86c37a7ad11e9de00a27bbb0bbd25cbc2fcabe04e74741c64f9fb3cfe1a9663145e058215272a247766c7b8106218eda80cbcd838f'
-  data.tar.gz: 9d13e685c5a293c4d9033376509bf4b5c762a5f5155a2d5dd6e838d5a55dc79b9ef7d9521a5bcf65eac88a683f0e20cd7e5dac2680134aa565c709eb48452e40
+  metadata.gz: 88c50af83f66f569739bd37377cc2dfc51f7bc6970243cb14bf5b2a7defc9ab6fee60f0e43f85e30f5acf0a315c2774ff0fd88b36c6ed913a5e9d6ef4aa63352
+  data.tar.gz: 63359d42f26529e726ef070f335e726b62bef23b0c897092b6010385ae91d01790039da35e300e734c4dfebb796c8b687759bdce395e13fcb778dca89c0318a1

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,17 +65,16 @@ $ 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 (no external tools needed)
+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
 ```
 
 ### Ruby API
@@ -79,7 +83,7 @@ rperf diff --top before.pb.gz after.pb.gz  # print diff to terminal
 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 +91,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 +129,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
@@ -147,23 +170,23 @@ 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 (wall mode)
 
-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 |
+| Label | 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 |
+| `%GVL: blocked` | Off-GVL time (I/O, sleep, C extension releasing GVL) |
+| `%GVL: wait` | Waiting to reacquire the GVL (contention) |
+| `%GC: mark` | Time in GC mark phase |
+| `%GC: sweep` | Time in GC sweep phase |
 
 ## 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.
 
@@ -172,19 +195,20 @@ rperf hooks GVL and GC events to attribute non-CPU time:
 - **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.
+- **No fork following** — profiling stops in fork(2) child processes (the child can start a new session).
 
 
 ## 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

data/docs/help.md

@@ -16,10 +16,10 @@ POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
 
 ### record: Profile and save to file.
 
-    -o, --output PATH       Output file (default: rperf.data)
+    -o, --output PATH       Output file (default: rperf.json.gz)
     -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
     -m, --mode MODE         cpu or wall (default: cpu)
-    --format FORMAT         pprof, collapsed, or text (default: auto from extension)
+    --format FORMAT         json, pprof, collapsed, or text (default: auto from extension)
     -p, --print             Print text profile to stdout
                             (same as --format=text --output=/dev/stdout)
     --signal VALUE          Timer signal (Linux only): signal number, or 'false'
@@ -40,6 +40,8 @@ Uses wall mode by default. No file output by default.
 
 Shows: user/sys/real time, time breakdown (CPU execution, GVL blocked,
 GVL wait, GC marking, GC sweeping), GC/memory/OS stats, and profiler overhead.
+Lines are prefixed: `[Rperf]` for sampling-derived data, `[Ruby ]` for
+runtime info, `[OS   ]` for OS-level info.
 Use --report to add flat and cumulative top-50 function tables.
 
 ### exec: Run command and print full profile report to stderr.
@@ -56,13 +58,13 @@ Like `stat --report`. Uses wall mode by default. No file output by default.
 Shows: user/sys/real time, time breakdown, GC/memory/OS stats, profiler overhead,
 and flat/cumulative top-50 function tables.
 
-### report: Open pprof profile with go tool pprof. Requires Go.
+### report: Open profile viewer or go tool pprof.
 
     --top                   Print top functions by flat time
     --text                  Print text report
 
 Default (no flag): opens interactive web UI in browser.
-Default file: rperf.data
+Default file: rperf.json.gz
 
 ### diff: Compare two pprof profiles (target - base). Requires Go.
 
@@ -116,7 +118,8 @@ Rperf.save("profile.txt", data)
     mode:       :cpu or :wall (Symbol, default: :cpu)
     output:     File path to write on stop (String or nil)
     verbose:    Print statistics to stderr (true/false, default: false)
-    format:     :pprof, :collapsed, :text, or nil for auto-detect (Symbol or nil)
+    format:     :json, :pprof, :collapsed, :text, or nil for auto-detect (Symbol or nil)
+    defer:      Start with timer paused; use Rperf.profile to activate (default: false)
 
 ### Rperf.stop return value
 
@@ -210,29 +213,62 @@ In pprof output, use labels for filtering and grouping:
     go tool pprof -tagroot=request profile.pb.gz
     go tool pprof -tagleaf=request profile.pb.gz
 
+### Rperf.start with defer: true
+
+With `defer: true`, the profiler infrastructure is set up but the sampling
+timer does not start. Use `Rperf.profile` to activate the timer for specific
+sections. Outside `profile` blocks, the timer is disarmed and overhead is zero.
+
+Note: the timer is process-wide, not per-thread. While a `profile` block is
+active on one thread, other threads running at the same time will also be
+sampled. Their samples carry their own labels (not the calling thread's labels),
+so they can be distinguished in the profile. This design is intentional: it
+provides complete visibility into what the process was doing during profiled
+sections, including GVL contention and background work.
+
+### Rperf.profile(**labels, &block)
+
+Activates the sampling timer for the block duration and applies labels to
+the current thread. Designed for use with `start(defer: true)`.
+
+```ruby
+Rperf.start(defer: true, mode: :wall)
+
+Rperf.profile(endpoint: "/users") do
+  handle_request   # sampled with endpoint="/users"
+end
+# timer paused — zero overhead
+
+data = Rperf.stop
+```
+
+Nesting is supported: timer stays active until the outermost block exits.
+Also works with `start(defer: false)` — applies labels only (timer already
+running). Raises `RuntimeError` if not started, `ArgumentError` without block.
+
 ### Rperf.labels
 
 Returns the current thread's labels as a Hash. Empty hash if none set.
 
 ### Rperf.save(path, data, format: nil)
 
-Writes data to path. format: :pprof, :collapsed, or :text.
+Writes data to path. format: :json, :pprof, :collapsed, or :text.
 nil auto-detects from extension.
 
-### Rperf::Middleware (Rack)
+### Rperf::RackMiddleware (Rack)
 
-Labels samples with the request endpoint. Requires `require "rperf/middleware"`.
+Labels samples with the request endpoint. Requires `require "rperf/rack"`.
 
 ```ruby
 # Rails
-Rails.application.config.middleware.use Rperf::Middleware
+Rails.application.config.middleware.use Rperf::RackMiddleware
 
 # Sinatra
-use Rperf::Middleware
+use Rperf::RackMiddleware
 ```
 
-The middleware only sets labels — start profiling separately.
-Option: `label_key:` (default: `:endpoint`).
+The middleware uses `Rperf.profile` to activate timer and set labels.
+Start profiling separately. Option: `label_key:` (default: `:endpoint`).
 
 ### Rperf::ActiveJobMiddleware
 
@@ -256,6 +292,88 @@ Sidekiq.configure_server do |config|
 end
 ```
 
+### Rperf::Viewer (Rack middleware)
+
+In-browser profiling UI with flamegraph, top table, and tag breakdown.
+Requires `require "rperf/viewer"`.
+
+**Security note**: Rperf::Viewer has no built-in authentication and exposes
+profiling data (including stack traces and label values) to anyone who can
+reach the endpoint. In production, always restrict access using your
+framework's authentication — see "Access control" below. The UI loads
+d3.js and d3-flame-graph from CDNs (cdnjs.cloudflare.com, cdn.jsdelivr.net).
+
+```ruby
+# config.ru or Rails config
+require "rperf/viewer"
+use Rperf::Viewer                         # mount at /rperf/ (default)
+use Rperf::Viewer, path: "/profiler"      # custom mount path
+use Rperf::Viewer, max_snapshots: 12      # keep fewer snapshots (default: 24)
+```
+
+Take snapshots via `Rperf::Viewer.instance.take_snapshot!` or
+`Rperf::Viewer.instance.add_snapshot(data)`.
+
+#### Typical setup with RackMiddleware and periodic snapshots
+
+```ruby
+require "rperf/viewer"
+require "rperf/rack"
+
+Rperf.start(mode: :wall, frequency: 999, defer: true)
+use Rperf::Viewer
+use Rperf::RackMiddleware
+run MyApp
+
+# Take a snapshot every 60 minutes in a background thread
+Thread.new do
+  loop do
+    sleep 60 * 60
+    Rperf::Viewer.instance&.take_snapshot!
+  end
+end
+```
+
+Visit `/rperf/` in a browser. Snapshots accumulate automatically
+(up to `max_snapshots`, oldest are discarded). You can also trigger
+a snapshot manually via an endpoint or console:
+
+```ruby
+Rperf::Viewer.instance.take_snapshot!
+```
+
+#### Access control
+
+Rperf::Viewer has no built-in authentication. Restrict access using
+your framework's existing mechanisms:
+
+```ruby
+# Rails: route constraint (e.g., admin-only)
+# config/routes.rb
+require "rperf/viewer"
+constraints ->(req) { req.session[:admin] } do
+  mount Rperf::Viewer.new(nil, path: ""), at: "/rperf"
+end
+```
+
+#### UI tabs
+
+- **Flamegraph** — Interactive flamegraph (d3-flame-graph). Click to zoom.
+- **Top** — Flat/cumulative weight table. Click column headers to sort.
+- **Tags** — Label key/value breakdown with weight bars. Click a row to
+  set tagfocus and switch to Flamegraph.
+
+#### Filtering controls
+
+- **tagfocus** — Regex matched against label values. Press Enter to apply.
+- **tagignore** — Dropdown checkboxes. Select `key = (none)` to exclude
+  samples without that key (e.g., background threads without `endpoint`).
+- **tagroot** — Dropdown checkboxes for label keys. Checked keys are
+  prepended as root frames (e.g., `[endpoint: GET /users]`).
+- **tagleaf** — Same as tagroot but appended as leaf frames.
+
+Tag keys are sorted alphabetically (`%`-prefixed VM state keys appear first).
+
 ## PROFILING MODES
 
 - **cpu** — Measures per-thread CPU time via Linux thread clock.
@@ -265,15 +383,26 @@ end
 - **wall** — Measures wall-clock time (CLOCK_MONOTONIC).
   Use for: finding where wall time goes, including I/O, sleep, GVL
   contention, and off-CPU waits.
-  Includes synthetic frames (see below).
+  Includes VM state labels (see below).
 
 ## OUTPUT FORMATS
 
-### pprof (default)
+### json (default) — rperf native format
+
+Gzip-compressed JSON representation of the internal data hash
+(the same hash returned by `Rperf.stop` / `Rperf.snapshot` — see
+"Return value" above for the full structure).
+Preserves all data including labels, VM state, thread info, and statistics.
+Readable by non-Ruby tools (Python, jq, etc.).
+Extension convention: `.json.gz`
+View with: `rperf report` (opens rperf viewer in browser, no Go required).
+Load programmatically: `data = Rperf.load("rperf.json.gz")`
+
+### pprof
 
 Gzip-compressed protobuf. Standard pprof format.
 Extension convention: `.pb.gz`
-View with: `go tool pprof`, pprof-rs, or speedscope (via import).
+View with: `go tool pprof`, pprof-rs, speedscope, or `rperf report` (requires Go).
 
 Embedded metadata:
 
@@ -330,27 +459,44 @@ Example output:
 
 Format is auto-detected from the output file extension:
 
-    .collapsed → collapsed
-    .txt       → text
-    anything else → pprof
+    .json.gz    → json (rperf native, default)
+    .pb.gz      → pprof
+    .collapsed  → collapsed
+    .txt        → text
 
 The `--format` flag (CLI) or `format:` parameter (API) overrides auto-detect.
 
-## SYNTHETIC FRAMES
+## VM STATE LABELS
+
+rperf tracks GVL and GC states as **labels** (tags) on samples, not as
+stack frames. The C extension records a VM state per sample, and the Ruby
+layer merges it into the sample's label set using reserved keys `%GVL`
+and `%GC`.
 
-In wall mode, rperf adds synthetic frames that represent non-CPU time:
+In wall mode, GVL state labels are recorded:
 
-- **[GVL blocked]** — Time the thread spent off-GVL (I/O, sleep, C extension
+- **%GVL=blocked** — The thread was off-GVL (I/O, sleep, C extension
   releasing GVL). Attributed to the stack at SUSPENDED.
-- **[GVL wait]** — Time the thread spent waiting to reacquire the GVL after
+- **%GVL=wait** — The thread was waiting to reacquire the GVL after
   becoming ready. Indicates GVL contention. Same stack.
 
-In both modes, GC time is tracked:
+In both modes, GC state labels are recorded:
+
+- **%GC=mark** — Time spent in GC marking phase (wall time).
+- **%GC=sweep** — Time spent in GC sweeping phase (wall time).
+
+These labels appear in `label_sets` (e.g., `{"%GVL" => "blocked"}`,
+`{"%GC" => "mark"}`) and are written into pprof sample labels.
+
+To add VM state as frames in flamegraphs, use pprof tag options:
+
+    go tool pprof -tagleaf=%GVL profile.pb.gz
+    go tool pprof -tagroot=%GC profile.pb.gz
 
-- **[GC marking]** — Time spent in GC marking phase (wall time).
-- **[GC sweeping]** — Time spent in GC sweeping phase (wall time).
+To filter by VM state:
 
-These always appear as the leaf (deepest) frame in a sample.
+    go tool pprof -tagfocus=%GVL=blocked profile.pb.gz
+    go tool pprof -tagfocus=%GC=mark profile.pb.gz
 
 ## INTERPRETING RESULTS
 
@@ -375,20 +521,24 @@ To convert: 1,000,000 ns = 1 ms, 1,000,000,000 ns = 1 s.
 **Problem: slow request / high latency**
 - Mode: wall
 - Look for: functions with high cum wall time.
-- If [GVL blocked] is dominant → I/O or sleep is the bottleneck.
-- If [GVL wait] is dominant → GVL contention; reduce GVL-holding work
+- If %GVL=blocked is dominant → I/O or sleep is the bottleneck.
+  Filter: `go tool pprof -tagfocus=%GVL=blocked profile.pb.gz`
+- If %GVL=wait is dominant → GVL contention; reduce GVL-holding work
   or move work to Ractors / child processes.
+  Filter: `go tool pprof -tagfocus=%GVL=wait profile.pb.gz`
 
 **Problem: GC pauses**
 - Mode: cpu or wall
-- Look for: [GC marking] and [GC sweeping] samples.
-- High [GC marking] → too many live objects; reduce allocations.
-- High [GC sweeping] → too many short-lived objects; reuse or pool.
+- Look for: samples with %GC=mark and %GC=sweep labels.
+  Filter: `go tool pprof -tagfocus=%GC profile.pb.gz`
+- High %GC=mark → too many live objects; reduce allocations.
+- High %GC=sweep → too many short-lived objects; reuse or pool.
 
 **Problem: multithreaded app slower than expected**
 - Mode: wall
-- Look for: [GVL wait] time across threads.
-- High [GVL wait] means threads are serialized on the GVL.
+- Look for: samples with %GVL=wait label across threads.
+  Filter: `go tool pprof -tagfocus=%GVL=wait profile.pb.gz`
+- High %GVL=wait means threads are serialized on the GVL.
 
 ## READING COLLAPSED STACKS PROGRAMMATICALLY
 
@@ -426,7 +576,7 @@ Used internally by the CLI to pass options to the auto-started profiler:
     RPERF_OUTPUT=path     Output file path
     RPERF_FREQUENCY=hz    Sampling frequency
     RPERF_MODE=cpu|wall   Profiling mode
-    RPERF_FORMAT=fmt      pprof, collapsed, or text
+    RPERF_FORMAT=fmt      json, pprof, collapsed, or text
     RPERF_VERBOSE=1       Print statistics
     RPERF_SIGNAL=N|false  Timer signal number or 'false' for nanosleep (Linux only)
     RPERF_STAT=1          Enable stat mode (used by rperf stat)

data/docs/logo.svg

@@ -0,0 +1,25 @@
+<svg viewBox="0 0 280 160" xmlns="http://www.w3.org/2000/svg">
+  <!-- Gauge arc -->
+  <path d="M70,100 A70,70 0 0,1 210,100" fill="none" stroke="#cc342d" stroke-width="3"/>
+
+  <!-- Tick marks -->
+  <g stroke="#cc342d" stroke-width="1.5">
+    <line x1="76" y1="68" x2="82" y2="74"/>
+    <line x1="100" y1="42" x2="104" y2="50"/>
+    <line x1="140" y1="32" x2="140" y2="40"/>
+    <line x1="180" y1="42" x2="176" y2="50"/>
+    <line x1="204" y1="68" x2="198" y2="74"/>
+  </g>
+
+  <!-- Ruby gem (below 12 o'clock tick) -->
+  <g transform="translate(140,52)">
+    <polygon points="-5,-5.5 5,-5.5 7.5,-1.5 0,6.5 -7.5,-1.5" fill="none" stroke="#cc342d" stroke-width="0.9"/>
+  </g>
+
+  <!-- Needle (-30%) -->
+  <line x1="140" y1="100" x2="172" y2="69" stroke="#8a7038" stroke-width="2.5" stroke-linecap="round"/>
+  <circle cx="140" cy="100" r="4" fill="#8a7038"/>
+
+  <!-- "rperf" text -->
+  <text x="140" y="148" text-anchor="middle" font-family="'Space Mono', monospace" font-size="24" font-weight="700" fill="#8a7038" letter-spacing="3">rperf</text>
+</svg>