rperf 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 520b1f5fd883bd68232c2b714aa1a66dbf811a3f3d2b2b54c212233f4a97d1c4
-  data.tar.gz: 11f5a6f52444abebc28a41055726eab246d623457c85001ba737fcb790b20cea
+  metadata.gz: 0dd9ddc0ea22d51ff2ebcdae6ddfa2f5e531c4a7814552b16470668d04d1d617
+  data.tar.gz: fce76e35ea6ccbca8e8b429da4b55574349f98b8731a2db3826efd908082dda6
 SHA512:
-  metadata.gz: 88c50af83f66f569739bd37377cc2dfc51f7bc6970243cb14bf5b2a7defc9ab6fee60f0e43f85e30f5acf0a315c2774ff0fd88b36c6ed913a5e9d6ef4aa63352
-  data.tar.gz: 63359d42f26529e726ef070f335e726b62bef23b0c897092b6010385ae91d01790039da35e300e734c4dfebb796c8b687759bdce395e13fcb778dca89c0318a1
+  metadata.gz: dceedb899f6b9249ae342e5701ef3280253c82d317ad73dea0bdd0c0c040a576740bb747c05c79b1f6118c82b05ad4756207ac046d9cc4805982a2f24ad09e1b
+  data.tar.gz: 4353afbe9ca80126c25884e837aacdd902a1e9d20756d543d235415492e17932490711b348ee49eb9e5144f977027a1284876cbd4dea4de31c342a16db16d931

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

@@ -69,14 +69,23 @@ rperf stat ruby app.rb
 rperf record ruby app.rb                     # → rperf.json.gz (cpu mode, default)
 rperf record -m wall ruby server.rb          # wall mode
 
-# View results in browser (no external tools needed)
+# 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 (requires Go)
 rperf diff before.json.gz after.json.gz      # open diff in browser
+
+# Track performance across commits (time-travel viewer)
+rperf record --snapshot-dir ./profiles ruby app.rb   # → profiles/rperf-<sha7>-<ts>.json.gz
+rperf report ./profiles/                             # sidebar: per-commit list, diff, sparkline
+
+# Flat tables for AI analysis (no Go required)
+rperf diff --format table base.json.gz head.json.gz | claude -p "analyze the regression"
 ```
 
+On `rperf report`, you can see the profile result like this page: [rperf viewer](https://ko1.github.io/rperf/examples/cpu_intensive_profile.html)
+
 ### Ruby API
 
 ```ruby
@@ -117,10 +126,12 @@ Thread.new { loop { sleep 3600; Rperf::Viewer.instance&.take_snapshot! } }
 Profile without code changes (e.g., Rails):
 
 ```bash
-RPERF_ENABLED=1 RPERF_MODE=wall ruby app.rb    # → rperf.json.gz
-rperf report                                    # open in viewer
+RPERF_ENABLED=1 RPERF_MODE=wall RUBYOPT=-rrperf ruby app.rb    # → rperf.json.gz
+rperf report                                                    # open in viewer
 ```
 
+`RPERF_ENABLED` takes effect when rperf is loaded — if rperf is already in your Gemfile (e.g., Rails), `RUBYOPT=-rrperf` is unnecessary.
+
 Run `rperf help` for full documentation, or see the [online manual](https://ko1.github.io/rperf/docs/manual/).
 
 ## Subcommands
@@ -132,8 +143,8 @@ Inspired by Linux `perf` — familiar subcommand interface for profiling workflo
 | `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 viewer for `.json.gz`; wraps `go tool pprof` for `.pb.gz` (requires Go) |
-| `rperf diff` | Compare two profiles (requires Go) |
+| `rperf report` | Open viewer for `.json.gz` (or a directory for time-travel mode); wraps `go tool pprof` for `.pb.gz` (requires Go) |
+| `rperf diff` | Compare two profiles (requires Go, except `--format table`) |
 | `rperf help` | Show full reference documentation |
 
 ## How It Works
@@ -156,7 +167,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.
@@ -170,32 +181,32 @@ 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).
 
-### GVL and GC Labels (wall mode)
+### GVL and GC Labels
 
 rperf hooks GVL and GC events to attribute non-CPU time. These are recorded as labels on samples rather than synthetic stack frames:
 
-| Label | Meaning |
-|-------|---------|
-| `%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 |
+| 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 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.
+- **Low overhead** — Signal-based timer on Linux (signals delivered to a dedicated worker thread — Ruby threads are never interrupted). ~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 following** — profiling stops in fork(2) child processes (the child can start a new session).
 
 
 ## Output Formats

data/docs/help.md

@@ -12,7 +12,9 @@ POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
     rperf stat [options] command [args...]
     rperf exec [options] command [args...]
     rperf report [options] [file]
+    rperf diff [options] base target
     rperf help
+    rperf -v / --version
 
 ### record: Profile and save to file.
 
@@ -24,8 +26,17 @@ POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
                             (same as --format=text --output=/dev/stdout)
     --signal VALUE          Timer signal (Linux only): signal number, or 'false'
                             for nanosleep thread (default: auto)
+    --snapshot-dir DIR      Save as rperf-<sha7>-<timestamp>.json.gz in DIR
+                            (rperf-nogit-<timestamp>-<pid>.json.gz outside git)
+    --label KEY=VALUE       Add a label to profile metadata (repeatable)
+    --no-inherit            Do not profile forked/spawned child processes
+    --no-aggregate          Disable C-level sample aggregation (raw per-sample data)
     -v, --verbose           Print sampling statistics to stderr
 
+JSON output embeds `meta` (git commit, host, Ruby/rperf versions, labels)
+and `summary` (time, GC, allocation, top methods) — see "Profile metadata"
+under OUTPUT FORMATS.
+
 ### stat: Run command and print performance summary to stderr.
 
 Uses wall mode by default. No file output by default.
@@ -33,9 +44,12 @@ Uses wall mode by default. No file output by default.
     -o, --output PATH       Also save profile to file (default: none)
     -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
     -m, --mode MODE         cpu or wall (default: wall)
+    --label KEY=VALUE       Add a label to profile metadata (repeatable)
     --report                Include flat/cumulative profile tables in output
     --signal VALUE          Timer signal (Linux only): signal number, or 'false'
                             for nanosleep thread (default: auto)
+    --no-inherit            Do not profile forked/spawned child processes
+    --no-aggregate          Disable C-level sample aggregation (raw per-sample data)
     -v, --verbose           Print additional sampling statistics
 
 Shows: user/sys/real time, time breakdown (CPU execution, GVL blocked,
@@ -44,6 +58,10 @@ 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.
 
+When child processes are profiled (default), the stat output shows
+aggregated data from all processes and includes a "Ruby processes profiled"
+count. Use --no-inherit to disable child process tracking.
+
 ### exec: Run command and print full profile report to stderr.
 
 Like `stat --report`. Uses wall mode by default. No file output by default.
@@ -51,8 +69,11 @@ Like `stat --report`. Uses wall mode by default. No file output by default.
     -o, --output PATH       Also save profile to file (default: none)
     -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
     -m, --mode MODE         cpu or wall (default: wall)
+    --label KEY=VALUE       Add a label to profile metadata (repeatable)
     --signal VALUE          Timer signal (Linux only): signal number, or 'false'
                             for nanosleep thread (default: auto)
+    --no-inherit            Do not profile forked/spawned child processes
+    --no-aggregate          Disable C-level sample aggregation (raw per-sample data)
     -v, --verbose           Print additional sampling statistics
 
 Shows: user/sys/real time, time breakdown, GC/memory/OS stats, profiler overhead,
@@ -62,17 +83,136 @@ and flat/cumulative top-50 function tables.
 
     --top                   Print top functions by flat time
     --text                  Print text report
+    --format FORMAT         Flat table for AI/machine consumption:
+                            'table' (TSV) or 'table-json' (JSON array)
+    --html                  Output static HTML viewer to stdout
+    --port PORT             Port for the web UI (default: auto).
+                            Useful for SSH port forwarding
+    --host HOST             Bind address for the web UI (default: localhost).
+                            0.0.0.0 allows external access — the viewer has
+                            NO authentication; prefer SSH port forwarding
+
+The browser is auto-opened only when a GUI is available (DISPLAY /
+WAYLAND_DISPLAY on Linux) and the bind address is local; otherwise the URL
+is printed for manual opening (no terminal-browser fallback).
 
 Default (no flag): opens interactive web UI in browser.
 Default file: rperf.json.gz
 
-### diff: Compare two pprof profiles (target - base). Requires Go.
+#### Time-travel mode (directory input)
+
+    rperf report ./profiles/
+
+Passing a directory lists all `*.json(.gz)` profiles in a sidebar — one row
+per snapshot with commit SHA (a `*` marks a dirty working tree), commit
+subject, date, and alloc/GC badges versus the previous snapshot (⚠️ when
+allocation changed more than ±15%). Rows are grouped by git branch
+(main/master expanded by default). Only meta/summary heads are read for the
+listing; profile bodies are lazy-loaded on selection, so directories with
+100+ snapshots open instantly. Works well with `rperf record --snapshot-dir`.
+
+- Click a row to view that snapshot; j / k move to the newer / older one.
+- ⇄ on a row diffs the current snapshot against it: the flamegraph is
+  recolored by share change (red = increased, blue = decreased, neutral
+  below ±0.4pt; direction is base (older) → current).
+- Shift+click a frame to pin that method: a sparkline of its share across
+  all snapshots appears at the top of the sidebar (points are filled in as
+  bodies load; click a point to jump). The pinned frame is highlighted and
+  others are dimmed.
+- Files without meta (saved by older rperf) appear as unknown snapshots.
+
+`--html` generates an HTML file with profile data embedded inline.
+No server is needed — open it directly in a browser. d3 and
+d3-flamegraph are loaded from CDN, so an internet connection is
+required on first viewing. Useful for sharing or hosting on static
+sites (e.g., GitHub Pages).
+
+    rperf report --html profile.json.gz > report.html
+
+### diff: Compare two profiles (target - base). Requires Go (except --format table).
+
+Accepts `.json.gz` (auto-converted to pprof) or `.pb.gz` files.
 
     --top                   Print top functions by diff
     --text                  Print text diff report
+    --format FORMAT         Flat diff table for AI/machine consumption:
+                            'table' (TSV) or 'table-json' (JSON array).
+                            Computed in Ruby — no Go required.
+                            .json.gz / .json files only.
+    --port PORT             Port for the web UI (default: auto)
+    --host HOST             Bind address for the web UI (default: localhost)
 
 Default (no flag): opens diff in browser.
 
+### Table output for AI analysis (--format table / table-json)
+
+Aggregation, diffing, and cutoff happen on the rperf side; the output is a
+flat table that an LLM can analyze directly — no tree walking required.
+
+`rperf report --format table FILE` columns (self_pct descending, top 50
+plus an `(other)` aggregate row):
+
+    method  self_pct  total_pct  self_ms
+
+`rperf diff --format table BASE HEAD` columns (|delta_pt| descending,
+top 50; delta_pt = self_pct_head - self_pct_base in percentage points):
+
+    method  self_pct_base  self_pct_head  delta_pt
+
+Per-method allocation data does not exist in sampling profiles, so
+allocation counts appear only in the summary (whole-profile delta).
+
+The last TSV line is `# summary` with tab-separated key=value pairs
+(total_ms / allocated_objects / GC counts; base/head/delta for diff).
+With `table-json`, the output is a JSON array of row objects whose last
+element is `{"summary": {...}}`.
+
+Feed the result to an LLM:
+
+    rperf diff --format table base.json.gz head.json.gz | claude -p "回帰の原因を分析して"
+
+### Multi-process profiling
+
+By default, rperf profiles forked and spawned Ruby child processes.
+Profiles from all processes are merged into a single output. Each child
+process's samples are tagged with a `%pid` label for per-process filtering.
+
+    # Profile a preforking server (Unicorn, Puma, etc.)
+    rperf stat -m wall bundle exec unicorn
+    rperf record -m wall -o profile.json.gz bundle exec unicorn
+
+    # Profile with fork
+    rperf stat ruby -e '4.times { fork { work } }; Process.waitall'
+
+    # Disable child process tracking
+    rperf stat --no-inherit ruby app.rb
+
+How it works:
+
+- On fork: `Process._fork` hook restarts profiling in the child and sets
+  a `%pid` label. When the child exits, its profile is saved to a
+  temporary session directory.
+- On spawn/system: The spawned Ruby process inherits `RUBYLIB` (pointing
+  to rperf's lib directory) and `RUBYOPT=-rrperf`, plus `RPERF_SESSION_DIR`.
+  It auto-starts profiling and writes its profile to the session directory.
+- When the root process exits, it aggregates all profiles from the
+  session directory into a single output (stat report or file).
+- The session directory is cleaned up after aggregation.
+
+Limitations:
+
+- Daemon children (Process.daemon) that outlive the parent will have
+  their profiles lost, since the parent aggregates and cleans up the
+  session directory at exit.
+- Cross-process snapshots (Rperf.snapshot) are not supported; snapshots
+  only cover the current process.
+- Only Ruby child processes are profiled; non-Ruby children (shell
+  scripts, Python, etc.) are not affected.
+- Child processes that use rperf independently (Rperf.start in their
+  own code) will conflict with the inherited auto-start session.
+  Such programs should clear RPERF_ENABLED from their environment
+  before requiring rperf.
+
 ### Examples
 
     rperf record ruby app.rb
@@ -81,15 +221,22 @@ Default (no flag): opens diff in browser.
     rperf record -o profile.collapsed ruby app.rb
     rperf record -o profile.txt ruby app.rb
     rperf record -p ruby app.rb
+    rperf record --snapshot-dir ./profiles ruby app.rb
+    rperf record --label ci=github-actions --label pr=123 ruby app.rb
     rperf stat ruby app.rb
     rperf stat --report ruby app.rb
     rperf stat -o profile.pb.gz ruby app.rb
+    rperf stat -m wall bundle exec unicorn
+    rperf stat --no-inherit ruby app.rb
     rperf exec ruby app.rb
     rperf exec -m cpu ruby app.rb
     rperf report
     rperf report --top profile.pb.gz
+    rperf report --format table profile.json.gz
+    rperf report ./profiles/
     rperf diff before.pb.gz after.pb.gz
     rperf diff --top before.pb.gz after.pb.gz
+    rperf diff --format table before.json.gz after.json.gz
 
 ## RUBY API
 
@@ -114,12 +261,17 @@ Rperf.save("profile.txt", data)
 
 ### Rperf.start parameters
 
-    frequency:  Sampling frequency in Hz (Integer, default: 1000)
+    frequency:  Sampling frequency in Hz (Integer, 1..10000, default: 1000)
     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:     :json, :pprof, :collapsed, :text, or nil for auto-detect (Symbol or nil)
     defer:      Start with timer paused; use Rperf.profile to activate (default: false)
+    inherit:    Child process tracking: :fork (default), true (fork+spawn), false (none)
+                Note: CLI defaults to true (--no-inherit to disable)
+    signal:     Timer signal (Linux only): nil (default, auto), false (use nanosleep),
+                or a signal number (Integer)
+    aggregate:  Aggregate samples in C (default: true). false returns raw per-sample data
 
 ### Rperf.stop return value
 
@@ -128,24 +280,30 @@ nil if profiler was not running; otherwise a Hash:
 ```ruby
 { mode: :cpu,                      # or :wall
   frequency: 500,
-  sampling_count: 1234,
+  trigger_count: 1300,             # number of timer triggers
+  sampling_count: 1234,            # number of timer callbacks (may differ from trigger_count)
   sampling_time_ns: 56789,
   detected_thread_count: 4,        # threads seen during profiling
   start_time_ns: 17740...,         # CLOCK_REALTIME epoch nanos
   duration_ns: 10000000,           # profiling duration in nanos
-  aggregated_samples: [                  # when aggregate: true (default)
+  aggregated_samples: [                  # always present
     [frames, weight, seq, label_set_id], #   frames: [[path, label], ...] deepest-first
     ...                                  #   weight: Integer (nanoseconds, merged per unique stack)
   ],                                     #   seq: Integer (thread sequence, 1-based)
                                          #   label_set_id: Integer (0 = no labels)
   label_sets: [{}, {request: "abc"}, ...], # label set table (index = label_set_id)
-  # --- OR ---
-  raw_samples: [                   # when aggregate: false
-    [frames, weight, seq, label_set_id], # one entry per timer sample (not merged)
-    ...
-  ] }
+  # additionally, when aggregate: false:
+  raw_samples: [                             # one entry per timer sample (not merged)
+    [frames, weight, seq, label_set_id, vm_state],
+    ...                                      #   vm_state: Integer (raw VM state; NOT
+  ] }                                        #   converted to %GVL/%GC labels — only
+                                             #   aggregated_samples gets that conversion)
 ```
 
+With `aggregate: false`, BOTH keys are present: `aggregated_samples` is built
+in Ruby from the raw samples (so encoders always work), and `raw_samples`
+preserves the unmerged per-sample data.
+
 ### Rperf.snapshot(clear: false)
 
 Returns a snapshot of the current profiling data without stopping.
@@ -153,7 +311,9 @@ Only works in aggregate mode (the default). Returns nil if not profiling.
 
 When `clear: true` is given, resets aggregated data after taking the snapshot.
 This enables interval-based profiling where each snapshot covers only the
-period since the last clear.
+period since the last clear. Note: the frame table is intentionally retained
+(frame IDs must stay stable for GC safety and thread data consistency), so
+`unique_frames` may accumulate across intervals.
 
 ```ruby
 Rperf.start(frequency: 1000)
@@ -250,6 +410,22 @@ running). Raises `RuntimeError` if not started, `ArgumentError` without block.
 
 Returns the current thread's labels as a Hash. Empty hash if none set.
 
+### Rperf.running?
+
+Returns true while a profiling session is active (between start and stop).
+
+### Rperf.load(path)
+
+Loads a `.json.gz` or `.json` profile file (saved by `rperf record` or `Rperf.save`)
+and returns the parsed data hash (same format as `Rperf.stop` / `Rperf.snapshot`).
+Gzip is auto-detected by magic bytes, so both compressed and plain files work.
+Warns to stderr if the file was saved by a different rperf version.
+
+```ruby
+data = Rperf.load("rperf.json.gz")   # gzip compressed
+data = Rperf.load("profile.json")    # plain text JSON
+```
+
 ### Rperf.save(path, data, format: nil)
 
 Writes data to path. format: :json, :pprof, :collapsed, or :text.
@@ -269,6 +445,8 @@ use Rperf::RackMiddleware
 
 The middleware uses `Rperf.profile` to activate timer and set labels.
 Start profiling separately. Option: `label_key:` (default: `:endpoint`).
+When the profiler is not running, the middleware is a no-op (passes the
+request straight through).
 
 ### Rperf::ActiveJobMiddleware
 
@@ -312,7 +490,19 @@ 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)`.
+`Rperf::Viewer.instance.add_snapshot(data)`. Snapshots carry the same
+meta/summary as saved profiles, so when more than one snapshot exists the
+UI shows the time-travel sidebar (list, diff, pin/sparkline, j/k) — see
+"Time-travel mode" under the report subcommand.
+`add_snapshot_dir(dir)` loads a directory of saved profiles (lazy-loaded;
+`max_snapshots` does not apply to directory entries).
+
+The UI fetches data from `<path>/snapshots` (list) and
+`<path>/snapshots/<id>` (body). The URLs are replaceable at runtime:
+define `window.RPERF_DATA_SOURCE` (with `listUrl()` / `snapshotUrl(id)`,
+and optionally an async `onAuthError(url)` hook that returns a fresh URL
+when a fetch hits HTTP 403, e.g. an expired signed URL) before the viewer
+script runs to read snapshots from another source.
 
 #### Typical setup with RackMiddleware and periodic snapshots
 
@@ -358,7 +548,8 @@ end
 
 #### UI tabs
 
-- **Flamegraph** — Interactive flamegraph (d3-flame-graph). Click to zoom.
+- **Flamegraph** — Interactive flamegraph (d3-flame-graph). Click to zoom;
+  Shift+click to pin a method (sparkline across snapshots in the sidebar).
 - **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.
@@ -389,15 +580,80 @@ Tag keys are sorted alphabetically (`%`-prefixed VM state keys appear first).
 
 ### json (default) — rperf native format
 
-Gzip-compressed JSON representation of the internal data hash
+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`
+Extension convention: `.json.gz` (gzip-compressed, default) or `.json` (plain text).
 View with: `rperf report` (opens rperf viewer in browser, no Go required).
 Load programmatically: `data = Rperf.load("rperf.json.gz")`
 
+#### Profile metadata (meta / summary)
+
+JSON profiles embed two extra top-level keys, written FIRST in the file so
+tools can list profiles by decompressing only the head (`Rperf.read_meta`):
+
+```json
+{
+  "meta": {
+    "format_version": 1,
+    "created_at": "2026-06-12T10:00:00Z",
+    "ruby_version": "3.5.0",
+    "rperf_version": "0.10.0",
+    "mode": "cpu",
+    "hostname": "...",
+    "git": {
+      "sha": "88e1a40...",
+      "branch": "main",
+      "subject": "Add nested includes support",
+      "committed_at": "2026-06-09T...",
+      "dirty": false
+    },
+    "labels": { "ci": "github-actions", "pr": "123" }
+  },
+  "summary": {
+    "total_ms": 2001.8,
+    "cpu_ms": 2023.3,
+    "gc_count_minor": 2,
+    "gc_count_major": 2,
+    "gc_ms": 3.0,
+    "allocated_objects": 48741,
+    "freed_objects": 27034,
+    "maxrss_mb": 16,
+    "samples": 1999,
+    "top_methods": [
+      { "name": "Object#fibonacci", "self_pct": 99.9, "total_pct": 99.9 }
+    ]
+  }
+}
+```
+
+Notes:
+
+- `git` is omitted outside a git repository (never an error). In GitHub
+  Actions, `GITHUB_SHA` / `GITHUB_REF_NAME` take priority over git commands.
+  The CLI collects git info before launching the profiled command, so a
+  `chdir` in the app cannot point git at the wrong repository.
+- `git.dirty` is true when the working tree has uncommitted changes.
+- GC counts and allocation counts are deltas over the profiled period
+  (`GC.stat` baselines are captured at `Rperf.start`). `maxrss_mb` is the
+  process-lifetime peak (no period delta is possible; on macOS the value
+  comes from `ps -o rss=` and is the current RSS, not the peak).
+- `summary.top_methods` lists up to 50 methods by self time.
+- In multi-process profiling, GC/memory stats come from the root process
+  only (same policy as `rperf stat`); time and sample stats are aggregated.
+- Files saved by older rperf versions (no `meta`) remain loadable; viewers
+  treat them as unknown snapshots.
+- pprof / collapsed / text exports do not contain meta.
+
+### Rperf.read_meta(path)
+
+Reads only `meta` / `summary` from a `.json(.gz)` profile without parsing
+the sample body (fast even for large files). Returns
+`{ meta: Hash|nil, summary: Hash|nil }`, or nil for pre-meta files and
+unreadable files.
+
 ### pprof
 
 Gzip-compressed protobuf. Standard pprof format.
@@ -459,7 +715,8 @@ Example output:
 
 Format is auto-detected from the output file extension:
 
-    .json.gz    → json (rperf native, default)
+    .json.gz    → json (rperf native, gzip compressed, default)
+    .json       → json (plain text, readable by jq)
     .pb.gz      → pprof
     .collapsed  → collapsed
     .txt        → text
@@ -485,8 +742,8 @@ 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.
+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:
 
@@ -566,7 +823,7 @@ Or convert to text with pprof CLI:
 
     go tool pprof -text profile.pb.gz
     go tool pprof -top profile.pb.gz
-    go tool pprof -flame profile.pb.gz
+    go tool pprof -http=:8080 profile.pb.gz   # web UI (includes flame graph view)
 
 ## ENVIRONMENT VARIABLES
 
@@ -581,6 +838,15 @@ Used internally by the CLI to pass options to the auto-started profiler:
     RPERF_SIGNAL=N|false  Timer signal number or 'false' for nanosleep (Linux only)
     RPERF_STAT=1          Enable stat mode (used by rperf stat)
     RPERF_STAT_REPORT=1   Include profile tables in stat output
+    RPERF_AGGREGATE=0     Disable C-level sample aggregation (raw mode)
+    RPERF_DEFER=1         Start with timer paused; use Rperf.profile to activate
+    RPERF_TMPDIR=path     Base directory for session directories (overrides default tmpdir)
+
+Internal variables (set automatically by the CLI — not for manual use):
+
+    RPERF_SESSION_DIR=path   Session directory for multi-process profiling
+    RPERF_ROOT_PROCESS=pid   Marks the root aggregating process
+    RPERF_STAT_COMMAND=str   Command string displayed in stat output
 
 ## TIPS