sperf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aecc23432b8dba72018c524b1fb6653a0c83a44e9e8b2c9af17c87cde20b648b
+  data.tar.gz: fbdf1dddcb5b8fef86e358f315a801478bfcad7768d8f28cbcf82726c67d529c
+SHA512:
+  metadata.gz: ff265b78dd2e237dac4d07a32b7459e07e73d77504347556945878e4addc1ccf89c47c409824591ff800cbe5605a863ae536b200c7f7c5eca5d06bbbd4ca6c05
+  data.tar.gz: 950c3860737f37a9d57d15dae9db259635ebe94494096ad06c0489ab6c028827ea2b24d7e0046462e3b57ea546173993b2ed3e0c910bc677828b23b01ed718e9

data/README.md

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="sperf logo" width="260">
+</p>
+
+# sperf
+
+A safepoint-based sampling performance profiler for Ruby. Uses actual time deltas as sample weights to correct safepoint bias.
+
+- 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)
+
+## Quick Start
+
+```bash
+gem install sperf
+
+# Performance summary (wall mode, prints to stderr)
+sperf stat ruby app.rb
+
+# Profile to file
+sperf record ruby app.rb                              # → sperf.data (pprof, cpu mode)
+sperf record -m wall -o profile.pb.gz ruby server.rb   # wall mode, custom output
+
+# View results (report/diff require Go: https://go.dev/dl/)
+sperf report                      # open sperf.data in browser
+sperf report --top profile.pb.gz  # print top functions to terminal
+
+# Compare two profiles
+sperf diff before.pb.gz after.pb.gz        # open diff in browser
+sperf diff --top before.pb.gz after.pb.gz  # print diff to terminal
+```
+
+### Ruby API
+
+```ruby
+require "sperf"
+
+# Block form — profiles and saves to file
+Sperf.start(output: "profile.pb.gz", frequency: 500, mode: :cpu) do
+  # code to profile
+end
+
+# Manual start/stop
+Sperf.start(frequency: 1000, mode: :wall)
+# ...
+data = Sperf.stop
+Sperf.save("profile.pb.gz", data)
+```
+
+### Environment Variables
+
+Profile without code changes (e.g., Rails):
+
+```bash
+SPERF_ENABLED=1 SPERF_MODE=wall SPERF_OUTPUT=profile.pb.gz ruby app.rb
+```
+
+Run `sperf help` for full documentation (all options, output interpretation, diagnostics guide).
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `sperf record` | Profile a command and save to file |
+| `sperf stat` | Profile a command and print summary to stderr |
+| `sperf report` | Open pprof profile with `go tool pprof` (requires Go) |
+| `sperf diff` | Compare two pprof profiles (requires Go) |
+| `sperf help` | Show full reference documentation |
+
+## How It Works
+
+### The Problem
+
+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.
+
+### The Solution
+
+sperf uses **time deltas as sample weights**:
+
+```
+Timer thread (pthread)           VM thread (postponed job)
+─────────────────────           ────────────────────────
+  every 1/frequency sec:          at next safepoint:
+    rb_postponed_job_trigger()  →   sperf_sample_job()
+                                      time_now = read_clock()
+                                      weight = time_now - prev_time
+                                      record(backtrace, weight)
+```
+
+If a safepoint is delayed, the sample carries proportionally more weight. The total weight equals the total time, accurately distributed across call stacks.
+
+### Modes
+
+| Mode | Clock | What it measures |
+|------|-------|------------------|
+| `cpu` (default) | `CLOCK_THREAD_CPUTIME_ID` | CPU time consumed (excludes sleep/I/O) |
+| `wall` | `CLOCK_MONOTONIC` | Real elapsed time (includes everything) |
+
+Use `cpu` to find what consumes CPU. Use `wall` to find what makes things slow (I/O, GVL contention, GC).
+
+### Synthetic Frames (wall mode)
+
+sperf hooks GVL and GC events to attribute non-CPU time:
+
+| Frame | 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 |
+
+## Output Formats
+
+| Format | Extension | Use case |
+|--------|-----------|----------|
+| pprof (default) | `.pb.gz` | `sperf report`, `go tool pprof`, speedscope |
+| collapsed | `.collapsed` | FlameGraph (`flamegraph.pl`), speedscope |
+| text | `.txt` | Human/AI-readable flat + cumulative report |
+
+Format is auto-detected from extension, or set explicitly with `--format`.
+
+## License
+
+MIT

data/exe/sperf

@@ -0,0 +1,457 @@
+#!/usr/bin/env ruby
+require "optparse"
+
+HELP_TEXT = <<'HELP'
+sperf - safepoint-based sampling performance profiler for Ruby
+
+OVERVIEW
+
+  sperf profiles Ruby programs by sampling at safepoints and using actual
+  time deltas (nanoseconds) as weights to correct safepoint bias.
+  POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
+
+CLI USAGE
+
+  sperf record [options] command [args...]
+  sperf stat [options] command [args...]
+  sperf report [options] [file]
+  sperf help
+
+  record: Profile and save to file.
+    -o, --output PATH       Output file (default: sperf.data)
+    -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)
+    -v, --verbose           Print sampling statistics to stderr
+
+  stat: Run command and print performance summary to stderr.
+    Always uses wall mode. No file output by default.
+    -o, --output PATH       Also save profile to file (default: none)
+    -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
+    -v, --verbose           Print additional sampling statistics
+
+    Shows: user/sys/real time, time breakdown (CPU execution, GVL blocked,
+    GVL wait, GC marking, GC sweeping), and top 5 hot functions.
+
+  report: Open pprof profile with go tool pprof. Requires Go.
+    --top                   Print top functions by flat time
+    --text                  Print text report
+    Default (no flag): opens interactive web UI in browser.
+    Default file: sperf.data
+
+  diff: Compare two pprof profiles (target - base). Requires Go.
+    --top                   Print top functions by diff
+    --text                  Print text diff report
+    Default (no flag): opens diff in browser.
+
+  Examples:
+    sperf record ruby app.rb
+    sperf record -o profile.pb.gz ruby app.rb
+    sperf record -m wall -f 500 -o profile.pb.gz ruby server.rb
+    sperf record -o profile.collapsed ruby app.rb
+    sperf record -o profile.txt ruby app.rb
+    sperf stat ruby app.rb
+    sperf stat -o profile.pb.gz ruby app.rb
+    sperf report
+    sperf report --top profile.pb.gz
+    sperf diff before.pb.gz after.pb.gz
+    sperf diff --top before.pb.gz after.pb.gz
+
+RUBY API
+
+  require "sperf"
+
+  # Block form (recommended) — profiles the block and writes to file
+  Sperf.start(output: "profile.pb.gz", frequency: 500, mode: :cpu) do
+    # code to profile
+  end
+
+  # Manual start/stop — returns data hash for programmatic use
+  Sperf.start(frequency: 1000, mode: :wall)
+  # ... code to profile ...
+  data = Sperf.stop
+
+  # Save data to file later
+  Sperf.save("profile.pb.gz", data)
+  Sperf.save("profile.collapsed", data)
+  Sperf.save("profile.txt", data)
+
+  Sperf.start parameters:
+    frequency:  Sampling frequency in Hz (Integer, 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:     :pprof, :collapsed, :text, or nil for auto-detect (Symbol or nil)
+
+  Sperf.stop return value:
+    nil if profiler was not running; otherwise a Hash:
+      { mode: :cpu,             # or :wall
+        frequency: 500,
+        sampling_count: 1234,
+        sampling_time_ns: 56789,
+        samples: [              # Array of [frames, weight]
+          [frames, weight],     #   frames: [[path, label], ...] deepest-first
+          ...                   #   weight: Integer (nanoseconds)
+        ] }
+
+  Sperf.save(path, data, format: nil)
+    Writes data to path. format: :pprof, :collapsed, or :text.
+    nil auto-detects from extension.
+
+PROFILING MODES
+
+  cpu   Measures per-thread CPU time via Linux thread clock.
+        Use for: finding functions that consume CPU cycles.
+        Ignores time spent sleeping, in I/O, or waiting for GVL.
+
+  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).
+
+OUTPUT FORMATS
+
+  pprof (default)
+    Gzip-compressed protobuf. Standard pprof format.
+    Extension convention: .pb.gz
+    View with: go tool pprof, pprof-rs, or speedscope (via import).
+
+  collapsed
+    Plain text. One line per unique stack: "frame1;frame2;...;leaf weight\n"
+    Frames are semicolon-separated, bottom-to-top. Weight in nanoseconds.
+    Extension convention: .collapsed
+    Compatible with: FlameGraph (flamegraph.pl), speedscope.
+
+  text
+    Human/AI-readable report. Shows total time, then flat and cumulative
+    top-N tables sorted by weight descending. No parsing needed.
+    Extension convention: .txt
+    Example output:
+      Total: 1523.4ms (cpu)
+      Samples: 4820, Frequency: 500Hz
+
+      Flat:
+           820.3ms  53.8%  Array#each (app/models/user.rb)
+           312.1ms  20.5%  JSON.parse (lib/json/parser.rb)
+           ...
+
+      Cumulative:
+          1401.2ms  92.0%  UsersController#index (app/controllers/users_controller.rb)
+           ...
+
+  Format is auto-detected from the output file extension:
+    .collapsed → collapsed
+    .txt       → text
+    anything else → pprof
+  The --format flag (CLI) or format: parameter (API) overrides auto-detect.
+
+SYNTHETIC FRAMES
+
+  In wall mode, sperf adds synthetic frames that represent non-CPU time:
+
+  [GVL blocked]   Time the thread spent 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
+                   becoming ready. Indicates GVL contention. Same stack.
+
+  In both modes, GC time is tracked:
+
+  [GC marking]    Time spent in GC marking phase (wall time).
+  [GC sweeping]   Time spent in GC sweeping phase (wall time).
+
+  These always appear as the leaf (deepest) frame in a sample.
+
+INTERPRETING RESULTS
+
+  Weight unit is always nanoseconds regardless of mode.
+
+  Flat time: weight attributed directly to a function (it was the leaf).
+  Cumulative time: weight for all samples where the function appears
+  anywhere in the stack.
+
+  High flat time → the function itself is expensive.
+  High cum but low flat → the function calls expensive children.
+
+  To convert: 1_000_000 ns = 1 ms, 1_000_000_000 ns = 1 s.
+
+DIAGNOSING COMMON PERFORMANCE PROBLEMS
+
+  Problem: high CPU usage
+    Mode: cpu
+    Look for: functions with high flat cpu time.
+    Action: optimize the hot function or call it less.
+
+  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
+    or move work to Ractors / child processes.
+
+  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.
+
+  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.
+
+READING COLLAPSED STACKS PROGRAMMATICALLY
+
+  Each line: "bottom_frame;...;top_frame weight_ns"
+  Parse with:
+    File.readlines("profile.collapsed").each do |line|
+      stack, weight = line.rpartition(" ").then { |s, _, w| [s, w.to_i] }
+      frames = stack.split(";")
+      # frames[0] is bottom (main), frames[-1] is leaf (hot)
+    end
+
+READING PPROF PROGRAMMATICALLY
+
+  Decompress + parse protobuf:
+    require "zlib"; require "stringio"
+    raw = Zlib::GzipReader.new(StringIO.new(File.binread("profile.pb.gz"))).read
+    # raw is a protobuf binary; use google-protobuf gem or pprof tooling.
+
+  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
+
+ENVIRONMENT VARIABLES
+
+  Used internally by the CLI to pass options to the auto-started profiler:
+    SPERF_ENABLED=1       Enable auto-start on require
+    SPERF_OUTPUT=path     Output file path
+    SPERF_FREQUENCY=hz    Sampling frequency
+    SPERF_MODE=cpu|wall   Profiling mode
+    SPERF_FORMAT=fmt      pprof, collapsed, or text
+    SPERF_VERBOSE=1       Print statistics
+
+TIPS
+
+  - Default frequency (1000 Hz) works well for most cases; overhead is < 0.2%.
+  - For long-running production profiling, lower frequency (100-500) reduces overhead further.
+  - Profile representative workloads, not micro-benchmarks.
+  - Compare cpu and wall profiles to distinguish CPU-bound from I/O-bound.
+  - The verbose flag (-v) shows sampling overhead and top functions on stderr.
+HELP
+
+USAGE = "Usage: sperf record [options] command [args...]\n" \
+       "       sperf stat [options] command [args...]\n" \
+       "       sperf report [options] [file]\n" \
+       "       sperf diff [options] base.pb.gz target.pb.gz\n" \
+       "       sperf help\n"
+
+# Handle top-level flags before subcommand parsing
+case ARGV.first
+when "-v", "--version"
+  require "sperf"
+  puts "sperf #{Sperf::VERSION}"
+  exit
+when "-h", "--help"
+  puts USAGE
+  puts
+  puts "Run 'sperf help' for full documentation"
+  exit
+end
+
+subcommand = ARGV.shift
+
+case subcommand
+when "help"
+  puts HELP_TEXT
+  exit
+when "report"
+  # sperf report: wrapper around go tool pprof
+  report_mode = :http  # default: open in browser
+  report_file = nil
+
+  report_parser = OptionParser.new do |opts|
+    opts.banner = "Usage: sperf report [options] [file]\n" \
+                  "       Opens pprof profile in browser (default) or prints summary.\n" \
+                  "       Default file: sperf.data"
+
+    opts.on("--top", "Print top functions by flat time") do
+      report_mode = :top
+    end
+
+    opts.on("--text", "Print text report") do
+      report_mode = :text
+    end
+
+    opts.on("-h", "--help", "Show this help") do
+      puts opts
+      exit
+    end
+  end
+
+  begin
+    report_parser.order!(ARGV)
+  rescue OptionParser::InvalidOption => e
+    $stderr.puts e.message
+    $stderr.puts report_parser
+    exit 1
+  end
+
+  report_file = ARGV.shift || "sperf.data"
+
+  unless File.exist?(report_file)
+    $stderr.puts "File not found: #{report_file}"
+    exit 1
+  end
+
+  unless system("go", "version", out: File::NULL, err: File::NULL)
+    $stderr.puts "'go' command not found. Install Go to use 'sperf report'."
+    $stderr.puts "  https://go.dev/dl/"
+    exit 1
+  end
+
+  case report_mode
+  when :top
+    exec("go", "tool", "pprof", "-top", report_file)
+  when :text
+    exec("go", "tool", "pprof", "-text", report_file)
+  else
+    exec("go", "tool", "pprof", "-http=:0", report_file)
+  end
+when "diff"
+  # sperf diff: compare two pprof profiles via go tool pprof -diff_base
+  diff_mode = :http
+  diff_parser = OptionParser.new do |opts|
+    opts.banner = "Usage: sperf diff [options] base.pb.gz target.pb.gz\n" \
+                  "       Compare two pprof profiles (shows target - base)."
+
+    opts.on("--top", "Print top functions by diff") do
+      diff_mode = :top
+    end
+
+    opts.on("--text", "Print text diff report") do
+      diff_mode = :text
+    end
+
+    opts.on("-h", "--help", "Show this help") do
+      puts opts
+      exit
+    end
+  end
+
+  begin
+    diff_parser.order!(ARGV)
+  rescue OptionParser::InvalidOption => e
+    $stderr.puts e.message
+    $stderr.puts diff_parser
+    exit 1
+  end
+
+  if ARGV.size < 2
+    $stderr.puts "Two profile files required."
+    $stderr.puts diff_parser
+    exit 1
+  end
+
+  base_file, target_file = ARGV.shift(2)
+
+  [base_file, target_file].each do |f|
+    unless File.exist?(f)
+      $stderr.puts "File not found: #{f}"
+      exit 1
+    end
+  end
+
+  unless system("go", "version", out: File::NULL, err: File::NULL)
+    $stderr.puts "'go' command not found. Install Go to use 'sperf diff'."
+    $stderr.puts "  https://go.dev/dl/"
+    exit 1
+  end
+
+  case diff_mode
+  when :top
+    exec("go", "tool", "pprof", "-top", "-diff_base=#{base_file}", target_file)
+  when :text
+    exec("go", "tool", "pprof", "-text", "-diff_base=#{base_file}", target_file)
+  else
+    exec("go", "tool", "pprof", "-http=:0", "-diff_base=#{base_file}", target_file)
+  end
+when "record", "stat"
+  # continue below
+else
+  $stderr.puts "Unknown subcommand: #{subcommand.inspect}" if subcommand
+  $stderr.puts USAGE
+  exit 1
+end
+
+output = (subcommand == "stat") ? nil : "sperf.data"
+frequency = 1000
+mode = (subcommand == "stat") ? "wall" : "cpu"
+format = nil
+verbose = false
+
+parser = OptionParser.new do |opts|
+  opts.banner = USAGE
+
+  opts.on("-o", "--output PATH", "Output file#{subcommand == 'stat' ? ' (default: none)' : ' (default: sperf.data)'}") do |v|
+    output = v
+  end
+
+  opts.on("-f", "--frequency HZ", Integer, "Sampling frequency in Hz (default: 1000)") do |v|
+    frequency = v
+  end
+
+  if subcommand == "record"
+    opts.on("-m", "--mode MODE", %w[cpu wall], "Profiling mode: cpu or wall (default: cpu)") do |v|
+      mode = v
+    end
+
+    opts.on("--format FORMAT", %w[pprof collapsed text],
+            "Output format: pprof, collapsed, or text (default: auto from extension)") do |v|
+      format = v
+    end
+  end
+
+  opts.on("-v", "--verbose", "Print sampling statistics to stderr") do
+    verbose = true
+  end
+
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    puts
+    puts "Run 'sperf help' for full documentation (modes, formats, diagnostics guide, etc.)"
+    exit
+  end
+end
+
+begin
+  parser.order!(ARGV)
+rescue OptionParser::InvalidOption => e
+  $stderr.puts e.message
+  $stderr.puts parser
+  exit 1
+end
+
+if ARGV.empty?
+  $stderr.puts "No command specified."
+  $stderr.puts parser
+  exit 1
+end
+
+# Add lib dir to RUBYLIB so -rsperf can find the extension
+lib_dir = File.expand_path("../lib", __dir__)
+ENV["RUBYLIB"] = [lib_dir, ENV["RUBYLIB"]].compact.join(File::PATH_SEPARATOR)
+ENV["RUBYOPT"] = "-rsperf #{ENV['RUBYOPT']}".strip
+ENV["SPERF_ENABLED"] = "1"
+ENV["SPERF_OUTPUT"] = output if output
+ENV["SPERF_FREQUENCY"] = frequency.to_s
+ENV["SPERF_MODE"] = mode
+ENV["SPERF_FORMAT"] = format if format
+ENV["SPERF_VERBOSE"] = "1" if verbose
+
+if subcommand == "stat"
+  ENV["SPERF_STAT"] = "1"
+  ENV["SPERF_STAT_COMMAND"] = ARGV.join(" ")
+end
+
+exec(*ARGV)

data/ext/sperf/extconf.rb

@@ -0,0 +1,6 @@
+require "mkmf"
+
+have_header("pthread.h") or abort "pthread.h not found"
+have_library("pthread") or abort "libpthread not found"
+
+create_makefile("sperf")