rperf 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 520b1f5fd883bd68232c2b714aa1a66dbf811a3f3d2b2b54c212233f4a97d1c4
-  data.tar.gz: 11f5a6f52444abebc28a41055726eab246d623457c85001ba737fcb790b20cea
+  metadata.gz: 7182c353301aa38afde2d65928219c46cee3e777b49842bf60331dd40e7b3ab2
+  data.tar.gz: ebb30b807d9b86a7ff48090bc5990d6bdcc0c9951f80b21758df2413bdbd39f2
 SHA512:
-  metadata.gz: 88c50af83f66f569739bd37377cc2dfc51f7bc6970243cb14bf5b2a7defc9ab6fee60f0e43f85e30f5acf0a315c2774ff0fd88b36c6ed913a5e9d6ef4aa63352
-  data.tar.gz: 63359d42f26529e726ef070f335e726b62bef23b0c897092b6010385ae91d01790039da35e300e734c4dfebb796c8b687759bdce395e13fcb778dca89c0318a1
+  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

@@ -69,7 +69,7 @@ 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
 
@@ -77,6 +77,8 @@ rperf report --top profile.json.gz           # print top functions to terminal
 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
@@ -156,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.
@@ -170,16 +172,16 @@ 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?
 
@@ -189,13 +191,13 @@ rperf hooks GVL and GC events to attribute non-CPU time. These are recorded as l
 - **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 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,6 +26,8 @@ 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)
+    --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
 
 ### stat: Run command and print performance summary to stderr.
@@ -36,6 +40,8 @@ Uses wall mode by default. No file output by default.
     --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 +50,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.
@@ -53,6 +63,8 @@ Like `stat --report`. Uses wall mode by default. No file output by default.
     -m, --mode MODE         cpu or wall (default: wall)
     --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 +74,70 @@ and flat/cumulative top-50 function tables.
 
     --top                   Print top functions by flat time
     --text                  Print text report
+    --html                  Output static HTML viewer to stdout
 
 Default (no flag): opens interactive web UI in browser.
 Default file: rperf.json.gz
 
-### diff: Compare two pprof profiles (target - base). Requires Go.
+`--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.
+
+Accepts `.json.gz` (auto-converted to pprof) or `.pb.gz` files.
 
     --top                   Print top functions by diff
     --text                  Print text diff report
 
 Default (no flag): opens diff in browser.
 
+### 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
@@ -84,6 +149,8 @@ Default (no flag): opens diff in browser.
     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
@@ -114,12 +181,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,7 +200,8 @@ 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
@@ -153,7 +226,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 +325,18 @@ running). Raises `RuntimeError` if not started, `ArgumentError` without block.
 
 Returns the current thread's labels as a Hash. Empty hash if none set.
 
+### 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.
@@ -389,12 +476,12 @@ 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")`
 
@@ -459,7 +546,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 +573,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:
 
@@ -581,6 +669,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
 

data/exe/rperf

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 require "optparse"
 require "socket"
+require "fileutils"
 
 def find_available_port
   server = TCPServer.new("localhost", 0)
@@ -23,6 +24,12 @@ def run_pprof_subcommand(name, banner, min_files:)
       mode = :text
     end
 
+    if min_files == 1
+      opts.on("--html", "Output static HTML viewer to stdout") do
+        mode = :html
+      end
+    end
+
     opts.on("-h", "--help", "Show this help") do
       puts opts
       exit
@@ -31,7 +38,7 @@ def run_pprof_subcommand(name, banner, min_files:)
 
   begin
     parser.order!(ARGV)
-  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+  rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::NeedlessArgument => e
     $stderr.puts e.message
     $stderr.puts parser
     exit 1
@@ -63,13 +70,15 @@ def run_pprof_subcommand(name, banner, min_files:)
   yield mode, files
 end
 
-HELP_TEXT = File.read(File.expand_path("../docs/help.md", __dir__))
+def self.help_text
+  @help_text ||= File.read(File.expand_path("../docs/help.md", __dir__))
+end
 
 USAGE = "Usage: rperf record [options] command [args...]\n" \
        "       rperf stat [options] command [args...]\n" \
        "       rperf exec [options] command [args...]\n" \
        "       rperf report [options] [file]\n" \
-       "       rperf diff [options] base.pb.gz target.pb.gz\n" \
+       "       rperf diff [options] base target\n" \
        "       rperf help\n"
 
 # Handle top-level flags before subcommand parsing
@@ -89,7 +98,7 @@ subcommand = ARGV.shift
 
 case subcommand
 when "help"
-  puts HELP_TEXT
+  puts help_text
   exit
 when "report"
   run_pprof_subcommand("report",
@@ -114,6 +123,9 @@ when "report"
       when :text
         $stdout.puts Rperf::Text.encode(data)
         exit
+      when :html
+        $stdout.puts Rperf::Viewer.render_static_html(data)
+        exit
       end
 
       port = find_available_port
@@ -225,6 +237,7 @@ signal = nil
 verbose = false
 aggregate = true
 stat_report = (subcommand == "exec")
+inherit = true
 
 parser = OptionParser.new do |opts|
   opts.banner = case subcommand
@@ -279,6 +292,10 @@ parser = OptionParser.new do |opts|
     end
   end
 
+  opts.on("--no-inherit", "Do not profile forked/spawned child processes (default: inherit)") do
+    inherit = false
+  end
+
   opts.on("-v", "--verbose", "Print sampling statistics to stderr") do
     verbose = true
   end
@@ -293,7 +310,7 @@ end
 
 begin
   parser.order!(ARGV)
-rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::NeedlessArgument => e
   $stderr.puts e.message
   $stderr.puts parser
   exit 1
@@ -328,7 +345,9 @@ if signal && signal != "false"
   end
 end
 
-# Add lib dir to RUBYLIB so -rrperf can find the extension
+# Add lib dir to RUBYLIB so -rrperf can find the correct version.
+# RUBYLIB handles spaces in paths safely (PATH_SEPARATOR delimited).
+# RUBYOPT -r<path> does not support spaces, so we use RUBYLIB + -rrperf.
 lib_dir = File.expand_path("../lib", __dir__)
 ENV["RUBYLIB"] = [lib_dir, ENV["RUBYLIB"]].compact.join(File::PATH_SEPARATOR)
 ENV["RUBYOPT"] = "-rrperf #{ENV['RUBYOPT']}".strip
@@ -347,4 +366,14 @@ if subcommand == "stat" || subcommand == "exec"
   ENV["RPERF_STAT_REPORT"] = "1" if stat_report
 end
 
+# Multi-process (fork) support: create a session directory for aggregation
+if inherit
+  require_relative "../lib/rperf"
+  session_dir = Rperf.send(:_create_session_dir, clean_stale: true)
+  if session_dir
+    ENV["RPERF_ROOT_PROCESS"] = Process.pid.to_s
+    ENV["RPERF_SESSION_DIR"] = session_dir
+  end
+end
+
 exec(*ARGV)