rperf 0.8.0 → 0.10.0

data/lib/rperf.rb

@@ -1,4 +1,6 @@
 require_relative "rperf/version"
+require_relative "rperf/meta"
+require_relative "rperf/table"
 require "zlib"
 require "stringio"
 
@@ -13,10 +15,21 @@ end
 
 module Rperf
 
-  @verbose = false
-  @output = nil
-  @stat = false
-  @stat_start_mono = nil
+  # --- Module-level state (single global profiler) ---
+  # Profiling session
+  @verbose = false               # verbose stats output on stop
+  @output = nil                  # output file path (nil = no file)
+  @format = nil                  # output format (:json, :pprof, :collapsed, :text, nil = auto)
+  @stat = false                  # print user/sys/real summary to stderr
+  @stat_start_mono = nil         # Process::CLOCK_MONOTONIC at start (for real time)
+  @stat_start_times = nil        # Process.times at start (for user/sys time)
+  @label_set_table = nil         # Array: label_set_id → frozen Hash
+  @label_set_index = nil         # Hash: frozen label Hash → label_set_id
+  # Multi-process (fork/spawn) support
+  @_session_dir_output = false   # true when @output points to session dir (child process)
+  @_session_dir_created = false  # true after first fork activates session dir
+  @_fork_hook_installed = false  # true after Process._fork hook is prepended
+  @_saved_env = nil              # saved ENV values for restore on stop (inherit: true)
 
   # Starts profiling.
   # format: :json, :pprof, :collapsed, or :text. nil = auto-detect from output extension
@@ -24,10 +37,19 @@ module Rperf
   #   .collapsed → collapsed stacks (FlameGraph / speedscope compatible)
   #   .txt       → text report (human/AI readable flat + cumulative table)
   #   .pb.gz     → pprof protobuf (gzip compressed)
-  def self.start(frequency: 1000, mode: :cpu, output: nil, verbose: false, format: nil, stat: false, signal: nil, aggregate: true, defer: false)
+  # inherit: controls child process profiling.
+  #   :fork  — (default) automatically profile forked child processes via Process._fork hook.
+  #            Session dir is created eagerly at start time. Spawned processes are NOT tracked.
+  #   true   — profile both forked and spawned Ruby child processes. Sets RUBYOPT=-rrperf
+  #            and RPERF_* env vars so spawned Ruby processes auto-start profiling.
+  #            Use with caution: affects ALL spawned Ruby processes, including independent
+  #            programs that may use rperf themselves.
+  #   false  — do not track child processes (single-process mode).
+  def self.start(frequency: 1000, mode: :cpu, output: nil, verbose: false, format: nil, stat: false, signal: nil, aggregate: true, defer: false, inherit: :fork)
     raise ArgumentError, "frequency must be a positive integer (got #{frequency.inspect})" unless frequency.is_a?(Integer) && frequency > 0
     raise ArgumentError, "frequency must be <= 10000 (10KHz), got #{frequency}" if frequency > 10_000
     raise ArgumentError, "mode must be :cpu or :wall, got #{mode.inspect}" unless %i[cpu wall].include?(mode)
+    raise ArgumentError, "inherit must be :fork, true, or false, got #{inherit.inspect}" unless [true, false, :fork].include?(inherit)
     c_mode = mode == :cpu ? 0 : 1
     unless signal.nil? || signal == false || signal.is_a?(Integer)
       raise ArgumentError, "signal must be nil, false, or an Integer, got #{signal.inspect}"
@@ -45,14 +67,19 @@ module Rperf
     @output = output
     @format = format
     @stat = stat
-    if @stat
-      @stat_start_mono = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      @stat_start_times = Process.times
-    end
+    @stat_start_mono = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    @stat_start_times = Process.times
+    @gc_stat_start = GC.stat
+    @gc_stat_snapshot_base = @gc_stat_start
     @label_set_table = nil
     @label_set_index = nil
     _c_start(frequency, c_mode, aggregate, c_signal, defer)
 
+    # Set up child process tracking
+    if inherit && !ENV["RPERF_SESSION_DIR"]
+      _setup_inherit(mode, frequency, signal, aggregate, inherit, defer)
+    end
+
     if block_given?
       begin
         yield
@@ -63,8 +90,12 @@ module Rperf
     end
   end
 
+  # Defensive fallback for process times when start didn't record them
+  ZERO_TIMES = Struct.new(:utime, :stime).new(0.0, 0.0).freeze
+  private_constant :ZERO_TIMES
+
   # VM state integer → label value mapping.
-  # These values appear in the "Ruby" label key.
+  # These values appear as "%GVL" / "%GC" label keys in label_sets.
   VM_STATE_LABELS = {
     1 => ["%GVL", "blocked"],
     2 => ["%GVL", "wait"],
@@ -73,9 +104,43 @@ module Rperf
   }.freeze
 
   def self.stop
+    # Check if we need to aggregate child process data.
+    # @_session_dir_created: fork happened and session dir is active.
+    # Otherwise: check for actual child profile files (spawn-only case).
+    session_dir = ENV["RPERF_SESSION_DIR"]
+    is_root = session_dir && Process.pid.to_s == ENV["RPERF_ROOT_PROCESS"]
+    has_child_profiles = is_root && !@_session_dir_created &&
+                         File.directory?(session_dir.to_s) &&
+                         !Dir.glob(File.join(session_dir.to_s, "profile-*.json.gz")).empty?
+    needs_aggregation = is_root && (@_session_dir_created || has_child_profiles)
+
     data = _c_stop
     return unless data
 
+    # Record process times for multi-process aggregation
+    times = Process.times
+    start_times = @stat_start_times || ZERO_TIMES
+    data[:user_ns] = ((times.utime - start_times.utime) * 1_000_000_000).to_i
+    data[:sys_ns] = ((times.stime - start_times.stime) * 1_000_000_000).to_i
+
+    # GC / memory statistics for the summary (deltas since start; GC.stat is
+    # cumulative over the process lifetime). maxrss is a process-lifetime
+    # peak — no delta is possible.
+    if @gc_stat_start
+      gc = GC.stat
+      data[:gc_stats] = {
+        count: gc[:count] - @gc_stat_start[:count],
+        minor_count: gc[:minor_gc_count] - @gc_stat_start[:minor_gc_count],
+        major_count: gc[:major_gc_count] - @gc_stat_start[:major_gc_count],
+        time_ms: (gc[:time] || 0) - (@gc_stat_start[:time] || 0),
+        allocated_objects: gc[:total_allocated_objects] - @gc_stat_start[:total_allocated_objects],
+        freed_objects: gc[:total_freed_objects] - @gc_stat_start[:total_freed_objects],
+      }
+      @gc_stat_start = nil
+    end
+    sys_stats = get_system_stats
+    data[:maxrss_mb] = (sys_stats[:maxrss_kb] / 1024.0).round if sys_stats[:maxrss_kb]
+
     # When aggregate: false, C extension returns :raw_samples but not
     # :aggregated_samples.  Build aggregated view so encoders always work.
     if data[:raw_samples] && !data[:aggregated_samples]
@@ -93,18 +158,79 @@ module Rperf
 
     merge_vm_state_labels!(data)
 
+    if needs_aggregation
+      # Root process with children: write root's own profile to session dir
+      # (fixed json.gz format), then aggregate all profiles.
+      # Root's @output/@format/@stat are preserved for the merged result.
+      print_stats(data) if @verbose
+      begin
+        write_data(File.join(session_dir, "profile-#{Process.pid}.json.gz"), data, :json, internal: true)
+      rescue SystemCallError
+        # Session dir may have been removed (e.g., test scenario) — continue to aggregation
+      end
+      merged = _aggregate_and_report(data)
+      if merged.nil? && data
+        # Aggregation failed — fall back to root's own data
+        $stderr.puts "rperf: warning: multi-process aggregation failed; writing root process data only"
+        write_data(@output, data, @format) if @output
+        print_stat(data) if @stat
+      end
+      _cleanup_session_state
+      return merged || data
+    end
+
     print_stats(data) if @verbose
     print_stat(data) if @stat
 
     if @output
-      write_data(@output, data, @format)
+      if @_session_dir_output
+        # Child process writing to session dir — tolerate missing dir
+        begin
+          write_data(@output, data, @format, internal: true)
+        rescue SystemCallError
+          # Parent may have already cleaned up the session dir (e.g., parent
+          # exited first and rm_rf'd it), or disk is full. Silently skip —
+          # crashing in at_exit is worse than losing one child's profile.
+        end
+      else
+        write_data(@output, data, @format)
+      end
       @output = nil
       @format = nil
     end
 
+    _cleanup_session_state
     data
   end
 
+  def self._cleanup_session_state
+    session_dir = ENV.delete("RPERF_SESSION_DIR")
+    ENV.delete("RPERF_ROOT_PROCESS")
+    ENV.delete("RPERF_DEFER")
+    @_session_dir_created = false
+    @_session_dir_output = false
+    # Restore ENV variables saved by _setup_inherit (inherit: true)
+    if @_saved_env
+      @_saved_env.each do |key, original|
+        if original.nil?
+          ENV.delete(key)
+        else
+          ENV[key] = original
+        end
+      end
+      @_saved_env = nil
+    end
+    # Remove eagerly-created session dir if it's empty (no children ran)
+    if session_dir && File.directory?(session_dir)
+      begin
+        Dir.rmdir(session_dir)  # only succeeds if empty
+      rescue SystemCallError
+        # not empty or already removed — fine
+      end
+    end
+  end
+  private_class_method :_cleanup_session_state
+
   # Returns a snapshot of the current profiling data without stopping.
   # Only works in aggregate mode (the default). Returns nil if not profiling.
   # The returned data has the same format as stop's return value and can be
@@ -116,6 +242,23 @@ module Rperf
   def self.snapshot(clear: false)
     data = _c_snapshot(clear)
     return unless data
+    # GC/memory stats for the snapshot's summary. The baseline advances on
+    # clear: true so interval snapshots report per-interval deltas.
+    if @gc_stat_snapshot_base
+      gc = GC.stat
+      base = @gc_stat_snapshot_base
+      data[:gc_stats] = {
+        count: gc[:count] - base[:count],
+        minor_count: gc[:minor_gc_count] - base[:minor_gc_count],
+        major_count: gc[:major_gc_count] - base[:major_gc_count],
+        time_ms: (gc[:time] || 0) - (base[:time] || 0),
+        allocated_objects: gc[:total_allocated_objects] - base[:total_allocated_objects],
+        freed_objects: gc[:total_freed_objects] - base[:total_freed_objects],
+      }
+      @gc_stat_snapshot_base = gc if clear
+    end
+    sys_stats = get_system_stats
+    data[:maxrss_mb] = (sys_stats[:maxrss_kb] / 1024.0).round if sys_stats[:maxrss_kb]
     merge_vm_state_labels!(data)
     data
   end
@@ -124,24 +267,40 @@ module Rperf
   # Label sets are stored as an Array of Hashes, indexed by label_set_id.
   # Index 0 is reserved (no labels).
 
-  @label_set_table = nil  # Array of frozen Hash
-  @label_set_index = nil  # Hash → id (for dedup)
-
   def self._init_label_sets
     @label_set_table = [{}]  # id 0 = no labels
     @label_set_index = { {} => 0 }
   end
 
   def self._intern_label_set(hash)
-    frozen = hash.frozen? ? hash : hash.freeze
-    @label_set_index[frozen] ||= begin
+    hash.freeze
+    @label_set_index[hash] ||= begin
       id = @label_set_table.size
-      @label_set_table << frozen
+      @label_set_table << hash
       _c_set_label_sets(@label_set_table)
       id
     end
   end
 
+  # Merges the given keyword labels into the current thread's label set,
+  # sets the result on the current thread, and returns [previous_id, new_id].
+  # Callers use previous_id to restore labels after a block.
+  def self._merge_and_set_label(kw)
+    _init_label_sets unless @label_set_table
+
+    cur_id = _c_get_label
+    cur_labels = @label_set_table[cur_id] || {}
+    # Interned label sets must be deeply immutable, but freezing the caller's
+    # own objects is an observable side effect — dup mutable Strings instead
+    kw = kw.transform_values { |v| v.is_a?(String) && !v.frozen? ? v.dup.freeze : v.freeze }
+    new_labels = cur_labels.merge(kw).reject { |_, v| v.nil? }
+    new_id = _intern_label_set(new_labels)
+    _c_set_label(new_id)
+
+    [cur_id, new_id]
+  end
+  private_class_method :_merge_and_set_label
+
   # Sets labels on the current thread for profiling annotation.
   # With a block: restores previous labels when the block exits.
   # Without a block: sets labels persistently on the current thread.
@@ -155,14 +314,7 @@ module Rperf
     return yield if block && !_c_running?
     return unless _c_running?
 
-    _init_label_sets unless @label_set_table
-
-    cur_id = _c_get_label
-    cur_labels = @label_set_table[cur_id] || {}
-
-    new_labels = cur_labels.merge(kw).reject { |_, v| v.nil? }
-    new_id = _intern_label_set(new_labels)
-    _c_set_label(new_id)
+    cur_id, _new_id = _merge_and_set_label(kw)
 
     if block
       begin
@@ -187,13 +339,7 @@ module Rperf
     raise ArgumentError, "Rperf.profile requires a block" unless block
     raise RuntimeError, "Rperf is not started" unless _c_running?
 
-    _init_label_sets unless @label_set_table
-
-    cur_id = _c_get_label
-    cur_labels = @label_set_table[cur_id] || {}
-    new_labels = cur_labels.merge(kw).reject { |_, v| v.nil? }
-    new_id = _intern_label_set(new_labels)
-    _c_set_label(new_id)
+    cur_id, _new_id = _merge_and_set_label(kw)
 
     _c_profile_inc
 
@@ -205,6 +351,11 @@ module Rperf
     end
   end
 
+  # Returns true while a profiling session is active (between start and stop).
+  def self.running?
+    _c_running?
+  end
+
   # Returns the current thread's labels as a Hash.
   # Returns an empty Hash if no labels are set or profiling is not running.
   def self.labels
@@ -238,7 +389,7 @@ module Rperf
       unless new_id
         base = label_sets[label_set_id] || {}
         key, value = VM_STATE_LABELS[vm_state]
-        new_ls = base.merge(key => value).freeze
+        new_ls = base.merge(key.to_sym => value).freeze
         new_id = label_sets.size
         label_sets << new_ls
         mapping[cache_key] = new_id
@@ -257,7 +408,8 @@ module Rperf
 
   # Saves profiling data to a file.
   # format: :json, :pprof, :collapsed, or :text. nil = auto-detect from path extension
-  #   .json.gz   → json (rperf native, default)
+  #   .json.gz   → json (rperf native, gzip compressed, default)
+  #   .json      → json (plain text, readable by jq etc.)
   #   .collapsed → collapsed stacks (FlameGraph / speedscope compatible)
   #   .txt       → text report (human/AI readable flat + cumulative table)
   #   .pb.gz     → pprof protobuf (gzip compressed)
@@ -265,30 +417,85 @@ module Rperf
     write_data(path, data, format)
   end
 
-  def self.write_data(path, data, format)
+  # internal: true skips meta/summary generation — used for per-process
+  # intermediate files in the multi-process session dir (meta is attached
+  # once, on the root's final output).
+  def self.write_data(path, data, format, internal: false)
     fmt = detect_format(path, format)
     case fmt
     when :collapsed
-      File.write(path, Collapsed.encode(data))
+      atomic_write(path, Collapsed.encode(data))
     when :text
-      File.write(path, Text.encode(data))
+      atomic_write(path, Text.encode(data))
     when :json
       require "json"
-      File.binwrite(path, gzip(JSON.generate(data.merge(rperf_version: VERSION))))
+      json_data = data
+      unless internal
+        # meta/summary must be the FIRST keys so Meta.read can extract them
+        # from the head of the (gzipped) file without loading the body —
+        # reorder even when re-saving data that already carries them.
+        meta = data[:meta] || Meta.build_meta(data)
+        summary = data[:summary] || Meta.build_summary(data)
+        json_data = { meta: meta, summary: summary }.merge(data.except(:meta, :summary))
+      end
+      json_data = json_data.merge(rperf_version: VERSION, pid: Process.pid, ppid: Process.ppid)
+      json_str = JSON.generate(json_data)
+      if path.to_s.end_with?(".gz")
+        atomic_write(path, gzip(json_str), binary: true)
+      else
+        atomic_write(path, json_str)
+      end
     else
-      File.binwrite(path, gzip(PProf.encode(data)))
+      atomic_write(path, gzip(PProf.encode(data)), binary: true)
     end
   end
   private_class_method :write_data
 
-  # Load a profile saved by rperf record (.json.gz).
+  # Write via tmp file + rename so a crash mid-write never leaves a truncated
+  # file at the final path (the multi-process aggregator globs the session dir
+  # and would otherwise load — and then discard — a partial child profile).
+  def self.atomic_write(path, content, binary: false)
+    # rename cannot replace special files (/dev/null → EBUSY) and would
+    # replace a symlink instead of writing through it — write those directly
+    st = begin
+      File.lstat(path)
+    rescue SystemCallError
+      nil
+    end
+    if st && !st.file?
+      binary ? File.binwrite(path, content) : File.write(path, content)
+      return
+    end
+
+    tmp = "#{path}.tmp-#{Process.pid}"
+    binary ? File.binwrite(tmp, content) : File.write(tmp, content)
+    File.rename(tmp, path)
+  rescue Exception
+    begin
+      File.unlink(tmp)
+    rescue SystemCallError
+      # tmp was never created or already renamed
+    end
+    raise
+  end
+  private_class_method :atomic_write
+
+  # Load a profile saved by rperf record (.json.gz or .json).
   # Returns the data hash (same format as Rperf.stop / Rperf.snapshot).
   # Warns to stderr if the file was saved by a different rperf version.
   def self.load(path)
-    compressed = File.binread(path)
-    raw = Zlib::GzipReader.new(StringIO.new(compressed)).read
+    raw_bytes = File.binread(path)
+    # Auto-detect gzip by magic bytes (1f 8b)
+    raw = if raw_bytes.byteslice(0, 2) == "\x1f\x8b".b
+      Zlib::GzipReader.new(StringIO.new(raw_bytes)).read
+    else
+      raw_bytes
+    end
     require "json"
     data = JSON.parse(raw, symbolize_names: true)
+    # symbolize_names only converts keys — :mode round-trips as a String
+    # ("wall"), which encoders compare against :wall/:cpu symbols
+    data[:mode] = data[:mode].to_sym if data[:mode].is_a?(String)
     saved_version = data.delete(:rperf_version)
     if saved_version && saved_version != VERSION
       $stderr.puts "rperf: warning: file was saved by rperf #{saved_version} (current: #{VERSION})"
@@ -298,6 +505,14 @@ module Rperf
     data
   end
 
+  # Read only the meta/summary head of a profile saved by rperf record
+  # (.json.gz or .json) without loading the sample body.
+  # Returns { meta: Hash|nil, summary: Hash|nil }, or nil for files saved
+  # by older rperf versions (no leading meta) or unreadable files.
+  def self.read_meta(path)
+    Meta.read(path)
+  end
+
   def self.detect_format(path, format)
     return format.to_sym if format
     case path.to_s
@@ -401,10 +616,17 @@ module Rperf
     samples_raw = data[:aggregated_samples] || []
     real_ns = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - @stat_start_mono) * 1_000_000_000).to_i
     times = Process.times
-    start_times = @stat_start_times || Struct.new(:utime, :stime).new(0.0, 0.0)
+    start_times = @stat_start_times || ZERO_TIMES
     user_ns = ((times.utime - start_times.utime) * 1_000_000_000).to_i
     sys_ns = ((times.stime - start_times.stime) * 1_000_000_000).to_i
 
+    # In multi-process mode, use aggregated user/sys from all processes
+    process_count = data[:process_count] || 0
+    if process_count > 1 && data[:user_ns]
+      user_ns = data[:user_ns]
+      sys_ns = data[:sys_ns] || 0
+    end
+
     command = ENV["RPERF_STAT_COMMAND"] || "(unknown)"
 
     $stderr.puts
@@ -416,9 +638,9 @@ module Rperf
 
     if samples_raw.size > 0
       breakdown, total_weight = compute_stat_breakdown(samples_raw, data[:label_sets])
-      print_stat_breakdown(breakdown, total_weight)
+      print_stat_breakdown(breakdown, total_weight, data)
       print_stat_runtime_info(data)
-      print_stat_system_info
+      print_stat_system_info(data)
       print_stat_report(data) if ENV["RPERF_STAT_REPORT"] == "1"
       print_stat_footer(samples_raw, real_ns, data)
     end
@@ -436,8 +658,8 @@ module Rperf
       if label_sets && label_set_id && label_set_id > 0
         ls = label_sets[label_set_id]
         if ls
-          gvl = ls["%GVL"]
-          gc  = ls["%GC"]
+          gvl = ls[:"%GVL"]
+          gc  = ls[:"%GC"]
           if gvl == "blocked"    then category = :gvl_blocked
           elsif gvl == "wait"    then category = :gvl_wait
           elsif gc  == "mark"    then category = :gc_marking
@@ -452,8 +674,12 @@ module Rperf
   end
   private_class_method :compute_stat_breakdown
 
-  def self.print_stat_breakdown(breakdown, total_weight)
+  def self.print_stat_breakdown(breakdown, total_weight, data)
     $stderr.puts
+    process_count = data[:process_count] || 0
+    if process_count > 1
+      $stderr.puts STAT_LINE.call(format_integer(process_count), "  ", "[Rperf] Ruby processes profiled")
+    end
 
     [
       [:cpu_execution, "[Rperf] CPU execution"],
@@ -490,7 +716,7 @@ module Rperf
   end
   private_class_method :print_stat_runtime_info
 
-  def self.print_stat_system_info
+  def self.print_stat_system_info(data = nil)
     sys_stats = get_system_stats
     maxrss_kb = sys_stats[:maxrss_kb]
     if maxrss_kb
@@ -520,6 +746,10 @@ module Rperf
           format_integer((r / 1024.0 / 1024.0).round),
           format_integer((w / 1024.0 / 1024.0).round)])
     end
+    process_count = data[:process_count] if data
+    if process_count && process_count > 1
+      $stderr.puts STAT_LINE.call("", "  ", "(GC/OS stats are from root process only; user/sys/[Rperf] lines are aggregated)")
+    end
   end
   private_class_method :print_stat_system_info
 
@@ -532,7 +762,12 @@ module Rperf
 
   def self.print_stat_footer(samples_raw, real_ns, data)
     triggers = data[:trigger_count] || 0
-    overhead_pct = real_ns > 0 ? (data[:sampling_time_ns] || 0) * 100.0 / real_ns : 0.0
+    sampling_time_ns = data[:sampling_time_ns] || 0
+    # In multi-process mode, use sum of all processes' durations as denominator.
+    # Single-process: fall back to root's real_ns.
+    total_real_ns = data[:total_duration_ns] || real_ns
+    total_real_ns = real_ns if total_real_ns == 0
+    overhead_pct = total_real_ns > 0 ? sampling_time_ns * 100.0 / total_real_ns : 0.0
     $stderr.puts
     samples = data[:sampling_count] || samples_raw.size
     $stderr.puts format("  %d samples / %d triggers, %.1f%% profiler overhead",
@@ -541,6 +776,10 @@ module Rperf
     if dropped > 0
       $stderr.puts format("  WARNING: %d samples dropped due to memory allocation failure", dropped)
     end
+    dropped_agg = data[:dropped_aggregation] || 0
+    if dropped_agg > 0
+      $stderr.puts format("  WARNING: %d samples dropped during aggregation (frame/stack table full)", dropped_agg)
+    end
   end
   private_class_method :print_stat_footer
 
@@ -553,10 +792,10 @@ module Rperf
   # Example: 5_609_200_000 → "5,609.2"
   def self.format_ms(ns)
     ms = ns / 1_000_000.0
-    int_part = ms.truncate
-    frac = format(".%d", ((ms - int_part).abs * 10).round % 10)
-    int_str = int_part.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
-    "#{int_str}#{frac}"
+    formatted = format("%.1f", ms)
+    int_str, frac = formatted.split(".")
+    int_str = int_str.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    "#{int_str}.#{frac}"
   end
   private_class_method :format_ms
 
@@ -583,9 +822,11 @@ module Rperf
     end
 
     if File.readable?("/proc/self/stat")
-      fields = File.read("/proc/self/stat").split
-      stats[:page_faults_minor] = fields[9].to_i
-      stats[:page_faults_major] = fields[11].to_i
+      # comm (field 2) is parenthesized and may contain spaces — split only
+      # the part after the closing paren (fields from state, field 3, onward)
+      fields = File.read("/proc/self/stat").rpartition(")").last.split
+      stats[:page_faults_minor] = fields[7].to_i   # minflt (field 10)
+      stats[:page_faults_major] = fields[9].to_i   # majflt (field 12)
     end
 
     if File.readable?("/proc/self/io")
@@ -604,6 +845,306 @@ module Rperf
   end
   private_class_method :get_system_stats
 
+  # --- Multi-process (fork) support ---
+
+  # Set up child process tracking from Rperf.start(inherit: ...).
+  # Called only when NOT already inside a CLI-managed session (no RPERF_SESSION_DIR).
+  # Creates the session directory eagerly — if creation fails, inherit is silently
+  # disabled and profiling continues in single-process mode.
+  def self._setup_inherit(mode, frequency, signal, aggregate, inherit, defer)
+    session_dir = _create_session_dir(clean_stale: true)
+    return unless session_dir
+
+    ENV["RPERF_ROOT_PROCESS"] = Process.pid.to_s
+    ENV["RPERF_SESSION_DIR"] = session_dir
+    ENV["RPERF_DEFER"] = "1" if defer
+
+    # Remember the start options for forked children (_restart_in_child).
+    # Fork preserves module state, so this works for inherit: :fork too,
+    # where the RPERF_* env vars below are NOT exported.
+    @_child_start_opts = { mode: mode, frequency: frequency, signal: signal,
+                           aggregate: aggregate, defer: defer }
+
+    _install_fork_hook
+
+    if inherit == true
+      # inherit: true — also track spawned Ruby children via RUBYOPT.
+      # Save original values so _cleanup_session_state can restore them.
+      env_keys = %w[RPERF_ENABLED RPERF_FREQUENCY RPERF_MODE RPERF_SIGNAL RPERF_AGGREGATE RUBYLIB RUBYOPT]
+      @_saved_env = env_keys.to_h { |k| [k, ENV[k]] }
+
+      ENV["RPERF_ENABLED"] = "1"
+      ENV["RPERF_FREQUENCY"] = frequency.to_s
+      ENV["RPERF_MODE"] = mode.to_s
+      ENV["RPERF_SIGNAL"] = signal.nil? ? nil : signal.to_s
+      ENV["RPERF_AGGREGATE"] = aggregate ? nil : "0"
+      lib_dir = File.expand_path("..", __FILE__)
+      ENV["RUBYLIB"] = [lib_dir, ENV["RUBYLIB"]].compact.join(File::PATH_SEPARATOR)
+      ENV["RUBYOPT"] = "-rrperf #{ENV['RUBYOPT']}".strip
+    end
+  end
+  private_class_method :_setup_inherit
+
+  # Create session directory eagerly.  Returns the session dir path on success,
+  # nil on failure (caller should fall back to single-process mode).
+  # Try each candidate base in order.  If user_dir looks usable but
+  # session_dir creation fails (quota, ACL, sandbox, etc.), fall through
+  # to the next base instead of giving up.
+  # When clean_stale: true, removes session dirs from dead processes.
+  def self._create_session_dir(clean_stale: false)
+    require "securerandom"
+    require "tmpdir"
+
+    bases = [ENV["RPERF_TMPDIR"], ENV["XDG_RUNTIME_DIR"], Dir.tmpdir].compact
+    bases.each do |base|
+      user_dir = File.join(base, "rperf-#{Process.uid}")
+
+      if File.directory?(user_dir)
+        st = File.stat(user_dir) rescue next
+        next unless st.owned? && (st.mode & 0777) == 0700
+      elsif File.writable?(base)
+        begin
+          Dir.mkdir(user_dir, 0700)
+        rescue Errno::EEXIST
+          st = File.stat(user_dir) rescue next
+          next unless st.owned? && (st.mode & 0777) == 0700
+        rescue SystemCallError
+          next
+        end
+      else
+        next
+      end
+
+      if clean_stale
+        require "fileutils"
+        Dir.glob(File.join(user_dir, "rperf-*")).each do |dir|
+          m = File.basename(dir).match(/\Arperf-(\d+)-/)
+          next unless m
+          pid = m[1].to_i
+          begin
+            Process.kill(0, pid)
+          rescue Errno::ESRCH
+            FileUtils.rm_rf(dir)
+          rescue Errno::EPERM
+            # not ours
+          end
+        end
+      end
+
+      session_dir = File.join(user_dir, "rperf-#{Process.pid}-#{SecureRandom.hex(4)}")
+      begin
+        Dir.mkdir(session_dir, 0700)
+        return session_dir
+      rescue SystemCallError
+        next
+      end
+    end
+    nil
+  end
+  private_class_method :_create_session_dir
+
+  def self._parse_signal_env
+    case ENV["RPERF_SIGNAL"]
+    when nil then nil
+    when "false" then false
+    when /\A\d+\z/ then ENV["RPERF_SIGNAL"].to_i
+    end
+  end
+  private_class_method :_parse_signal_env
+
+  def self._install_fork_hook
+    return if @_fork_hook_installed
+    @_fork_hook_installed = true
+
+    ::Process.singleton_class.prepend(Module.new {
+      def _fork
+        if !Rperf.instance_variable_get(:@_session_dir_created) &&
+           Process.pid.to_s == ENV["RPERF_ROOT_PROCESS"]
+          Rperf._on_first_fork
+        end
+        pid = super
+        if pid == 0
+          Rperf._restart_in_child
+        end
+        pid
+      end
+    })
+  end
+  private_class_method :_install_fork_hook
+
+  def self._on_first_fork
+    return if @_session_dir_created
+    session_dir = ENV["RPERF_SESSION_DIR"]
+    return unless session_dir && File.directory?(session_dir)
+
+    @_session_dir_created = true
+    # Root's @output/@format/@stat are kept as-is (user's original settings).
+    # stop() writes root's profile to session dir with fixed json.gz format,
+    # then uses the original settings for the merged output.
+  end
+
+  def self._restart_in_child
+    session_dir = ENV["RPERF_SESSION_DIR"]
+    return unless session_dir && File.directory?(session_dir)
+    return if _c_running?  # should not happen, but guard against it
+
+    # C state is already cleaned up by pthread_atfork child handler.
+    @label_set_table = nil
+    @label_set_index = nil
+
+    require "securerandom"
+    # Random suffix: PIDs can be recycled within a long-lived session, and a
+    # plain profile-<pid> name would silently overwrite an earlier child's data
+    child_output = File.join(session_dir, "profile-#{Process.pid}-#{SecureRandom.hex(4)}.json.gz")
+
+    # Start options: prefer the values remembered by _setup_inherit (API
+    # inherit: :fork / true — fork preserves module state); fall back to the
+    # RPERF_* env vars (CLI-managed sessions always export them).
+    saved = @_child_start_opts
+    opts = {
+      frequency: saved ? saved[:frequency] : (ENV["RPERF_FREQUENCY"] || 1000).to_i,
+      mode: saved ? saved[:mode] : (ENV["RPERF_MODE"] == "cpu" ? :cpu : :wall),
+      aggregate: saved ? saved[:aggregate] : ENV["RPERF_AGGREGATE"] != "0",
+      output: child_output,
+      format: :json,
+      stat: false,
+      verbose: false,
+    }
+    sig = saved ? saved[:signal] : _parse_signal_env
+    opts[:signal] = sig unless sig.nil?
+    opts[:defer] = true if saved ? saved[:defer] : ENV["RPERF_DEFER"] == "1"
+
+    start(**opts, inherit: false)
+    @_session_dir_output = true
+    label("%pid": Process.pid.to_s)
+
+    # Register at_exit so child's profile is written even without explicit stop
+    at_exit { Rperf.stop }
+  end
+
+  # root_data: the root process's own profile data — GC/OS stats in the
+  # merged summary come from the root only (same policy as `rperf stat`).
+  def self._aggregate_and_report(root_data = nil)
+    session_dir = ENV["RPERF_SESSION_DIR"]
+    return unless session_dir && File.directory?(session_dir)
+
+    merged_samples = []
+    merged_label_sets = [{}]
+    merged_label_sets_index = { {} => 0 }
+    total_trigger_count = 0
+    total_sampling_count = 0
+    total_sampling_time_ns = 0
+    max_duration_ns = 0
+    total_duration_ns = 0
+    total_user_ns = 0
+    total_sys_ns = 0
+    process_count = 0
+
+    Dir.glob(File.join(session_dir, "profile-*.json.gz")).each do |file|
+      begin
+        data = load(file)
+      rescue StandardError => e
+        $stderr.puts "rperf: warning: failed to load #{file}: #{e.message}"
+        next
+      end
+      next unless data
+      _merge_into(merged_samples, merged_label_sets, data, merged_label_sets_index)
+      total_trigger_count += (data[:trigger_count] || 0)
+      total_sampling_count += (data[:sampling_count] || 0)
+      total_sampling_time_ns += (data[:sampling_time_ns] || 0)
+      d = data[:duration_ns] || 0
+      max_duration_ns = d if d > max_duration_ns
+      total_duration_ns += d
+      total_user_ns += (data[:user_ns] || 0)
+      total_sys_ns += (data[:sys_ns] || 0)
+      process_count += 1
+    end
+
+    if process_count == 0
+      # Nothing loadable — remove the session dir here, or stop's empty-dir
+      # rmdir would fail on the leftover corrupt files and leak the dir
+      _cleanup_session_dir(session_dir)
+      return
+    end
+
+    # mode/frequency: the root's own profile is authoritative; the env vars
+    # are only set by the CLI or inherit: true (and default to the root's
+    # actual settings via _setup_inherit for the API case)
+    saved = @_child_start_opts
+    merged_data = {
+      mode: (root_data && root_data[:mode]) || (saved ? saved[:mode] : (ENV["RPERF_MODE"] || "wall").to_sym),
+      frequency: (root_data && root_data[:frequency]) || (saved ? saved[:frequency] : (ENV["RPERF_FREQUENCY"] || 1000).to_i),
+      aggregated_samples: merged_samples,
+      label_sets: merged_label_sets,
+      trigger_count: total_trigger_count,
+      sampling_count: total_sampling_count,
+      sampling_time_ns: total_sampling_time_ns,
+      duration_ns: max_duration_ns,
+      total_duration_ns: total_duration_ns,
+      user_ns: total_user_ns,
+      sys_ns: total_sys_ns,
+      process_count: process_count,
+    }
+
+    if root_data
+      merged_data[:gc_stats] = root_data[:gc_stats] if root_data[:gc_stats]
+      merged_data[:maxrss_mb] = root_data[:maxrss_mb] if root_data[:maxrss_mb]
+    end
+
+    print_stat(merged_data) if @stat
+    if @output
+      write_data(@output, merged_data, @format)
+    end
+
+    _cleanup_session_dir(session_dir)
+
+    merged_data
+  rescue => e
+    $stderr.puts "rperf: warning: failed to aggregate multi-process data: #{e.message}"
+    # stop() falls back to writing the root's own data when this returns nil
+    _cleanup_session_dir(session_dir)
+    nil
+  end
+  # Not private — called from at_exit block which runs in top-level context
+
+  def self._cleanup_session_dir(session_dir)
+    require "fileutils"
+    FileUtils.rm_rf(session_dir)
+  rescue => e
+    $stderr.puts "rperf: warning: failed to clean up session dir: #{e.message}"
+  end
+  private_class_method :_cleanup_session_dir
+
+  def self._merge_into(merged_samples, merged_label_sets, data, merged_label_sets_index = nil)
+    # Build a reverse index when the caller doesn't maintain one across calls
+    unless merged_label_sets_index
+      merged_label_sets_index = {}
+      merged_label_sets.each_with_index { |ls, i| merged_label_sets_index[ls] = i }
+    end
+
+    child_label_sets = data[:label_sets] || [{}]
+    id_map = {}
+    child_label_sets.each_with_index do |ls, child_id|
+      # Normalize keys to symbols for consistent comparison
+      normalized = ls.is_a?(Hash) ? ls.transform_keys(&:to_sym) : ls
+      existing = merged_label_sets_index[normalized]
+      if existing
+        id_map[child_id] = existing
+      else
+        new_idx = merged_label_sets.size
+        id_map[child_id] = new_idx
+        merged_label_sets << normalized
+        merged_label_sets_index[normalized] = new_idx
+      end
+    end
+
+    (data[:aggregated_samples] || []).each do |frames, weight, thread_seq, label_set_id|
+      new_lsi = id_map[label_set_id || 0] || 0
+      merged_samples << [frames, weight, thread_seq, new_lsi]
+    end
+  end
+  private_class_method :_merge_into
+
   # ENV-based auto-start for CLI usage
   if ENV["RPERF_ENABLED"] == "1"
     _rperf_mode_str = ENV["RPERF_MODE"] || "cpu"
@@ -618,22 +1159,70 @@ module Rperf
                       ENV["RPERF_FORMAT"].to_sym
                     end
     _rperf_stat = ENV["RPERF_STAT"] == "1"
-    _rperf_signal = case ENV["RPERF_SIGNAL"]
-                    when nil then nil
-                    when "false" then false
-                    when /\A\d+\z/ then ENV["RPERF_SIGNAL"].to_i
-                    else raise ArgumentError, "RPERF_SIGNAL must be a signal number or 'false', got: #{ENV["RPERF_SIGNAL"].inspect}"
-                    end
+    _rperf_signal = _parse_signal_env
     _rperf_aggregate = ENV["RPERF_AGGREGATE"] != "0"
+    _rperf_original_output = _rperf_stat ? ENV["RPERF_OUTPUT"] : (ENV["RPERF_OUTPUT"] || "rperf.json.gz")
+
     _rperf_start_opts = { frequency: (ENV["RPERF_FREQUENCY"] || 1000).to_i, mode: _rperf_mode,
-                          output: _rperf_stat ? ENV["RPERF_OUTPUT"] : (ENV["RPERF_OUTPUT"] || "rperf.json.gz"),
                           verbose: ENV["RPERF_VERBOSE"] == "1",
-                          format: _rperf_format,
-                          stat: _rperf_stat,
                           aggregate: _rperf_aggregate }
     _rperf_start_opts[:signal] = _rperf_signal unless _rperf_signal.nil?
-    start(**_rperf_start_opts)
-    at_exit { stop }
+    _rperf_start_opts[:defer] = true if ENV["RPERF_DEFER"] == "1"
+
+    if ENV["RPERF_SESSION_DIR"] && Process.pid.to_s != ENV["RPERF_ROOT_PROCESS"]
+      # spawn / fork+exec child: write to session dir, no aggregation.
+      # Session dir is created eagerly by the root process (CLI or API).
+      # If it doesn't exist, skip profiling entirely — don't fall back to
+      # normal mode which would duplicate output with the root process.
+      _rperf_session_dir = ENV["RPERF_SESSION_DIR"]
+      if File.directory?(_rperf_session_dir)
+        require "securerandom"
+        # Random suffix: PID reuse must not overwrite an earlier child's profile
+        _rperf_start_opts[:output] = File.join(_rperf_session_dir, "profile-#{Process.pid}-#{SecureRandom.hex(4)}.json.gz")
+        _rperf_start_opts[:format] = :json
+        _rperf_start_opts[:stat] = false
+        _rperf_start_opts[:verbose] = false
+
+        _install_fork_hook
+        start(**_rperf_start_opts, inherit: false)
+        @_session_dir_output = true
+        label("%pid": Process.pid.to_s)
+        at_exit { stop }
+      end
+    elsif ENV["RPERF_SESSION_DIR"]
+      # Root process: start with normal output settings.
+      # If no fork/spawn happens, behaves exactly like single-process mode.
+      _rperf_start_opts[:output] = _rperf_original_output
+      _rperf_start_opts[:format] = _rperf_format
+      _rperf_start_opts[:stat] = _rperf_stat
+
+      _install_fork_hook
+      start(**_rperf_start_opts, inherit: false)
+
+      at_exit { Rperf.stop }
+    else
+      _rperf_start_opts[:output] = _rperf_original_output
+      _rperf_start_opts[:format] = _rperf_format
+      _rperf_start_opts[:stat] = _rperf_stat
+      _rperf_start_opts[:inherit] = false  # no RPERF_SESSION_DIR means --no-inherit
+      start(**_rperf_start_opts)
+      # --no-inherit: scrub the env the CLI injected for THIS process, so
+      # Ruby descendants spawned by the app don't auto-start their own
+      # sessions (and clobber RPERF_OUTPUT with their own profiles)
+      %w[RPERF_ENABLED RPERF_OUTPUT RPERF_STAT RPERF_FORMAT RPERF_VERBOSE
+         RPERF_FREQUENCY RPERF_MODE RPERF_SIGNAL RPERF_AGGREGATE
+         RPERF_DEFER].each { |k| ENV.delete(k) }
+      if ENV["RUBYOPT"]
+        rubyopt = ENV["RUBYOPT"].split(" ").reject { |o| o == "-rrperf" }.join(" ")
+        rubyopt.empty? ? ENV.delete("RUBYOPT") : ENV["RUBYOPT"] = rubyopt
+      end
+      if ENV["RUBYLIB"]
+        _rperf_lib_dir = File.expand_path("..", __FILE__)
+        rubylib = ENV["RUBYLIB"].split(File::PATH_SEPARATOR).reject { |p| p == _rperf_lib_dir }.join(File::PATH_SEPARATOR)
+        rubylib.empty? ? ENV.delete("RUBYLIB") : ENV["RUBYLIB"] = rubylib
+      end
+      at_exit { stop }
+    end
   end
 
   # Text report encoder — human/AI readable flat + cumulative top-N table.
@@ -687,7 +1276,10 @@ module Rperf
       return "" if !samples || samples.empty?
       merged = Hash.new(0)
       samples.each do |frames, weight|
-        key = frames.reverse.map { |_, label| label }.join(";")
+        # ";" is the frame separator and has no escape in the collapsed
+        # format — replace it so a pathological method name cannot corrupt
+        # stack splitting downstream (FlameGraph/speedscope)
+        key = frames.reverse.map { |_, label| label.include?(";") ? label.tr(";", ",") : label }.join(";")
         merged[key] += weight
       end
       merged.map { |stack, weight| "#{stack} #{weight}" }.join("\n") + "\n"
@@ -703,10 +1295,10 @@ module Rperf
     module_function
 
     def encode(data)
-      samples_raw = data[:aggregated_samples]
+      samples_raw = data[:aggregated_samples] || []
       frequency = data[:frequency]
-      interval_ns = 1_000_000_000 / frequency
-      mode = data[:mode] || :cpu
+      interval_ns = (frequency && frequency > 0) ? 1_000_000_000 / frequency : 0
+      mode = (data[:mode] || :cpu).to_sym
 
       # Build string table: index 0 must be ""
       string_table = [""]
@@ -722,7 +1314,7 @@ module Rperf
 
       # Convert string frames to index frames and merge identical stacks per thread/label
       merged = Hash.new(0)
-      thread_seq_key = intern.("thread_seq")
+      thread_seq_key = nil  # interned lazily — only when a sample carries thread_seq
       label_sets = data[:label_sets]  # Array of Hash (may be nil)
       samples_raw.each do |frames, weight, thread_seq, label_set_id|
         key = [frames.map { |path, label| [intern.(path), intern.(label)] }, thread_seq || 0, label_set_id || 0]
@@ -742,8 +1334,8 @@ module Rperf
         end
       end
 
-      # Build location/function tables
-      locations, functions = build_tables(merged.map { |(frames, _, _), w| [frames, w] })
+      # Build the frame → id table (locations and functions are 1:1)
+      frame_ids = build_tables(merged)
 
       # Intern type label and unit
       type_label = mode == :wall ? "wall" : "cpu"
@@ -759,11 +1351,12 @@ module Rperf
       # field 2: sample (repeated Sample) with thread_seq + user labels
       merged.each do |(frames, thread_seq, label_set_id), weight|
         sample_buf = "".b
-        loc_ids = frames.map { |f| locations[f] }
+        loc_ids = frames.map { |f| frame_ids[f] }
         sample_buf << encode_packed_uint64(1, loc_ids)
         sample_buf << encode_packed_int64(2, [weight])
         if thread_seq && thread_seq > 0
           label_buf = "".b
+          thread_seq_key ||= intern.("thread_seq")
           label_buf << encode_int64(1, thread_seq_key)  # key
           label_buf << encode_int64(3, thread_seq)       # num
           sample_buf << encode_message(3, label_buf)
@@ -782,19 +1375,18 @@ module Rperf
         buf << encode_message(2, sample_buf)
       end
 
-      # field 4: location (repeated Location)
-      locations.each do |frame, loc_id|
+      # field 4: location (repeated Location) — Line points at the same id
+      frame_ids.each do |_frame, id|
         loc_buf = "".b
-        loc_buf << encode_uint64(1, loc_id)
+        loc_buf << encode_uint64(1, id)
         line_buf = "".b
-        func_id = functions[frame]
-        line_buf << encode_uint64(1, func_id)
+        line_buf << encode_uint64(1, id)
         loc_buf << encode_message(4, line_buf)
         buf << encode_message(4, loc_buf)
       end
 
       # field 5: function (repeated Function)
-      functions.each do |frame, func_id|
+      frame_ids.each do |frame, func_id|
         func_buf = "".b
         func_buf << encode_uint64(1, func_id)
         func_buf << encode_int64(2, frame[1])    # name (label_idx)
@@ -841,22 +1433,23 @@ module Rperf
       buf
     end
 
+    # Assign sequential ids to unique frames.  rperf emits exactly one
+    # Location and one Function per frame, sharing the same id, so a single
+    # table serves both.
     def build_tables(merged)
-      locations = {}
-      functions = {}
+      frame_ids = {}
       next_id = 1
 
-      merged.each do |frames, _weight|
+      merged.each do |(frames, _thread_seq, _label_set_id), _weight|
         frames.each do |frame|
-          unless locations.key?(frame)
-            locations[frame] = next_id
-            functions[frame] = next_id
+          unless frame_ids.key?(frame)
+            frame_ids[frame] = next_id
             next_id += 1
           end
         end
       end
 
-      [locations, functions]
+      frame_ids
     end
 
     # --- Protobuf encoding helpers ---