rperf 0.9.0 → 0.10.0

data/ext/rperf/rperf.c

@@ -80,7 +80,11 @@ typedef struct rperf_sample_buffer {
     size_t sample_count;
     size_t sample_capacity;
     VALUE *frame_pool;
-    size_t frame_pool_count;
+    /* _Atomic: read by GC dmark concurrently with the aggregator's clear.
+     * Seq-cst accesses pair with the frame_table count release-stores so
+     * dmark never observes the cleared pool together with a stale
+     * frame_table count (which would leave frames unmarked). */
+    _Atomic size_t frame_pool_count;
     size_t frame_pool_capacity;
 } rperf_sample_buffer_t;
 
@@ -102,8 +106,6 @@ typedef struct rperf_frame_table {
 
 /* ---- Aggregation table: stack → weight ---- */
 
-#define RPERF_AGG_ENTRY_EMPTY 0
-
 typedef struct rperf_agg_entry {
     uint32_t frame_start;     /* offset into stack_pool */
     int depth;
@@ -145,7 +147,10 @@ typedef struct rperf_gc_state {
 /* ---- Sampling overhead stats ---- */
 
 typedef struct rperf_stats {
-    size_t trigger_count;
+    /* _Atomic: incremented by the signal handler / nanosleep worker, read and
+     * cleared by snapshot while running (atomic size_t is async-signal-safe
+     * when lock-free, which it is on all supported platforms). */
+    _Atomic size_t trigger_count;
     size_t sampling_count;
     int64_t sampling_total_ns;
     size_t dropped_samples;     /* samples lost due to allocation failure */
@@ -206,12 +211,17 @@ rperf_profiler_mark(void *ptr)
 {
     rperf_profiler_t *prof = (rperf_profiler_t *)ptr;
     int i;
-    /* Mark both sample buffers' frame_pools */
+    /* Mark both sample buffers' frame_pools.
+     * Load the count once: the aggregator may clear it concurrently, and the
+     * pools must be read BEFORE frame_table.count below — seeing the cleared
+     * count (seq-cst) guarantees the corresponding frame_table inserts are
+     * visible, so every frame is covered by at least one mark source. */
     for (i = 0; i < 2; i++) {
         rperf_sample_buffer_t *buf = &prof->buffers[i];
-        if (buf->frame_pool && buf->frame_pool_count > 0) {
+        size_t fp_count = buf->frame_pool_count;
+        if (buf->frame_pool && fp_count > 0) {
             rb_gc_mark_locations(buf->frame_pool,
-                                buf->frame_pool + buf->frame_pool_count);
+                                buf->frame_pool + fp_count);
         }
     }
     /* Mark label_sets array */
@@ -249,10 +259,8 @@ rperf_profiler_memsize(const void *ptr)
     /* Frame table */
     size += prof->frame_table.capacity * sizeof(VALUE);           /* keys */
     size += prof->frame_table.bucket_capacity * sizeof(uint32_t); /* buckets */
-    for (i = 0; i < prof->frame_table.old_keys_count; i++) {
-        /* old_keys entries are previous keys arrays; exact sizes unknown,
-         * but the pointer array itself is accounted for below. */
-    }
+    /* old_keys entries are previous keys arrays; exact sizes unknown,
+     * only the pointer array itself is accounted for. */
     size += prof->frame_table.old_keys_capacity * sizeof(VALUE *); /* old_keys */
 
     /* Aggregation table */
@@ -637,7 +645,12 @@ rperf_aggregate_buffer(rperf_profiler_t *prof, rperf_sample_buffer_t *buf)
         /* Convert VALUE frames to frame_ids */
         int overflow = 0;
         for (j = 0; j < s->depth; j++) {
-            if (s->frame_start + j >= buf->frame_pool_count) break;
+            if (s->frame_start + j >= buf->frame_pool_count) {
+                /* Defensive: sample points past the pool — truncate the
+                 * sample so we never hash/insert uninitialized temp_ids */
+                s->depth = j;
+                break;
+            }
             VALUE fval = buf->frame_pool[s->frame_start + j];
             uint32_t fid = rperf_frame_table_insert(&prof->frame_table, fval);
             if (fid == RPERF_FRAME_TABLE_EMPTY) { overflow = 1; break; }
@@ -648,6 +661,7 @@ rperf_aggregate_buffer(rperf_profiler_t *prof, rperf_sample_buffer_t *buf)
             prof->stats.dropped_aggregation += buf->sample_count - i;
             break;
         }
+        if (s->depth <= 0) continue;
 
         hash = rperf_fnv1a_u32(temp_ids, s->depth, s->thread_seq, s->label_set_id, s->vm_state);
 
@@ -753,7 +767,8 @@ static void
 rperf_handle_suspended(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t *td)
 {
     /* Has GVL — safe to call Ruby APIs */
-    int64_t wall_now = rperf_wall_time_ns();
+    /* suspended_at_ns is only consumed by RESUMED in wall mode */
+    int64_t wall_now = (prof->mode == RPERF_MODE_WALL) ? rperf_wall_time_ns() : 0;
 
     int is_first = 0;
 
@@ -766,19 +781,22 @@ rperf_handle_suspended(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t
     int64_t time_now = rperf_current_time_ns(prof);
     if (time_now < 0) return;
 
-    /* Capture backtrace into active buffer's frame_pool */
-    rperf_sample_buffer_t *buf = &prof->buffers[atomic_load_explicit(&prof->active_idx, memory_order_relaxed)];
-    if (rperf_ensure_frame_pool_capacity(buf, RPERF_MAX_STACK_DEPTH) < 0) return;
-    size_t frame_start = buf->frame_pool_count;
-    int depth = rb_profile_frames(0, RPERF_MAX_STACK_DEPTH,
-                                  &buf->frame_pool[frame_start], NULL);
-    if (depth <= 0) return;
-    buf->frame_pool_count += depth;
-
-    /* Record normal sample (skip if first time — no prev_time, or if paused) */
+    /* Record normal sample (skip if first time — no prev_time, or if paused).
+     * The backtrace is captured only when a sample is actually recorded:
+     * committing frames to the pool while paused would grow it without bound,
+     * because no aggregation runs until samples accumulate. */
     if (!is_first && !RPERF_PAUSED(prof)) {
-        int64_t weight = time_now - td->prev_time_ns;
-        rperf_record_sample(prof, frame_start, depth, weight, RPERF_VM_STATE_NORMAL, td->thread_seq, td->label_set_id);
+        rperf_sample_buffer_t *buf = &prof->buffers[atomic_load_explicit(&prof->active_idx, memory_order_relaxed)];
+        if (rperf_ensure_frame_pool_capacity(buf, RPERF_MAX_STACK_DEPTH) >= 0) {
+            size_t frame_start = buf->frame_pool_count;
+            int depth = rb_profile_frames(0, RPERF_MAX_STACK_DEPTH,
+                                          &buf->frame_pool[frame_start], NULL);
+            if (depth > 0) {
+                buf->frame_pool_count += depth;
+                int64_t weight = time_now - td->prev_time_ns;
+                rperf_record_sample(prof, frame_start, depth, weight, RPERF_VM_STATE_NORMAL, td->thread_seq, td->label_set_id);
+            }
+        }
     }
 
     /* Save timestamp for READY/RESUMED */
@@ -863,19 +881,26 @@ static void
 rperf_thread_event_hook(rb_event_flag_t event, const rb_internal_thread_event_data_t *data, void *user_data)
 {
     rperf_profiler_t *prof = (rperf_profiler_t *)user_data;
-    if (!prof->running) return;
 
     VALUE thread = data->thread;
     rperf_thread_data_t *td = (rperf_thread_data_t *)rb_internal_thread_specific_get(thread, prof->ts_key);
 
+    /* EXITED frees the thread's data even when running == 0: a thread can
+     * exit between stop setting running = 0 and the hook removal, and its td
+     * would otherwise leak (stop's Thread.list cleanup no longer sees it). */
+    if (event & RUBY_INTERNAL_THREAD_EVENT_EXITED) {
+        rperf_handle_exited(prof, thread, td);
+        return;
+    }
+
+    if (!prof->running) return;
+
     if (event & RUBY_INTERNAL_THREAD_EVENT_SUSPENDED)
         rperf_handle_suspended(prof, thread, td);
     else if (event & RUBY_INTERNAL_THREAD_EVENT_READY)
         rperf_handle_ready(td);
     else if (event & RUBY_INTERNAL_THREAD_EVENT_RESUMED)
         rperf_handle_resumed(prof, thread, td);
-    else if (event & RUBY_INTERNAL_THREAD_EVENT_EXITED)
-        rperf_handle_exited(prof, thread, td);
 }
 
 /* ---- GC event hook ---- */
@@ -1142,7 +1167,7 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
     rb_hash_aset(result, ID2SYM(rb_intern("frequency")), INT2NUM(prof->frequency));
     rb_hash_aset(result, ID2SYM(rb_intern("trigger_count")), SIZET2NUM(prof->stats.trigger_count));
     rb_hash_aset(result, ID2SYM(rb_intern("sampling_count")), SIZET2NUM(prof->stats.sampling_count));
-    rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LONG2NUM(prof->stats.sampling_total_ns));
+    rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LL2NUM(prof->stats.sampling_total_ns));
     if (prof->stats.dropped_samples > 0)
         rb_hash_aset(result, ID2SYM(rb_intern("dropped_samples")), SIZET2NUM(prof->stats.dropped_samples));
     if (prof->stats.dropped_aggregation > 0)
@@ -1161,8 +1186,8 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
                  + (int64_t)prof->start_realtime.tv_nsec;
         duration_ns = ((int64_t)now_monotonic.tv_sec - (int64_t)prof->start_monotonic.tv_sec) * 1000000000LL
                     + ((int64_t)now_monotonic.tv_nsec - (int64_t)prof->start_monotonic.tv_nsec);
-        rb_hash_aset(result, ID2SYM(rb_intern("start_time_ns")), LONG2NUM(start_ns));
-        rb_hash_aset(result, ID2SYM(rb_intern("duration_ns")), LONG2NUM(duration_ns));
+        rb_hash_aset(result, ID2SYM(rb_intern("start_time_ns")), LL2NUM(start_ns));
+        rb_hash_aset(result, ID2SYM(rb_intern("duration_ns")), LL2NUM(duration_ns));
     }
 
     {
@@ -1188,7 +1213,7 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
 
             VALUE sample = rb_ary_new_capa(5);
             rb_ary_push(sample, frames);
-            rb_ary_push(sample, LONG2NUM(e->weight));
+            rb_ary_push(sample, LL2NUM(e->weight));
             rb_ary_push(sample, INT2NUM(e->thread_seq));
             rb_ary_push(sample, INT2NUM(e->label_set_id));
             rb_ary_push(sample, INT2NUM(e->vm_state));
@@ -1313,6 +1338,14 @@ rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig, VAL
     /* Pre-initialize current thread's time so the first sample is not skipped */
     {
         VALUE cur_thread = rb_thread_current();
+        /* A stale td can survive a fork (the atfork child handler does not
+         * free the forking thread's data) — free it before creating a fresh
+         * one, or it would leak on every fork + restart cycle. */
+        rperf_thread_data_t *stale = (rperf_thread_data_t *)rb_internal_thread_specific_get(cur_thread, g_profiler.ts_key);
+        if (stale) {
+            free(stale);
+            rb_internal_thread_specific_set(cur_thread, g_profiler.ts_key, NULL);
+        }
         rperf_thread_data_t *td = rperf_thread_data_create(&g_profiler, cur_thread);
         if (!td) {
             rb_remove_event_hook(rperf_gc_event_hook);
@@ -1377,24 +1410,34 @@ rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig, VAL
         if (timer_create(CLOCK_MONOTONIC, &sev, &g_profiler.timer_id) != 0) {
             g_profiler.running = 0;
             sigaction(g_profiler.timer_signal, &g_profiler.old_sigaction, NULL);
+            /* Signal under the mutex — see rb_rperf_stop for the rationale */
+            CHECKED(pthread_mutex_lock(&g_profiler.worker_mutex));
             CHECKED(pthread_cond_signal(&g_profiler.worker_cond));
+            CHECKED(pthread_mutex_unlock(&g_profiler.worker_mutex));
             CHECKED(pthread_join(g_profiler.worker_thread, NULL));
             goto timer_fail;
         }
 
-        its.it_value.tv_sec = 0;
         if (RPERF_PAUSED(&g_profiler)) {
             /* defer mode: create timer but don't arm it */
+            its.it_value.tv_sec = 0;
             its.it_value.tv_nsec = 0;
         } else {
-            its.it_value.tv_nsec = 1000000000L / g_profiler.frequency;
+            /* Split into sec/nsec: frequency 1 gives a 1s interval, and
+             * tv_nsec must be < 1e9 or timer_settime fails with EINVAL */
+            long interval_ns = 1000000000L / g_profiler.frequency;
+            its.it_value.tv_sec = interval_ns / 1000000000L;
+            its.it_value.tv_nsec = interval_ns % 1000000000L;
         }
         its.it_interval = its.it_value;
         if (timer_settime(g_profiler.timer_id, 0, &its, NULL) != 0) {
             timer_delete(g_profiler.timer_id);
             g_profiler.running = 0;
             sigaction(g_profiler.timer_signal, &g_profiler.old_sigaction, NULL);
+            /* Signal under the mutex — see rb_rperf_stop for the rationale */
+            CHECKED(pthread_mutex_lock(&g_profiler.worker_mutex));
             CHECKED(pthread_cond_signal(&g_profiler.worker_cond));
+            CHECKED(pthread_mutex_unlock(&g_profiler.worker_mutex));
             CHECKED(pthread_join(g_profiler.worker_thread, NULL));
             goto timer_fail;
         }
@@ -1455,10 +1498,15 @@ rb_rperf_stop(VALUE self)
     }
 #endif
 
-    /* Wake and join worker thread.
+    /* Wake and join worker thread.  Signal while holding worker_mutex:
+     * the worker re-checks its predicate (running) with the mutex held, so
+     * signaling under the mutex guarantees it either sees running == 0 or is
+     * already inside cond_wait when the signal fires — no lost wakeup.
      * Any pending timer signals are still handled by rperf_signal_handler
      * (just increments trigger_count + calls rb_postponed_job_trigger). */
+    CHECKED(pthread_mutex_lock(&g_profiler.worker_mutex));
     CHECKED(pthread_cond_signal(&g_profiler.worker_cond));
+    CHECKED(pthread_mutex_unlock(&g_profiler.worker_mutex));
     CHECKED(pthread_join(g_profiler.worker_thread, NULL));
     CHECKED(pthread_mutex_destroy(&g_profiler.worker_mutex));
     CHECKED(pthread_cond_destroy(&g_profiler.worker_cond));
@@ -1517,7 +1565,7 @@ rb_rperf_stop(VALUE self)
         rb_hash_aset(result, ID2SYM(rb_intern("frequency")), INT2NUM(g_profiler.frequency));
         rb_hash_aset(result, ID2SYM(rb_intern("trigger_count")), SIZET2NUM(g_profiler.stats.trigger_count));
         rb_hash_aset(result, ID2SYM(rb_intern("sampling_count")), SIZET2NUM(g_profiler.stats.sampling_count));
-        rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LONG2NUM(g_profiler.stats.sampling_total_ns));
+        rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LL2NUM(g_profiler.stats.sampling_total_ns));
         if (g_profiler.stats.dropped_samples > 0)
             rb_hash_aset(result, ID2SYM(rb_intern("dropped_samples")), SIZET2NUM(g_profiler.stats.dropped_samples));
         if (g_profiler.stats.dropped_aggregation > 0)
@@ -1531,8 +1579,8 @@ rb_rperf_stop(VALUE self)
                      + (int64_t)g_profiler.start_realtime.tv_nsec;
             duration_ns = ((int64_t)stop_monotonic.tv_sec - (int64_t)g_profiler.start_monotonic.tv_sec) * 1000000000LL
                         + ((int64_t)stop_monotonic.tv_nsec - (int64_t)g_profiler.start_monotonic.tv_nsec);
-            rb_hash_aset(result, ID2SYM(rb_intern("start_time_ns")), LONG2NUM(start_ns));
-            rb_hash_aset(result, ID2SYM(rb_intern("duration_ns")), LONG2NUM(duration_ns));
+            rb_hash_aset(result, ID2SYM(rb_intern("start_time_ns")), LL2NUM(start_ns));
+            rb_hash_aset(result, ID2SYM(rb_intern("duration_ns")), LL2NUM(duration_ns));
         }
 
         samples_ary = rb_ary_new_capa((long)buf->sample_count);
@@ -1548,7 +1596,7 @@ rb_rperf_stop(VALUE self)
 
             VALUE sample = rb_ary_new_capa(5);
             rb_ary_push(sample, frames);
-            rb_ary_push(sample, LONG2NUM(s->weight));
+            rb_ary_push(sample, LL2NUM(s->weight));
             rb_ary_push(sample, INT2NUM(s->thread_seq));
             rb_ary_push(sample, INT2NUM(s->label_set_id));
             rb_ary_push(sample, INT2NUM(s->vm_state));
@@ -1684,10 +1732,13 @@ rperf_arm_timer(rperf_profiler_t *prof)
 #if RPERF_USE_TIMER_SIGNAL
     if (prof->timer_signal > 0) {
         struct itimerspec its;
-        its.it_value.tv_sec = 0;
-        its.it_value.tv_nsec = 1000000000L / prof->frequency;
+        long interval_ns = 1000000000L / prof->frequency;
+        its.it_value.tv_sec = interval_ns / 1000000000L;
+        its.it_value.tv_nsec = interval_ns % 1000000000L;
         its.it_interval = its.it_value;
-        timer_settime(prof->timer_id, 0, &its, NULL);
+        if (timer_settime(prof->timer_id, 0, &its, NULL) != 0) {
+            fprintf(stderr, "rperf: timer_settime (arm) failed: %s\n", strerror(errno));
+        }
         return;
     }
 #endif
@@ -1705,7 +1756,9 @@ rperf_disarm_timer(rperf_profiler_t *prof)
     if (prof->timer_signal > 0) {
         struct itimerspec its;
         memset(&its, 0, sizeof(its));
-        timer_settime(prof->timer_id, 0, &its, NULL);
+        if (timer_settime(prof->timer_id, 0, &its, NULL) != 0) {
+            fprintf(stderr, "rperf: timer_settime (disarm) failed: %s\n", strerror(errno));
+        }
         return;
     }
 #endif

data/lib/rperf/meta.rb

@@ -0,0 +1,343 @@
+# Profile metadata support: git/host info collection, summary statistics,
+# snapshot file naming, and a meta/summary prefix reader that lists profiles
+# without loading the sample body.
+#
+# JSON profiles written by rperf >= 0.10 place "meta" and "summary" as the
+# first two top-level keys, so Meta.read can decompress only the head of the
+# file and stop as soon as both are extracted.
+
+require "json"
+require "time"
+require "zlib"
+
+module Rperf
+  module Meta
+    FORMAT_VERSION = 1
+    TOP_METHODS_LIMIT = 50
+
+    module_function
+
+    # Collect git information for the profiled working directory.
+    # GitHub Actions environment variables take priority over git commands
+    # (CI checkouts may be detached or shallow). Returns a Hash with
+    # sha/branch/subject/committed_at/dirty, or nil when not in a git
+    # repository or git is unavailable.
+    def collect_git(dir = Dir.pwd)
+      gh_sha = ENV["GITHUB_SHA"]
+      # Validate the sha shape: the value is passed to git as a positional
+      # argument, and a crafted value starting with "-" would be parsed as
+      # a git option
+      if gh_sha && gh_sha.match?(/\A\h{7,64}\z/)
+        git = { sha: gh_sha, dirty: false }
+        branch = ENV["GITHUB_HEAD_REF"]
+        branch = ENV["GITHUB_REF_NAME"] if branch.nil? || branch.empty?
+        git[:branch] = branch if branch && !branch.empty?
+        # Enrich from the local checkout when possible (may fail on shallow clones)
+        subject = git_capture(dir, "log", "-1", "--format=%s", gh_sha)
+        committed_at = git_capture(dir, "log", "-1", "--format=%cI", gh_sha)
+        git[:subject] = subject if subject && !subject.empty?
+        git[:committed_at] = committed_at if committed_at && !committed_at.empty?
+        return git
+      end
+
+      sha = git_capture(dir, "rev-parse", "HEAD")
+      return nil if sha.nil? || sha.empty?
+
+      git = { sha: sha }
+      branch = git_capture(dir, "rev-parse", "--abbrev-ref", "HEAD")
+      git[:branch] = branch if branch && !branch.empty? && branch != "HEAD"
+      subject = git_capture(dir, "log", "-1", "--format=%s")
+      git[:subject] = subject if subject && !subject.empty?
+      committed_at = git_capture(dir, "log", "-1", "--format=%cI")
+      git[:committed_at] = committed_at if committed_at && !committed_at.empty?
+      status = git_capture(dir, "status", "--porcelain")
+      git[:dirty] = !status.empty? if status
+      git
+    end
+
+    # Run a git command, returning stripped stdout or nil on failure
+    # (no git binary, not a repository, etc.).
+    def git_capture(dir, *args)
+      out = IO.popen(["git", "-C", dir, *args], err: File::NULL, &:read)
+      $?.success? ? out.strip : nil
+    rescue SystemCallError
+      nil
+    end
+
+    # File name used by `rperf record --snapshot-dir`.
+    # In a git repository: rperf-<sha7>-<timestamp>.json.gz
+    # Outside:            rperf-nogit-<timestamp>-<pid>.json.gz
+    def snapshot_filename(git, time: Time.now.utc, pid: Process.pid)
+      ts = time.utc.strftime("%Y%m%dT%H%M%SZ")
+      if git && git[:sha]
+        "rperf-#{git[:sha][0, 7]}-#{ts}.json.gz"
+      else
+        "rperf-nogit-#{ts}-#{pid}.json.gz"
+      end
+    end
+
+    # Build the meta hash for a profile about to be written.
+    # Git info comes from RPERF_META_GIT (set by the CLI, which collects it
+    # before exec so a chdir in the profiled app cannot point at the wrong
+    # repository); when unset (direct API usage) it is collected here.
+    # RPERF_META_GIT="null" means "already checked, not a repository".
+    def build_meta(data)
+      meta = {
+        format_version: FORMAT_VERSION,
+        created_at: Time.now.utc.iso8601,
+        ruby_version: RUBY_VERSION,
+        rperf_version: Rperf::VERSION,
+        mode: (data[:mode] || :cpu).to_s,
+      }
+      hostname = safe_hostname
+      meta[:hostname] = hostname if hostname
+      git = git_from_env_or_collect
+      meta[:git] = git if git
+      labels = labels_from_env
+      meta[:labels] = labels if labels && !labels.empty?
+      meta
+    end
+
+    def git_from_env_or_collect
+      if ENV.key?("RPERF_META_GIT")
+        v = ENV["RPERF_META_GIT"].to_s
+        return nil if v.empty? || v == "null"
+        begin
+          JSON.parse(v, symbolize_names: true)
+        rescue JSON::ParserError
+          nil
+        end
+      else
+        # Memoized (array wraps a legitimate nil): periodic viewer snapshots
+        # must not spawn git subprocesses on every take_snapshot!
+        @collect_git_memo ||= [collect_git]
+        @collect_git_memo[0]
+      end
+    end
+
+    def labels_from_env
+      v = ENV["RPERF_META_LABELS"]
+      return nil unless v
+      begin
+        labels = JSON.parse(v)
+        labels.is_a?(Hash) ? labels : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    def safe_hostname
+      require "socket"
+      Socket.gethostname
+    rescue StandardError
+      nil
+    end
+
+    # Build the summary hash from profile data (as returned by Rperf.stop).
+    # Fields whose source data is missing are omitted.
+    def build_summary(data)
+      s = {}
+      s[:total_ms] = (data[:duration_ns] / 1e6).round(1) if data[:duration_ns]
+      if data[:user_ns] || data[:sys_ns]
+        s[:cpu_ms] = (((data[:user_ns] || 0) + (data[:sys_ns] || 0)) / 1e6).round(1)
+      end
+      if (gc = data[:gc_stats])
+        s[:gc_count_minor] = gc[:minor_count] if gc[:minor_count]
+        s[:gc_count_major] = gc[:major_count] if gc[:major_count]
+        s[:gc_ms] = gc[:time_ms].to_f.round(1) if gc[:time_ms]
+        s[:allocated_objects] = gc[:allocated_objects] if gc[:allocated_objects]
+        s[:freed_objects] = gc[:freed_objects] if gc[:freed_objects]
+      end
+      s[:maxrss_mb] = data[:maxrss_mb] if data[:maxrss_mb]
+      s[:samples] = data[:sampling_count] if data[:sampling_count]
+      s[:top_methods] = top_methods(data)
+      s
+    end
+
+    # Top methods by self time, merged by method name (shares the by-name
+    # fold with Table so report/summary numbers can never diverge).
+    def top_methods(data, limit: TOP_METHODS_LIMIT)
+      samples = data[:aggregated_samples]
+      return [] if !samples || samples.empty?
+
+      flat_by_name, cum_by_name, total = Table.flat_cum_by_name(data)
+      return [] if total <= 0
+
+      flat_by_name.sort_by { |_, w| -w }.first(limit).map do |name, w|
+        {
+          name: name,
+          self_pct: (w * 100.0 / total).round(1),
+          total_pct: (cum_by_name[name] * 100.0 / total).round(1),
+        }
+      end
+    end
+
+    # --- meta/summary prefix reader ---
+
+    READ_CHUNK = 64 * 1024
+    READ_LIMIT = 8 * 1024 * 1024
+
+    # Read meta/summary from a .json(.gz) profile without loading the body.
+    # Returns { meta: Hash|nil, summary: Hash|nil } or nil for files without
+    # leading meta/summary keys (old format) and unreadable/corrupt files.
+    def read(path)
+      File.open(path, "rb") do |f|
+        magic = f.read(2)
+        f.rewind
+        io = (magic == "\x1f\x8b".b) ? Zlib::GzipReader.new(f) : f
+        begin
+          buf = "".b
+          loop do
+            chunk = io.read(READ_CHUNK)
+            buf << chunk if chunk
+            result = scan_prefix(buf)
+            return result unless result == :incomplete
+            return nil if chunk.nil? || buf.bytesize > READ_LIMIT
+          end
+        ensure
+          # Free the inflate zstream now — directory listings open many files
+          # and the buffers would otherwise linger until GC
+          io.close if io.is_a?(Zlib::GzipReader)
+        end
+      end
+    rescue Zlib::Error, SystemCallError, JSON::ParserError
+      # Zlib::Error covers GzipFile::Error (truncated) and also DataError /
+      # BufError (valid gzip header, corrupt deflate body) — one corrupt
+      # snapshot must not break listing an entire directory
+      nil
+    end
+
+    # Byte codes used by the scanner. Byte-wise scanning is safe in UTF-8:
+    # continuation bytes are >= 0x80 and never collide with ASCII syntax.
+    DQUOTE = 0x22
+    BSLASH = 0x5c
+    LBRACE = 0x7b
+    RBRACE = 0x7d
+    LBRACKET = 0x5b
+    RBRACKET = 0x5d
+    COMMA = 0x2c
+    COLON = 0x3a
+
+    # Scan the head of a JSON object for top-level "meta" / "summary" keys.
+    # rperf writes them first, so scanning stops at the first other key —
+    # large sample arrays are never traversed.
+    # Returns { meta:, summary: }, nil (old format / malformed),
+    # or :incomplete (need more input).
+    def scan_prefix(buf)
+      n = buf.bytesize
+      i = skip_ws(buf, 0, n)
+      return :incomplete if i >= n
+      return nil unless buf.getbyte(i) == LBRACE
+      i += 1
+      found = {}
+
+      loop do
+        i = skip_ws(buf, i, n)
+        return :incomplete if i >= n
+        return finalize_scan(found) if buf.getbyte(i) == RBRACE
+        return nil unless buf.getbyte(i) == DQUOTE
+
+        key_start = i
+        i = scan_string(buf, i, n)
+        return :incomplete unless i
+        key = buf.byteslice(key_start + 1, i - key_start - 2)
+
+        # First key that is not meta/summary ends the scan (old format or body)
+        return finalize_scan(found) unless key == "meta" || key == "summary"
+
+        i = skip_ws(buf, i, n)
+        return :incomplete if i >= n
+        return nil unless buf.getbyte(i) == COLON
+        i += 1
+        i = skip_ws(buf, i, n)
+        return :incomplete if i >= n
+
+        vstart = i
+        i = scan_value(buf, i, n)
+        return :incomplete unless i
+        fragment = buf.byteslice(vstart, i - vstart).force_encoding(Encoding::UTF_8)
+        found[key.to_sym] = JSON.parse(fragment, symbolize_names: true)
+        return finalize_scan(found) if found.key?(:meta) && found.key?(:summary)
+
+        i = skip_ws(buf, i, n)
+        return :incomplete if i >= n
+        case buf.getbyte(i)
+        when COMMA then i += 1
+        when RBRACE then return finalize_scan(found)
+        else return nil
+        end
+      end
+    rescue JSON::ParserError
+      nil
+    end
+
+    def finalize_scan(found)
+      found.empty? ? nil : { meta: found[:meta], summary: found[:summary] }
+    end
+
+    def skip_ws(buf, i, n)
+      while i < n
+        b = buf.getbyte(i)
+        break unless b == 0x20 || b == 0x09 || b == 0x0a || b == 0x0d
+        i += 1
+      end
+      i
+    end
+
+    # Scan a JSON string starting at the opening quote.
+    # Returns the index just past the closing quote, or nil if truncated.
+    def scan_string(buf, i, n)
+      j = i + 1
+      while j < n
+        b = buf.getbyte(j)
+        if b == BSLASH
+          j += 2
+        elsif b == DQUOTE
+          return j + 1
+        else
+          j += 1
+        end
+      end
+      nil
+    end
+
+    # Scan a JSON value (string, container, or scalar) starting at i.
+    # Returns the index just past the value, or nil if truncated.
+    def scan_value(buf, i, n)
+      case buf.getbyte(i)
+      when DQUOTE
+        scan_string(buf, i, n)
+      when LBRACE, LBRACKET
+        depth = 0
+        j = i
+        while j < n
+          b = buf.getbyte(j)
+          if b == DQUOTE
+            j = scan_string(buf, j, n)
+            return nil unless j
+          elsif b == LBRACE || b == LBRACKET
+            depth += 1
+            j += 1
+          elsif b == RBRACE || b == RBRACKET
+            depth -= 1
+            j += 1
+            return j if depth == 0
+          else
+            j += 1
+          end
+        end
+        nil
+      else
+        # scalar: number, true, false, null
+        j = i
+        while j < n
+          b = buf.getbyte(j)
+          break if b == COMMA || b == RBRACE || b == RBRACKET ||
+                   b == 0x20 || b == 0x09 || b == 0x0a || b == 0x0d
+          j += 1
+        end
+        j < n ? j : nil
+      end
+    end
+  end
+end

data/lib/rperf/rack.rb

@@ -16,10 +16,15 @@ class Rperf::RackMiddleware
     @label_proc = label
   end
 
-  UUID_RE = %r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}i
-  NUMERIC_RE = %r{/\d+}
+  UUID_RE = %r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=/|\z)}i
+  NUMERIC_RE = %r{/\d+(?=/|\z)}
 
   def call(env)
+    # No-op when the profiler is not running (Rperf.profile would raise):
+    # the app may boot without Rperf.start, stop mid-run, or run in a forked
+    # worker where the atfork handler silently stopped profiling.
+    return @app.call(env) unless Rperf.running?
+
     endpoint = if @label_proc == :raw
       "#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"
     elsif @label_proc