sperf 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125090cb17cacbc9157402fcb9db54117011ccde812da775ea00b6c1f6bee535
-  data.tar.gz: 1430d997988a6538059a0c63be28d4f05f43681d1f2efbd84020490308a5c279
+  metadata.gz: 70bf807f20a737cfb74344fb33a3f0e984d6bdd369ea3ff25f528467df676bb8
+  data.tar.gz: 5fb3a228a2d0a600dcbe648688c2e068c2634c575900aa058e256b55ae14f176
 SHA512:
-  metadata.gz: 17a52cfc856ae47f254bf0df3450ff76cd471703c97e029907abbf639aa9dd8d6971ef8b18acf6a9784b87b295981533776c147b0fc31993e33dcf528cf15a3d
-  data.tar.gz: 6bbad7152c998859f4ec1f07d42eeca8824918ad635b0454fbe13635d9b913ad309b09f8e7c760f5cdd4cc1d32d1316ba50a5fb7c1863e7718cb1df01a2761ad
+  metadata.gz: cd24d9e9c959baf5623a2601f3f46dce83d340d6a1b721dce2da5ddc3066c1d8e1f8cfd3af2aaa72cd85bb230be703dd1823021976e7fbbb1f9f36fd50aac0f8
+  data.tar.gz: df95dbacd3a6eef0794a54503856607becd5028fb0e917d9d2e4b957f68d993ea05c590f57f4e1fa21d51737dea052ddbebb116616babbc5c650e643c0eeba56

data/exe/sperf

@@ -1,476 +1,2 @@
 #!/usr/bin/env ruby
-require "optparse"
-require "socket"
-
-def find_available_port
-  server = TCPServer.new("localhost", 0)
-  port = server.addr[1]
-  server.close
-  port
-end
-
-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)
-    --signal VALUE          Timer signal (Linux only): signal number, or 'false'
-                            for nanosleep thread (default: auto)
-    -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)
-    --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 (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
-    SPERF_SIGNAL=N|false  Timer signal number or 'false' for nanosleep (Linux only)
-
-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=localhost:#{find_available_port}", 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=localhost:#{find_available_port}", "-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
-signal = 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("--signal VALUE", "Timer signal (Linux only): signal number, or 'false' for nanosleep thread") do |v|
-    signal = (v == "false") ? "false" : v
-  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
-ENV["SPERF_SIGNAL"] = signal if signal
-
-if subcommand == "stat"
-  ENV["SPERF_STAT"] = "1"
-  ENV["SPERF_STAT_COMMAND"] = ARGV.join(" ")
-end
-
-exec(*ARGV)
+require_relative '../lib/sperf'

data/lib/sperf/version.rb

@@ -1,3 +1,3 @@
 module Sperf
-  VERSION = "0.2.1"
-end
+  VERSION = "0.3.0"
+end