rperf 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7182c353301aa38afde2d65928219c46cee3e777b49842bf60331dd40e7b3ab2
-  data.tar.gz: ebb30b807d9b86a7ff48090bc5990d6bdcc0c9951f80b21758df2413bdbd39f2
+  metadata.gz: db5be965ca0511ea90e7482309f7dca4dc545a1c83a73f7b3fc08fc4029f9d34
+  data.tar.gz: 4ae2c1fe82a6d754a1ef0b4759ce2b1a2a22370788ce0197b1d269ba0a1e98e4
 SHA512:
-  metadata.gz: d70dde1af1a4c3c9cec02e20981038c465facea4d3da32c32ce26e16cfc402de01f594c0b41386e3095f53603631f930fb2bd133d23b8a5757662d40f117d2a5
-  data.tar.gz: b7868f0237f84a47bda6286c99b7056f47738fb235ede0d21ac8f950feb9b891b1677dff38f25294393766cbe4f742b2eeffe73a43dded92562926db8d5bd392
+  metadata.gz: d99ff20c55b9d359b0dfced5f13cdfaa5f8d4fe1debb5375f2a2de2c7d2ed8a219d2bd4b89c05dbb6ee7fe257b5cf51fa74ad8a85b017db608d6f30d9a5eadf1
+  data.tar.gz: fefb4b168fc733da575e758933083fd169ee6513ac38624f7d89ba8e66b202b4166bf2cb6d8f6e513fe85fb5fec9e31c48231d036ba19439a4e24e09b077460d

data/README.md

@@ -75,9 +75,22 @@ 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"
+
+# Drive rperf without wrapping the command (CI/tooling): source the env, then
+# run your command unchanged — `bundle exec …` stays bundler-managed, plain
+# `ruby …` stays plain. (Run `rperf help` for details.)
+eval "$(rperf record --snapshot-dir ./profiles --print-env)"
+export RPERF_ROOT_PROCESS=$$ && exec ruby app.rb
 ```
 
-On `rperf report`, you can see the profile result like this page: [rprof viewer](https://ko1.github.io/rperf/examples/cpu_intensive_profile.html)
+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
 
@@ -119,10 +132,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
@@ -134,8 +149,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
@@ -188,7 +203,7 @@ rperf hooks GVL and GC events to attribute non-CPU time. These are recorded as l
 - **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.

data/docs/help.md

@@ -26,10 +26,37 @@ 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)
+    --print-env             Print the env rperf would set (export KEY=VALUE lines)
+                            and exit WITHOUT running a command — see below
     -v, --verbose           Print sampling statistics to stderr
 
+#### --print-env: drive rperf without wrapping the command
+
+Instead of `rperf record [options] -- command`, `--print-env` prints the
+environment a profiled process auto-starts from and exits without running
+anything. A wrapper (e.g. a CI script) sources it, makes the process that runs
+the command the session root, and runs the command unchanged — so a
+`bundle exec …` command stays bundler-managed and a plain `ruby …` stays plain;
+rperf is never inserted into the command line.
+
+    eval "$(rperf record --snapshot-dir ./profiles --print-env)"
+    export RPERF_ROOT_PROCESS=$$    # the pid that will exec the command is the root
+    exec ruby app.rb               # runs verbatim; rperf auto-starts via RUBYOPT
+
+`RPERF_ROOT_PROCESS` is not emitted (the caller sets it to the pid that execs
+the command); `RPERF_META_LABELS` is not emitted (set it yourself if you want
+per-run labels). Everything else (`RUBYOPT=-rrperf`, output path, mode,
+frequency, fork session dir, …) is included.
+
+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.
@@ -37,6 +64,7 @@ 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)
@@ -61,6 +89,7 @@ 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
@@ -74,11 +103,44 @@ 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
 
+#### 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
@@ -87,15 +149,48 @@ sites (e.g., GitHub Pages).
 
     rperf report --html profile.json.gz > report.html
 
-### diff: Compare two profiles (target - base). Requires Go.
+### 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.
@@ -146,6 +241,8 @@ Limitations:
     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
@@ -155,8 +252,11 @@ Limitations:
     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
 
@@ -206,19 +306,24 @@ nil if profiler was not running; otherwise a Hash:
   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.
@@ -325,6 +430,10 @@ 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`)
@@ -356,6 +465,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
 
@@ -399,7 +510,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
 
@@ -445,7 +568,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.
@@ -485,6 +609,71 @@ Extension convention: `.json.gz` (gzip-compressed, default) or `.json` (plain te
 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.
@@ -654,7 +843,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