rperf 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5e10797e7670051bb82e49f32a80bac5371c9bd7652809ece4894a7d508c4bf
-  data.tar.gz: b577d93730398a5b91ab89df80e0cec422300839ec3d9879043b711285d4c4c2
+  metadata.gz: 3413c4c6ed0cdc0897428bf01fc0fec17a4d14f1c2883e9e5afa0cff110247dc
+  data.tar.gz: '097b06203ce4648a860f2816635d6dfac52f8e5987aa381653cec874d52abf7c'
 SHA512:
-  metadata.gz: 2b5eb6e2125e2155937af009e084b43ff4ea4a5599a4b9d2015f3d6cd13a86f6644ecf05b58a383867853bb87e2017a4097d0f9c34662622dfaafba21efdd98c
-  data.tar.gz: e3585af44f4cfbb5bace10a7ea127d801035006123a45a54aa1c2b095aeb93f8b98a41041f39cda62a5bda7e16ce4ee5acb6a88290224db5b3162e08c969f6da
+  metadata.gz: 37065071f049a27eb1bab9f859ed39499022489a19aa8ecd91b3dc35cb6052ffb6b2fbc02c67ea46a94e8dba7644f2b23760d72d2dda7b998ccf3c61c304e225
+  data.tar.gz: 686ab430d58e5dd5163ae65a2bd330a76e57cf0dd72e7eac2b7c61621a03007bd724cac20b1e452766870ff33de325855e199bc3d873d004344f7b26b9b6614f

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
 
@@ -19,22 +20,41 @@ POSIX systems (Linux, macOS). Requires Ruby >= 3.4.0.
     -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)
+    -p, --print             Print text profile to stdout
+                            (same as --format=text --output=/dev/stdout)
     --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.
+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)
+    --report                Include flat/cumulative profile tables in output
     --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.
+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.
 
@@ -58,8 +78,12 @@ Default (no flag): opens diff in browser.
     rperf record -m wall -f 500 -o profile.pb.gz ruby server.rb
     rperf record -o profile.collapsed ruby app.rb
     rperf record -o profile.txt ruby app.rb
+    rperf record -p ruby app.rb
     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
@@ -99,16 +123,22 @@ 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],         #   frames: [[path, label], ...] deepest-first
+    ...                            #   weight: Integer (nanoseconds, merged per unique stack)
+  ],                               #   seq: Integer (thread sequence, 1-based)
+  # --- OR ---
+  raw_samples: [           # when aggregate: false
+    [frames, weight, seq], #   one entry per timer sample (not merged)
+    ...
+  ] }
 ```
 
 ### Rperf.save(path, data, format: nil)
@@ -168,14 +198,14 @@ 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)
-         ...
+     Flat:
+               820.3 ms  53.8%  Array#each (app/models/user.rb)
+               312.1 ms  20.5%  JSON.parse (lib/json/parser.rb)
+               ...
 
-    Cumulative:
-        1401.2ms  92.0%  UsersController#index (app/controllers/users_controller.rb)
-         ...
+     Cumulative:
+             1,401.2 ms  92.0%  UsersController#index (app/controllers/users_controller.rb)
+               ...
 
 ### Format auto-detection
 
@@ -281,6 +311,7 @@ Used internally by the CLI to pass options to the auto-started profiler:
     RPERF_VERBOSE=1       Print statistics
     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
 
 ## TIPS
 

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"
@@ -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,17 +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 = (subcommand == "exec")
 
 parser = OptionParser.new do |opts|
-  opts.banner = USAGE
+  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
 
@@ -146,21 +153,37 @@ parser = OptionParser.new do |opts|
     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
+  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
 
+  if subcommand == "record"
     opts.on("--format FORMAT", %w[pprof collapsed text],
             "Output format: pprof, collapsed, or text (default: auto from extension)") do |v|
       format = v
     end
+
+    opts.on("-p", "--print", "Print text profile to stdout (same as --format=text --output=/dev/stdout)") do
+      format = "text"
+      output = "/dev/stdout"
+    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("--no-aggregate", "Disable sample aggregation (keep raw samples)") do
+    aggregate = false
+  end
+
+  if subcommand == "stat"
+    opts.on("--report", "Include flat/cumulative profile tables in output") do
+      stat_report = true
+    end
+  end
+
   opts.on("-v", "--verbose", "Print sampling statistics to stderr") do
     verbose = true
   end
@@ -187,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)
@@ -198,10 +244,12 @@ ENV["RPERF_MODE"] = mode
 ENV["RPERF_FORMAT"] = format if format
 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
 end
 
 exec(*ARGV)