rperf 0.9.0 → 0.11.0

data/exe/rperf

@@ -10,12 +10,102 @@ def find_available_port
   port
 end
 
-def run_pprof_subcommand(name, banner, min_files:)
+# Whether a GUI browser can be opened. Without a display, xdg-open /
+# sensible-browser fall back to terminal browsers (w3m etc.), which take
+# over the TTY and cannot run the viewer's JavaScript anyway.
+def can_open_browser?
+  case RUBY_PLATFORM
+  when /darwin/ then true
+  when /linux/  then !!(ENV["DISPLAY"] || ENV["WAYLAND_DISPLAY"])
+  else false
+  end
+end
+
+# Serve a Rperf::Viewer app and open the browser (only with a GUI and a
+# local bind). Does not return (runs the Rack handler until interrupted).
+def serve_viewer(app, port: nil, host: nil)
+  # Find an available Rack handler first, before claiming to serve
+  begin
+    require "rackup/handler"
+  rescue LoadError
+    $stderr.puts "Error: 'rackup' gem is required for 'rperf report'. Install it with:"
+    $stderr.puts "  gem install rackup"
+    exit 1
+  end
+
+  if port
+    # Fail fast on a taken port — otherwise the readiness probe below would
+    # "succeed" against the foreign server and open the browser on it, and
+    # the handler would die with a raw EADDRINUSE backtrace
+    begin
+      TCPServer.open(host || "localhost", port) {}
+    rescue Errno::EADDRINUSE
+      $stderr.puts "Error: port #{port} is already in use (choose another --port)"
+      exit 1
+    rescue SystemCallError
+      # unbindable host etc. — let the handler report it
+    end
+  end
+  port ||= find_available_port
+  host ||= "localhost"
+  local = %w[localhost 127.0.0.1 ::1].include?(host)
+  # 0.0.0.0 binds all interfaces; show a URL that works from outside
+  display_host = (host == "0.0.0.0") ? Socket.gethostname : host
+  url = "http://#{display_host}:#{port}/"
+  $stderr.puts "Serving rperf viewer at #{url} (bound to #{host})"
+  unless local
+    $stderr.puts "WARNING: the viewer has no authentication; anyone who can reach #{host}:#{port} can read the profile."
+  end
+  auto_open = local && can_open_browser?
+  $stderr.puts "Open the URL in a browser (not auto-opening)." unless auto_open
+  $stderr.puts "Press Ctrl-C to stop."
+
+  # Open browser after server is ready
+  if auto_open
+    Thread.new do
+      20.times do
+        TCPSocket.new(host, port).close
+        break
+      rescue Errno::ECONNREFUSED
+        sleep 0.1
+      end
+      case RUBY_PLATFORM
+      when /darwin/ then system("open", url)
+      when /linux/  then system("xdg-open", url, out: File::NULL, err: File::NULL) || system("sensible-browser", url, out: File::NULL, err: File::NULL)
+      end
+    end
+  end
+
+  handler = Rackup::Handler.default
+  begin
+    handler.run(app, Port: port, Host: host, Silent: true)
+  rescue Errno::EADDRINUSE
+    $stderr.puts "Error: port #{port} is already in use (choose another --port)"
+    exit 1
+  end
+end
+
+def run_pprof_subcommand(banner, min_files:)
   mode = :http
+  port = nil
+  host = nil
 
   parser = OptionParser.new do |opts|
     opts.banner = banner
 
+    opts.on("--port PORT", Integer, "Port for the web UI (default: auto). Useful for SSH port forwarding") do |v|
+      unless v.between?(1, 65535)
+        $stderr.puts "Error: --port must be 1..65535, got #{v}"
+        exit 1
+      end
+      port = v
+    end
+
+    opts.on("--host HOST", "Bind address for the web UI (default: localhost). " \
+                           "Use 0.0.0.0 to allow external access — the viewer has NO authentication") do |v|
+      host = v
+    end
+
     opts.on("--top", "Print top functions by #{min_files > 1 ? 'diff' : 'flat time'}") do
       mode = :top
     end
@@ -24,6 +114,12 @@ def run_pprof_subcommand(name, banner, min_files:)
       mode = :text
     end
 
+    opts.on("--format FORMAT", %w[table table-json],
+            "Flat #{min_files > 1 ? 'diff ' : ''}table for AI/machine consumption: " \
+            "'table' (TSV) or 'table-json' (JSON)") do |v|
+      mode = (v == "table") ? :table : :table_json
+    end
+
     if min_files == 1
       opts.on("--html", "Output static HTML viewer to stdout") do
         mode = :html
@@ -38,27 +134,29 @@ def run_pprof_subcommand(name, banner, min_files:)
 
   begin
     parser.order!(ARGV)
-  rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::NeedlessArgument => e
+  rescue OptionParser::ParseError => e
     $stderr.puts e.message
     $stderr.puts parser
     exit 1
   end
 
-  if ARGV.size < min_files
-    msg = min_files > 1 ? "Two profile files required." : "No profile file specified."
-    $stderr.puts msg if min_files > 1
-    # For report, use default file
-  end
-
-  files = ARGV.shift(min_files > 1 ? [ARGV.size, min_files].min : 1)
+  files = ARGV.shift(min_files)
   files = ["rperf.json.gz"] if files.empty? && min_files == 1
 
-  if min_files > 1 && files.size < min_files
+  if files.size < min_files
     $stderr.puts "Two profile files required."
     $stderr.puts parser
     exit 1
   end
 
+  # order! stops at the first non-option — anything left over (e.g. options
+  # placed after the file argument) would be silently ignored
+  unless ARGV.empty?
+    $stderr.puts "Unexpected extra arguments: #{ARGV.join(' ')} (options must come before the file arguments)"
+    $stderr.puts parser
+    exit 1
+  end
+
   files.each do |f|
     unless File.exist?(f)
       $stderr.puts "File not found: #{f}"
@@ -67,11 +165,11 @@ def run_pprof_subcommand(name, banner, min_files:)
   end
 
   # Go check is deferred — only needed for pprof files, not marshal/json
-  yield mode, files
+  yield mode, files, port, host
 end
 
 def self.help_text
-  @help_text ||= File.read(File.expand_path("../docs/help.md", __dir__))
+  File.read(File.expand_path("../docs/help.md", __dir__))
 end
 
 USAGE = "Usage: rperf record [options] command [args...]\n" \
@@ -101,15 +199,36 @@ when "help"
   puts help_text
   exit
 when "report"
-  run_pprof_subcommand("report",
+  run_pprof_subcommand(
     "Usage: rperf report [options] [file]\n" \
     "       Opens profile in browser (default) or prints summary.\n" \
     "       Default file: rperf.json.gz\n" \
     "       For .json.gz: opens rperf viewer (no Go required).\n" \
     "       For .pb.gz: opens go tool pprof (requires Go).",
-    min_files: 1) do |mode, files|
+    min_files: 1) do |mode, files, port, host|
     report_file = files[0]
-    if report_file =~ /\.json(\.gz)?\z/
+    if File.directory?(report_file)
+      # Time-travel mode: list all profiles in the directory (meta/summary
+      # only — bodies are lazy-loaded on selection)
+      unless mode == :http
+        $stderr.puts "Directory input opens the time-travel viewer; --top/--text/--html/--format are not supported"
+        exit 1
+      end
+      require_relative "../lib/rperf"
+      require_relative "../lib/rperf/viewer"
+      app = Rperf::Viewer.new(
+        proc { |_| [404, { "content-type" => "text/plain" }, ["Not Found"]] },
+        path: ""
+      )
+      count = app.add_snapshot_dir(report_file)
+      if count == 0
+        $stderr.puts "No .json(.gz) profiles found in #{report_file}"
+        exit 1
+      end
+      $stderr.puts "Loaded #{count} snapshot#{count == 1 ? '' : 's'} from #{report_file}"
+      serve_viewer(app, port: port, host: host)
+      exit
+    elsif report_file =~ /\.json(\.gz)?\z/
       # Use rperf viewer
       require_relative "../lib/rperf"
       require_relative "../lib/rperf/viewer"
@@ -123,49 +242,33 @@ when "report"
       when :text
         $stdout.puts Rperf::Text.encode(data)
         exit
+      when :table
+        $stdout.print Rperf::Table.report_tsv(data)
+        exit
+      when :table_json
+        $stdout.puts Rperf::Table.report_json(data)
+        exit
       when :html
         $stdout.puts Rperf::Viewer.render_static_html(data)
         exit
       end
 
-      port = find_available_port
-
       app = Rperf::Viewer.new(
         proc { |_| [404, { "content-type" => "text/plain" }, ["Not Found"]] },
         path: ""
       )
       app.add_snapshot(data)
-
-      url = "http://localhost:#{port}/"
-      $stderr.puts "Serving rperf viewer at #{url}"
-      $stderr.puts "Press Ctrl-C to stop."
-
-      # Open browser after server is ready
-      Thread.new do
-        20.times do
-          TCPSocket.new("localhost", port).close
-          break
-        rescue Errno::ECONNREFUSED
-          sleep 0.1
-        end
-        case RUBY_PLATFORM
-        when /darwin/ then system("open", url)
-        when /linux/  then system("xdg-open", url, err: File::NULL) || system("sensible-browser", url, err: File::NULL)
-        end
+      serve_viewer(app, port: port, host: host)
+      exit
+    else
+      if mode == :table || mode == :table_json
+        $stderr.puts "--format table requires a .json.gz / .json profile (got: #{report_file})"
+        exit 1
       end
-
-      # Find an available Rack handler
-      begin
-        require "rackup/handler"
-      rescue LoadError
-        $stderr.puts "Error: 'rackup' gem is required for 'rperf report'. Install it with:"
-        $stderr.puts "  gem install rackup"
+      if mode == :html
+        $stderr.puts "--html requires a .json.gz / .json profile (got: #{report_file})"
         exit 1
       end
-      handler = Rackup::Handler.default
-      handler.run(app, Port: port, Host: "localhost", Silent: true)
-      exit
-    else
       unless system("go", "version", out: File::NULL, err: File::NULL)
         $stderr.puts "'go' command not found. Install Go to use pprof files, or use .json.gz format."
         $stderr.puts "  https://go.dev/dl/"
@@ -174,17 +277,38 @@ when "report"
       case mode
       when :top  then exec("go", "tool", "pprof", "-top", report_file)
       when :text then exec("go", "tool", "pprof", "-text", report_file)
-      else            exec("go", "tool", "pprof", "-http=localhost:#{find_available_port}", report_file)
+      else
+        # pprof has its own browser launcher — suppress it without a GUI
+        http_args = ["-http=#{host || %q(localhost)}:#{port || find_available_port}"]
+        http_args << "-no_browser" unless can_open_browser?
+        exec("go", "tool", "pprof", *http_args, report_file)
       end
     end
   end
 when "diff"
-  run_pprof_subcommand("diff",
+  run_pprof_subcommand(
     "Usage: rperf diff [options] base target\n" \
     "       Compare two profiles (shows target - base).\n" \
     "       Accepts .json.gz (auto-converted) or .pb.gz files.\n" \
-    "       Requires Go (https://go.dev/dl/).",
-    min_files: 2) do |mode, files|
+    "       Requires Go (https://go.dev/dl/), except --format table/table-json.",
+    min_files: 2) do |mode, files, port, host|
+    # Table diff is computed in Ruby — no Go required
+    if mode == :table || mode == :table_json
+      unless files.all? { |f| f =~ /\.json(\.gz)?\z/ }
+        $stderr.puts "--format table requires .json.gz / .json profiles"
+        exit 1
+      end
+      require_relative "../lib/rperf"
+      base = Rperf.load(files[0])
+      head = Rperf.load(files[1])
+      if mode == :table
+        $stdout.print Rperf::Table.diff_tsv(base, head)
+      else
+        $stdout.puts Rperf::Table.diff_json(base, head)
+      end
+      exit
+    end
+
     unless system("go", "version", out: File::NULL, err: File::NULL)
       $stderr.puts "'go' command not found. Install Go to use 'rperf diff'."
       $stderr.puts "  https://go.dev/dl/"
@@ -210,7 +334,10 @@ when "diff"
     pprof_args = case mode
                  when :top  then ["-top", "-diff_base=#{base_file}", target_file]
                  when :text then ["-text", "-diff_base=#{base_file}", target_file]
-                 else            ["-http=localhost:#{find_available_port}", "-diff_base=#{base_file}", target_file]
+                 else
+                   args = ["-http=#{host || %q(localhost)}:#{port || find_available_port}"]
+                   args << "-no_browser" unless can_open_browser?
+                   args + ["-diff_base=#{base_file}", target_file]
                  end
     if tmpfiles.empty?
       exec("go", "tool", "pprof", *pprof_args)
@@ -230,6 +357,7 @@ else
 end
 
 output = (subcommand == "record") ? "rperf.json.gz" : nil
+output_given = false
 frequency = 1000
 mode = (subcommand == "record") ? "cpu" : "wall"
 format = nil
@@ -238,6 +366,9 @@ verbose = false
 aggregate = true
 stat_report = (subcommand == "exec")
 inherit = true
+meta_labels = {}
+snapshot_dir = nil
+print_env = false
 
 parser = OptionParser.new do |opts|
   opts.banner = case subcommand
@@ -248,6 +379,7 @@ parser = OptionParser.new do |opts|
 
   opts.on("-o", "--output PATH", "Output file#{subcommand == 'record' ? ' (default: rperf.json.gz)' : ' (default: none)'}") do |v|
     output = v
+    output_given = true
   end
 
   opts.on("-f", "--frequency HZ", Integer, "Sampling frequency in Hz (default: 1000)") do |v|
@@ -268,9 +400,23 @@ parser = OptionParser.new do |opts|
     opts.on("-p", "--print", "Print text profile to stdout (same as --format=text --output=/dev/stdout)") do
       format = "text"
       output = "/dev/stdout"
+      output_given = true
+    end
+
+    opts.on("--snapshot-dir DIR", "Save output as rperf-<sha7>-<timestamp>.json.gz in DIR") do |v|
+      snapshot_dir = v
     end
   end
 
+  opts.on("--label KEY=VALUE", "Add a label to profile metadata (repeatable)") do |v|
+    key, value = v.split("=", 2)
+    if key.nil? || key.empty? || value.nil?
+      $stderr.puts "Error: --label must be KEY=VALUE, got: #{v.inspect}"
+      exit 1
+    end
+    meta_labels[key] = value
+  end
+
   opts.on("--signal VALUE", "Timer signal (Linux only): signal number, or 'false' for nanosleep thread") do |v|
     if v == "false"
       signal = "false"
@@ -296,6 +442,13 @@ parser = OptionParser.new do |opts|
     inherit = false
   end
 
+  opts.on("--print-env",
+          "Print the environment rperf would set (one `export KEY=VALUE` per line), then exit " \
+          "WITHOUT running a command. The caller sources it, sets RPERF_ROOT_PROCESS to the pid " \
+          "that will exec the command, and runs the command itself — so rperf never wraps it.") do
+    print_env = true
+  end
+
   opts.on("-v", "--verbose", "Print sampling statistics to stderr") do
     verbose = true
   end
@@ -310,13 +463,13 @@ end
 
 begin
   parser.order!(ARGV)
-rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::NeedlessArgument => e
+rescue OptionParser::ParseError => e
   $stderr.puts e.message
   $stderr.puts parser
   exit 1
 end
 
-if ARGV.empty?
+if ARGV.empty? && !print_env
   $stderr.puts "No command specified."
   $stderr.puts parser
   exit 1
@@ -345,6 +498,47 @@ if signal && signal != "false"
   end
 end
 
+# Load the library BEFORE exporting RPERF_ENABLED — requiring it afterwards
+# would trigger the ENV-based auto-start in the CLI process itself.
+require_relative "../lib/rperf"
+require "json"
+
+# Collect git metadata here, not in the profiled process: the app may chdir,
+# which would point git at the wrong repository. The profiled process reads
+# RPERF_META_GIT instead of running git ("null" = checked, not a repo).
+git_info = Rperf::Meta.collect_git
+ENV["RPERF_META_GIT"] = git_info ? JSON.generate(git_info) : "null"
+ENV["RPERF_META_LABELS"] = JSON.generate(meta_labels) unless meta_labels.empty?
+
+if snapshot_dir
+  if output_given
+    $stderr.puts "Error: --snapshot-dir and -o/--output (or -p) are mutually exclusive"
+    exit 1
+  end
+  if format && format != "json"
+    $stderr.puts "Error: --snapshot-dir requires JSON format (got --format=#{format})"
+    exit 1
+  end
+  FileUtils.mkdir_p(snapshot_dir)
+  output = File.join(snapshot_dir, Rperf::Meta.snapshot_filename(git_info))
+  # Timestamp resolution is one second and the in-git name has no pid —
+  # don't overwrite an earlier run from the same second on the same commit
+  output = output.sub(/\.json\.gz\z/, "-#{Process.pid}.json.gz") if File.exist?(output)
+end
+
+if output
+  # Resolve now: the profiled app may chdir, which would silently relocate a
+  # relative output path. Validate writability up front, too — discovering an
+  # unwritable path in at_exit wastes the entire profiling run.
+  output = File.expand_path(output)
+  out_dir = File.dirname(output)
+  writable = File.exist?(output) ? File.writable?(output) : (File.directory?(out_dir) && File.writable?(out_dir))
+  unless writable
+    $stderr.puts "Error: output path is not writable: #{output}"
+    exit 1
+  end
+end
+
 # 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.
@@ -367,13 +561,39 @@ if subcommand == "stat" || subcommand == "exec"
 end
 
 # Multi-process (fork) support: create a session directory for aggregation
+session_dir = nil
 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
+    # In --print-env mode this short-lived process does not run the command, so
+    # it must not claim rootship: the caller sets RPERF_ROOT_PROCESS to the pid
+    # that will exec the command. Otherwise (normal exec) we are the root.
+    ENV["RPERF_ROOT_PROCESS"] = Process.pid.to_s unless print_env
   end
 end
 
-exec(*ARGV)
+# --print-env: emit the environment a profiled process inherits to auto-start
+# rperf, then exit without running anything. RPERF_ROOT_PROCESS and
+# RPERF_META_LABELS are deliberately omitted — the caller owns those (it sets
+# the root pid, and labels per measurement run).
+if print_env
+  require "shellwords"
+  %w[RUBYLIB RUBYOPT RPERF_ENABLED RPERF_OUTPUT RPERF_FREQUENCY RPERF_MODE
+     RPERF_FORMAT RPERF_VERBOSE RPERF_SIGNAL RPERF_AGGREGATE RPERF_META_GIT
+     RPERF_SESSION_DIR RPERF_STAT RPERF_STAT_COMMAND RPERF_STAT_REPORT].each do |k|
+    v = ENV[k]
+    puts "export #{k}=#{Shellwords.escape(v)}" unless v.nil?
+  end
+  exit 0
+end
+
+begin
+  exec(*ARGV)
+rescue Errno::ENOENT, Errno::EACCES => e
+  $stderr.puts "rperf: failed to execute #{ARGV.first.inspect}: #{e.message}"
+  # exec never ran — remove the eagerly created session dir instead of
+  # leaving it for the stale-PID sweep
+  FileUtils.rm_rf(session_dir) if session_dir
+  exit(e.is_a?(Errno::ENOENT) ? 127 : 126)
+end