rperf 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab923fe1fc0a0d6928941271cdffc979012af73d6d0bd0aa5c5d43a95e9451c2
-  data.tar.gz: 74a0200ec71ae3743d2b99d578df0b484d23dea57285385209e23b0748a95564
+  metadata.gz: 497392cfda8e82d1c37aadd0953b4c73b6bfb09870e6c612c1fd5fced0e3d24f
+  data.tar.gz: 6960be209fc3d4aac0f268378c5b7e1399027da0c5b7f498bcb4be0662012d62
 SHA512:
-  metadata.gz: b2d95c3e58fd883efebfcad8506a5249dee8c7322fb53e75a25afcd5050bbb1885fb620eef18a86e74fa54cb542ba83b1761f13630746862c619477e022b09db
-  data.tar.gz: ee4236170102e0be1cd13749389a29679ba7361c4c77db98ed708e9b509e8e1c28ba3b47a2d8a4b704ada2fe5a11859bc61c0476d8f061fbd43703168232f5f6
+  metadata.gz: '09fc32b7577ac9544a846c86c37a7ad11e9de00a27bbb0bbd25cbc2fcabe04e74741c64f9fb3cfe1a9663145e058215272a247766c7b8106218eda80cbcd838f'
+  data.tar.gz: 9d13e685c5a293c4d9033376509bf4b5c762a5f5155a2d5dd6e838d5a55dc79b9ef7d9521a5bcf65eac88a683f0e20cd7e5dac2680134aa565c709eb48452e40

data/README.md

@@ -2,25 +2,66 @@
   <img src="docs/logo.svg" alt="rperf logo" width="260">
 </p>
 
-# rperf
+<h1 align="center">rperf</h1>
 
-A safepoint-based sampling performance profiler for Ruby. Uses actual time deltas as sample weights to correct safepoint bias.
+<p align="center">
+  <strong>Know where your Ruby spends its time — accurately.</strong><br>
+  A sampling profiler that corrects safepoint bias using real time deltas.
+</p>
 
-- Requires Ruby >= 3.4.0
-- Output: pprof protobuf, collapsed stacks, or text report
-- Modes: CPU time (per-thread) and wall time (with GVL/GC tracking)
-- [Online manual](https://ko1.github.io/rperf/docs/manual/) | [GitHub](https://github.com/ko1/rperf)
+<p align="center">
+  <a href="https://rubygems.org/gems/rperf"><img src="https://img.shields.io/gem/v/rperf.svg" alt="Gem Version"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.4.0-cc342d" alt="Ruby >= 3.4.0">
+  <a href="https://ko1.github.io/rperf/docs/manual/"><img src="https://img.shields.io/badge/docs-manual-blue" alt="Manual"></a>
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+</p>
 
-## Quick Start
+<p align="center">
+  pprof / collapsed stacks / text report &nbsp;·&nbsp; CPU mode & wall mode (GVL + GC tracking)
+</p>
+
+<p align="center">
+  <a href='https://ko1.github.io/rperf/'>Web site</a>,
+  <a href='https://ko1.github.io/rperf/docs/manual/'>Online manual</a>,
+  <a href='https://github.com/ko1/rperf'>GitHub repository</a>
+</p>
+
+## See It in Action
 
 ```bash
-gem install rperf
+$ 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,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)
+
+ Flat:
+         2,034.2 ms 100.0%  Object#fibonacci (fib.rb)
+
+ Cumulative:
+         2,034.2 ms 100.0%  Object#fibonacci (fib.rb)
+         2,034.2 ms 100.0%  <main> (fib.rb)
+
+  2034 samples / 2034 triggers, 0.1% profiler overhead
+```
+
+## Quick Start
+
+```bash
 # Performance summary (wall mode, prints to stderr)
 rperf stat ruby app.rb
 
-# Profile to file
-rperf record ruby app.rb                              # → rperf.data (pprof, cpu mode)
+# 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
 
 # View results (report/diff require Go: https://go.dev/dl/)
@@ -67,19 +108,20 @@ Inspired by Linux `perf` — familiar subcommand interface for profiling workflo
 |---------|-------------|
 | `rperf record` | Profile a command and save to file |
 | `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 help` | Show full reference documentation |
 
 ## How It Works
 
-### The Problem
+### The Challenge: Safepoint Sampling
 
-Ruby's sampling profilers collect stack traces at **safepoints**, not at the exact timer tick. Traditional profilers assign equal weight to every sample, so if a safepoint is delayed 5ms, that delay is invisible.
+Most Ruby profilers (e.g., stackprof) use signal handlers to capture stack traces at the exact moment the timer fires. rperf takes a different approach — it samples at **safepoints** (VM checkpoints), which is safer (no async-signal-safety concerns, reliable access to VM state) but means the sample timing can be delayed. Without correction, this delay would skew the results.
 
-### The Solution
+### The Fix: Weight = Real Time
 
-rperf uses **time deltas as sample weights**:
+rperf uses **actual elapsed time as sample weights** — so delayed samples carry proportionally more weight, and the profile matches reality:
 
 ```
 Timer (signal or thread)         VM thread (postponed job)
@@ -116,23 +158,22 @@ rperf hooks GVL and GC events to attribute non-CPU time:
 | `[GC marking]` | Time in GC mark phase |
 | `[GC sweeping]` | Time in GC sweep phase |
 
-## Pros & Cons
+## Why rperf?
 
-### Pros
+- **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.
+- **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.
 
-- **Safepoint-based, but accurate**: Unlike signal-based profilers (e.g., stackprof), rperf samples at safepoints. Safepoint sampling is safer — no async-signal-safety constraints, so backtraces and VM state (GC phase, GVL ownership) can be inspected reliably. The downside is less precise sampling timing, but rperf compensates by using actual time deltas as sample weights — so the profiling results faithfully reflect where time is actually spent.
-- **GVL & GC visibility** (wall mode): Attributes off-GVL time, GVL contention, and GC phases to the responsible call stacks with synthetic frames.
-- **Low overhead**: No extra thread on Linux (signal-based timer). Sampling overhead is ~1-5 us per sample.
-- **pprof compatible**: Output works with `go tool pprof`, speedscope, and other standard tools.
-- **No code changes required**: Profile any Ruby program via CLI (`rperf stat ruby app.rb`) or environment variables (`RPERF_ENABLED=1`).
-- **perf-like CLI**: Familiar subcommand interface — `record`, `stat`, `report`, `diff` — inspired by Linux perf.
+### Limitations
 
-### Cons
+- **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.
 
-- **Method-level only**: Profiles at the method level, not the line level. You can see which method is slow, but not which line within it.
-- **Ruby >= 3.4.0**: Requires recent Ruby for the internal APIs used (postponed jobs, thread event hooks).
-- **POSIX only**: Linux, macOS, etc. No Windows support.
-- **Safepoint sampling**: Cannot sample inside C extensions or during long-running C calls that don't reach a safepoint. Time spent there is attributed to the next sample.
 
 ## Output Formats
 
@@ -146,4 +187,4 @@ Format is auto-detected from extension, or set explicitly with `--format`.
 
 ## License
 
-MIT
+MIT

data/docs/help.md

@@ -10,6 +10,7 @@ POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
 
     rperf record [options] command [args...]
     rperf stat [options] command [args...]
+    rperf exec [options] command [args...]
     rperf report [options] [file]
     rperf help
 
@@ -41,6 +42,20 @@ Shows: user/sys/real time, time breakdown (CPU execution, GVL blocked,
 GVL wait, GC marking, GC sweeping), GC/memory/OS stats, and profiler overhead.
 Use --report to add flat and cumulative top-50 function tables.
 
+### exec: Run command and print full profile report to stderr.
+
+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)
+    --signal VALUE          Timer signal (Linux only): signal number, or 'false'
+                            for nanosleep thread (default: auto)
+    -v, --verbose           Print additional sampling statistics
+
+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.
 
     --top                   Print top functions by flat time
@@ -67,6 +82,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 exec ruby app.rb
+    rperf exec -m cpu ruby app.rb
     rperf report
     rperf report --top profile.pb.gz
     rperf diff before.pb.gz after.pb.gz
@@ -106,23 +123,139 @@ Rperf.save("profile.txt", data)
 nil if profiler was not running; otherwise a Hash:
 
 ```ruby
-{ mode: :cpu,             # or :wall
+{ mode: :cpu,                      # or :wall
   frequency: 500,
   sampling_count: 1234,
   sampling_time_ns: 56789,
-  start_time_ns: 17740..., # CLOCK_REALTIME epoch nanos
-  duration_ns: 10000000,   # profiling duration in nanos
-  samples: [               # Array of [frames, weight, thread_seq]
-    [frames, weight, seq], #   frames: [[path, label], ...] deepest-first
-    ...                    #   weight: Integer (nanoseconds)
-  ] }                      #   seq: Integer (thread sequence, 1-based)
+  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)
+    [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)
+    ...
+  ] }
+```
+
+### Rperf.snapshot(clear: false)
+
+Returns a snapshot of the current profiling data without stopping.
+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.
+
+```ruby
+Rperf.start(frequency: 1000)
+# ... work ...
+snap = Rperf.snapshot         # read data without stopping
+Rperf.save("snap.pb.gz", snap)
+# ... more work ...
+data = Rperf.stop
+```
+
+Interval-based usage:
+
+```ruby
+Rperf.start(frequency: 1000)
+loop do
+  sleep 10
+  snap = Rperf.snapshot(clear: true)  # each snapshot covers the last 10s
+  Rperf.save("profile-#{Time.now.to_i}.pb.gz", snap)
+end
+```
+
+### Rperf.label(**labels, &block)
+
+Attaches key-value labels to the current thread's samples. Labels appear
+in pprof sample labels, enabling per-context filtering (e.g., per-request).
+If profiling is not running, labels are silently ignored (no error).
+
+```ruby
+# Block form — labels are restored when the block exits
+Rperf.label(request: "abc-123", endpoint: "/api/users") do
+  handle_request   # samples inside get these labels
+end
+# labels are restored to previous state here
+
+# Without block — labels persist until changed
+Rperf.label(request: "abc-123")
+
+# Merge — new labels merge with existing ones
+Rperf.label(phase: "db")      # adds phase, keeps request
+
+# Delete a key — set value to nil
+Rperf.label(request: nil)     # removes request key
+
+# Nested blocks — each block restores its entry state
+Rperf.label(request: "abc") do
+  Rperf.label(phase: "db") do
+    Rperf.labels  #=> {request: "abc", phase: "db"}
+  end
+  Rperf.labels    #=> {request: "abc"}
+end
+Rperf.labels      #=> {}
 ```
 
+In pprof output, use labels for filtering and grouping:
+
+    go tool pprof -tagfocus=request=abc-123 profile.pb.gz
+    go tool pprof -tagroot=request profile.pb.gz
+    go tool pprof -tagleaf=request profile.pb.gz
+
+### 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.
 nil auto-detects from extension.
 
+### Rperf::Middleware (Rack)
+
+Labels samples with the request endpoint. Requires `require "rperf/middleware"`.
+
+```ruby
+# Rails
+Rails.application.config.middleware.use Rperf::Middleware
+
+# Sinatra
+use Rperf::Middleware
+```
+
+The middleware only sets labels — start profiling separately.
+Option: `label_key:` (default: `:endpoint`).
+
+### Rperf::ActiveJobMiddleware
+
+Labels samples with the job class name. Requires `require "rperf/active_job"`.
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  include Rperf::ActiveJobMiddleware
+end
+```
+
+### Rperf::SidekiqMiddleware
+
+Labels samples with the worker class name. Requires `require "rperf/sidekiq"`.
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add Rperf::SidekiqMiddleware
+  end
+end
+```
+
 ## PROFILING MODES
 
 - **cpu** — Measures per-thread CPU time via Linux thread clock.
@@ -152,11 +285,20 @@ Embedded metadata:
 Sample labels:
 
     thread_seq      thread sequence number (1-based, assigned per profiling session)
+    <user labels>   custom key-value labels set via Rperf.label()
 
 View comments: `go tool pprof -comments profile.pb.gz`
 
 Group by thread: `go tool pprof -tagroot=thread_seq profile.pb.gz`
 
+Filter by label: `go tool pprof -tagfocus=request=abc-123 profile.pb.gz`
+
+Group by label (root): `go tool pprof -tagroot=request profile.pb.gz`
+
+Group by label (leaf): `go tool pprof -tagleaf=request profile.pb.gz`
+
+Exclude by label: `go tool pprof -tagignore=request=healthcheck profile.pb.gz`
+
 ### collapsed
 
 Plain text. One line per unique stack: `frame1;frame2;...;leaf weight`

data/exe/rperf

@@ -72,6 +72,7 @@ HELP_TEXT = File.read(File.expand_path("../docs/help.md", __dir__))
 
 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 help\n"
@@ -79,7 +80,7 @@ USAGE = "Usage: rperf record [options] command [args...]\n" \
 # Handle top-level flags before subcommand parsing
 case ARGV.first
 when "-v", "--version"
-  require "rperf"
+  require_relative "../lib/rperf"
   puts "rperf #{Rperf::VERSION}"
   exit
 when "-h", "--help"
@@ -120,7 +121,7 @@ when "diff"
     else            exec("go", "tool", "pprof", "-http=localhost:#{find_available_port}", "-diff_base=#{base_file}", target_file)
     end
   end
-when "record", "stat"
+when "record", "stat", "exec"
   # continue below
 else
   $stderr.puts "Unknown subcommand: #{subcommand.inspect}" if subcommand
@@ -128,22 +129,23 @@ else
   exit 1
 end
 
-output = (subcommand == "stat") ? nil : "rperf.data"
+output = (subcommand == "record") ? "rperf.data" : nil
 frequency = 1000
-mode = (subcommand == "stat") ? "wall" : "cpu"
+mode = (subcommand == "record") ? "cpu" : "wall"
 format = nil
 signal = nil
 verbose = false
 aggregate = true
-stat_report = false
+stat_report = (subcommand == "exec")
 
 parser = OptionParser.new do |opts|
   opts.banner = case subcommand
                 when "record" then "Usage: rperf record [options] command [args...]"
                 when "stat"   then "Usage: rperf stat [options] command [args...]"
+                when "exec"   then "Usage: rperf exec [options] command [args...]"
                 end
 
-  opts.on("-o", "--output PATH", "Output file#{subcommand == 'stat' ? ' (default: none)' : ' (default: rperf.data)'}") do |v|
+  opts.on("-o", "--output PATH", "Output file#{subcommand == 'record' ? ' (default: rperf.data)' : ' (default: none)'}") do |v|
     output = v
   end
 
@@ -151,7 +153,7 @@ parser = OptionParser.new do |opts|
     frequency = v
   end
 
-  default_mode = (subcommand == "stat") ? "wall" : "cpu"
+  default_mode = (subcommand == "record") ? "cpu" : "wall"
   opts.on("-m", "--mode MODE", %w[cpu wall], "Profiling mode: cpu or wall (default: #{default_mode})") do |v|
     mode = v
   end
@@ -208,6 +210,29 @@ if ARGV.empty?
   exit 1
 end
 
+if frequency <= 0
+  $stderr.puts "Error: frequency must be a positive integer (got #{frequency})"
+  exit 1
+end
+
+if frequency > 10_000
+  $stderr.puts "Error: frequency must be <= 10000 (10KHz), got #{frequency}"
+  exit 1
+end
+
+if signal && signal != "false"
+  unless RUBY_PLATFORM =~ /linux/
+    $stderr.puts "Error: signal mode is only supported on Linux"
+    exit 1
+  end
+  sig_num = signal.to_i
+  uncatchable = [Signal.list["KILL"], Signal.list["STOP"]].compact
+  if uncatchable.include?(sig_num)
+    $stderr.puts "Error: signal #{sig_num} (#{Signal.signame(sig_num)}) cannot be caught; use a different signal"
+    exit 1
+  end
+end
+
 # Add lib dir to RUBYLIB so -rrperf can find the extension
 lib_dir = File.expand_path("../lib", __dir__)
 ENV["RUBYLIB"] = [lib_dir, ENV["RUBYLIB"]].compact.join(File::PATH_SEPARATOR)
@@ -221,7 +246,7 @@ ENV["RPERF_VERBOSE"] = "1" if verbose
 ENV["RPERF_SIGNAL"] = signal if signal
 ENV["RPERF_AGGREGATE"] = "0" unless aggregate
 
-if subcommand == "stat"
+if subcommand == "stat" || subcommand == "exec"
   ENV["RPERF_STAT"] = "1"
   ENV["RPERF_STAT_COMMAND"] = ARGV.join(" ")
   ENV["RPERF_STAT_REPORT"] = "1" if stat_report