vernier 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8d610b954485d3bccefa47408932dddd5806b618caa2958d689f8c0c8fbb3d
-  data.tar.gz: 2423bf5e06dd1168e21f0a5063050e897137c37bd09ce68a540af9d84b0a7546
+  metadata.gz: 245f2f630047ca4214da2d8a939a3948f96486f626137e4cc951fb0161e8bba4
+  data.tar.gz: 8b6b4240f03d8e058a1fcae78029d2cb102de0bdebf53da66690143a14a7b8fc
 SHA512:
-  metadata.gz: 942b097d843b63457650254b2e9717698939df9ee40c02ff367832d344121e6ffdafffbc2e0824d70229bf5d4187d1cf0eb64491402a4c54c4c5f6dd8fb0b98f
-  data.tar.gz: 2f710c6b9eeb8e4e352290902aed1a4142ea5b48df7039ee49de66dc7c9f7411e25cb77319addba69a15f072f08b3820a51535fe19070a4e77341aa6c000a57b
+  metadata.gz: e0f0a556ccb06c4b95e531f724224de59805ef0821c275f84b0c72e15603b045a24ccc6b420d17fd6cf34bda8c15e100fe4b433fdfa8b0dc2450a76267814c12
+  data.tar.gz: 453a6a97efa3ea492cd79dd4a7455933d88e3dd3128e298c75c466bdecbae88d7594a671e8c383f89b9201f67d1f6e442e2cb7060bb5274dcba29bcba673082a

data/README.md

@@ -1,6 +1,6 @@
 # Vernier
 
-Next-generation Ruby 3.2.1+ sampling profiler. Tracks multiple threads, GVL activity, GC pauses, idle time, and more.
+Next-generation Ruby 3.3+ sampling profiler. Tracks multiple threads, GVL activity, GC pauses, idle time, and more.
 
 <img width="500" alt="Screenshot 2024-02-29 at 22 47 43" src="https://github.com/jhawthorn/vernier/assets/131752/aa995a41-d74f-405f-8ada-2522dd72c2c8">
 
@@ -24,7 +24,7 @@ Rails benchmark - lobste.rs (time)
 
 ## Installation
 
-Vernier requires Ruby version 3.2.1 or greater and a Unix-like operating system.
+Vernier requires Ruby version 3.3 or greater and a Unix-like operating system.
 
 ```ruby
 gem "vernier", "~> 1.0"
@@ -193,14 +193,15 @@ See [`examples/custom_hook.rb`](examples/custom_hook.rb) for a complete example.
 
 ### Options
 
-| Option                | Middleware Param              | Description                                                   | Default (Middleware Default) |
-|-----------------------|-------------------------------|---------------------------------------------------------------|------------------------------|
-| `mode`                | N/A                           | Sampling mode: `:wall`, `:retained`, or `:custom`.            | `:wall` (`:wall`)            |
-| `out`                 | N/A                           | File to write the profile to.                                 | N/A (Auto-generated)         |
-| `interval`            | `vernier_interval`            | Sampling interval (µs). Only in `:wall` mode.                 | `500` (`200`)                |
-| `allocation_interval` | `vernier_allocation_interval` | Allocation sampling interval. Only in `:wall` mode.           | `0` i.e. disabled (`200`)    |
-| `gc`                  | N/A                           | Run full GC cycle before profiling. Only in `:retained` mode. | `true` (N/A)                 |
-| `metadata`            | N/A                           | Metadata key-value pairs to include in the profile.           | `{}` (N/A)                   |
+| Option                   | Middleware Param              | Description                                                   | Default (Middleware Default) |
+|--------------------------|-------------------------------|---------------------------------------------------------------|------------------------------|
+| `mode`                   | N/A                           | Sampling mode: `:wall`, `:retained`, or `:custom`.            | `:wall` (`:wall`)            |
+| `out`                    | N/A                           | File to write the profile to.                                 | N/A (Auto-generated)         |
+| `interval`               | `vernier_interval`            | Sampling interval (µs). Only in `:wall` mode.                 | `500` (`200`)                |
+| `allocation_interval`    | `vernier_allocation_interval` | Allocation sampling interval. Only in `:wall` mode.           | `0` i.e. disabled (`200`)    |
+| `gc`                     | N/A                           | Run full GC cycle before profiling. Only in `:retained` mode. | `true` (N/A)                 |
+| `metadata`               | N/A                           | Metadata key-value pairs to include in the profile.           | `{}` (N/A)                   |
+| `hide_anonymous_threads` | N/A                           | Anonymous threads will be initially hidden in profile output. | `false` (N/A)                |
 
 #### Hook options
 
@@ -218,6 +219,14 @@ Vernier.profile(out: "time_profile.json", hooks: [:rails, :memory_usage]) do
 end
 ```
 
+### Overhead
+
+Vernier is a sampling profiler, so its overhead is low and depends on the sampling `interval`. Profiling a CPU-bound loop at the default interval runs within a few percent of its unprofiled speed.
+
+Allocation sampling (`allocation_interval`) costs more, since every allocation takes a slower path and sampled allocations record a stack. The cost grows with how often the code allocates and how small the interval is.
+
+See [`examples/measure_overhead.rb`](examples/measure_overhead.rb) to measure it yourself.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/exe/vernier

@@ -51,6 +51,9 @@ FLAGS:
           options[:metadata] ||= Metadata.new
           options[:metadata] << [key, value]
         end
+        o.on('--hide-anonymous-threads', "Anonymous threads will be initially hidden in profiles") do
+          options[:hide_anonymous_threads] = true
+        end
         o.on('--format [FORMAT]', String, "output format: firefox (default) or cpuprofile") do |output_format|
           options[:format] = output_format
         end

data/ext/vernier/extconf.rb

@@ -6,10 +6,11 @@ $CXXFLAGS += " -fvisibility=hidden "
 $CXXFLAGS += " -std=c++14 "
 $CXXFLAGS += " -ggdb3 -Og "
 
-have_header("ruby/thread.h")
-have_struct_member("rb_internal_thread_event_data_t", "thread", ["ruby/thread.h"])
+# Make VERNIER_ASSERT always check, even if Ruby wasn't built with RUBY_DEBUG.
+# Set by our CI; gem installs get RUBY_ASSERT (compiled out) by default.
+$defs << "-DVERNIER_ALWAYS_ASSERT" if ["1", "true"].include?(ENV["VERNIER_ALWAYS_ASSERT"])
 
-have_func("rb_profile_thread_frames", "ruby/debug.h")
+have_header("ruby/thread.h")
 
 have_func("pthread_setname_np")
 have_func("pthread_condattr_setclock")

data/ext/vernier/heap_tracker.cc

@@ -27,14 +27,20 @@ class HeapTracker {
     unsigned long long objects_allocated = 0;
     unsigned long long tombstones = 0;
 
+    HeapTracker() = default;
+    HeapTracker(const HeapTracker &) = delete;
+    HeapTracker &operator=(const HeapTracker &) = delete;
+
     std::unordered_map<VALUE, int> object_index;
     std::vector<VALUE> object_list;
     std::vector<int> frame_list;
 
     static VALUE rb_new(VALUE self, VALUE stack_table_value) {
+      // get_stack_table can raise, so do it before allocating anything
+      StackTable *stack_table = get_stack_table(stack_table_value);
       HeapTracker *heap_tracker = new HeapTracker();
       heap_tracker->stack_table_value = stack_table_value;
-      heap_tracker->stack_table = get_stack_table(stack_table_value);
+      heap_tracker->stack_table = stack_table;
       VALUE obj = TypedData_Wrap_Struct(rb_cHeapTracker, &rb_heap_tracker_type, heap_tracker);
       rb_ivar_set(obj, rb_intern("@stack_table"), stack_table_value);
       return obj;
@@ -63,7 +69,7 @@ class HeapTracker {
       frame_list.push_back(stack_index);
       object_index.emplace(obj, idx);
 
-      assert(frame_list.size() == object_list.size());
+      VERNIER_ASSERT(frame_list.size() == object_list.size());
     }
 
     void rebuild() {
@@ -175,7 +181,7 @@ class HeapTracker {
     }
 
     VALUE data() {
-      assert(stopped);
+      VERNIER_ASSERT(stopped);
       VALUE hash = rb_hash_new();
       VALUE samples = rb_ary_new();
       rb_hash_aset(hash, sym("samples"), samples);
@@ -222,6 +228,7 @@ class HeapTracker {
       object_index.clear();
       for (int i = 0; i < object_list.size(); i++) {
         VALUE obj = object_list[i];
+        if (obj == Qfalse) continue; // tombstone
         VALUE reloc_obj = rb_gc_location(obj);
 
         object_list[i] = reloc_obj;

data/ext/vernier/memory.cc

@@ -72,7 +72,7 @@ class MemoryTracker : public PeriodicThread {
         MemoryTracker() : PeriodicThread(TimeStamp::from_milliseconds(10)) {
         }
 
-        void run_iteration() {
+        void run_iteration() override {
             record();
         }
 
@@ -82,12 +82,19 @@ class MemoryTracker : public PeriodicThread {
         }
 };
 
+static void
+memory_tracker_free(void *data) {
+    MemoryTracker *memory_tracker = static_cast<MemoryTracker *>(data);
+    // The sampler thread holds a pointer to the tracker, so it must be
+    // stopped (and joined) before the tracker is destroyed.
+    memory_tracker->stop();
+    delete memory_tracker;
+}
+
 static const rb_data_type_t rb_memory_tracker_type = {
     .wrap_struct_name = "vernier/memory_tracker",
     .function = {
-        //.dmark = memory_tracker_mark,
-        //.dfree = memory_tracker_free,
-        //.dsize = memory_tracker_memsize,
+        .dfree = memory_tracker_free,
     },
 };
 
@@ -116,9 +123,16 @@ VALUE memory_tracker_record(VALUE self) {
 VALUE memory_tracker_results(VALUE self) {
     MemoryTracker *memory_tracker;
     TypedData_Get_Struct(self, MemoryTracker, &rb_memory_tracker_type, memory_tracker);
+    // Copy under the lock; don't call into Ruby (which can allocate, GC or
+    // raise) while holding it.
+    std::vector<MemoryTracker::Record> results;
+    {
+        const std::lock_guard<std::mutex> lock(memory_tracker->mutex);
+        results = memory_tracker->results;
+    }
     VALUE timestamps = rb_ary_new();
     VALUE memory = rb_ary_new();
-    for (const auto& record: memory_tracker->results) {
+    for (const auto& record: results) {
         rb_ary_push(timestamps, ULL2NUM(record.timestamp.nanoseconds()));
         rb_ary_push(memory, ULL2NUM(record.memory_rss));
     }

data/ext/vernier/periodic_thread.hh

@@ -1,6 +1,7 @@
 #include "ruby.h"
 
 #include <atomic>
+#include <errno.h>
 #include "timestamp.hh"
 
 #ifdef __APPLE__
@@ -41,7 +42,7 @@ inline void upgrade_thread_priority(pthread_t pthread) {
 #endif
 
 class PeriodicThread {
-    pthread_t pthread;
+    pthread_t pthread = 0;
     TimeStamp interval;
 
     pthread_mutex_t running_mutex = PTHREAD_MUTEX_INITIALIZER;
@@ -56,8 +57,20 @@ class PeriodicThread {
             pthread_condattr_setclock(&attr, CLOCK_MONOTONIC);
 #endif
             pthread_cond_init(&running_cv, &attr);
+            pthread_condattr_destroy(&attr);
         }
 
+        // Deleting through a base pointer must run the derived destructor.
+        // Subclasses must stop() the thread before they are destroyed, as it
+        // calls their virtual run_iteration().
+        virtual ~PeriodicThread() {
+            pthread_cond_destroy(&running_cv);
+            pthread_mutex_destroy(&running_mutex);
+        }
+
+        PeriodicThread(const PeriodicThread &) = delete;
+        PeriodicThread &operator=(const PeriodicThread &) = delete;
+
         void set_interval(TimeStamp timestamp) {
             interval = timestamp;
         }
@@ -99,10 +112,12 @@ class PeriodicThread {
                     auto offset = TimeStamp::NowRealtime() - TimeStamp::Now();
                     struct timespec next_sample_ts = (next_sample_schedule + offset).timespec();
 #endif
+                    // Wait until the deadline passes or we are asked to stop.
+                    // Wakeups may be spurious, so only a timeout ends the wait.
                     int ret;
                     do {
                         ret = pthread_cond_timedwait(&running_cv, &running_mutex, &next_sample_ts);
-                    } while(running && ret == EINTR);
+                    } while (running && ret != ETIMEDOUT);
                 }
                 done = !running;
                 pthread_mutex_unlock(&running_mutex);

data/ext/vernier/signal_safe_semaphore.hh

@@ -25,6 +25,9 @@ class SignalSafeSemaphore {
 
     public:
 
+    SignalSafeSemaphore(const SignalSafeSemaphore &) = delete;
+    SignalSafeSemaphore &operator=(const SignalSafeSemaphore &) = delete;
+
     SignalSafeSemaphore(unsigned int value = 0) {
 #ifdef __APPLE__
         sem = dispatch_semaphore_create(value);
@@ -56,7 +59,6 @@ class SignalSafeSemaphore {
         if (ret != 0) {
             rb_bug("VERNIER: sem_timedwait waited over 5 seconds");
         }
-        assert(ret == 0);
 #endif
     }
 

data/ext/vernier/stack_table.cc

@@ -53,6 +53,9 @@ stack_table_current_stack(int argc, VALUE *argv, VALUE self) {
     RawSample stack;
     stack.sample(offset);
     int stack_index = stack_table->stack_index(stack);
+    if (stack_index < 0) {
+        rb_raise(rb_eArgError, "no stack at the given offset");
+    }
     return INT2NUM(stack_index);
 }
 
@@ -174,7 +177,6 @@ StackTable::stack_table_func_name(VALUE self, VALUE idxval) {
         return Qnil;
     } else {
         const auto &func_info = table[idx];
-        std::string label = func_info.full_label();
 
         // Ruby constants are in an arbitrary (ASCII compatible) encoding and
         // method names are in an arbitrary (ASCII compatible) encoding. These
@@ -188,7 +190,18 @@ StackTable::stack_table_func_name(VALUE self, VALUE idxval) {
         //
         // In the future we might keep class and method name separate for
         // longer, preserve encodings, and defer formatting to the Ruby side.
-        return rb_enc_interned_str(label.c_str(), label.length(), rb_utf8_encoding());
+        //
+        // The label is assembled directly in a Ruby string so that no C++
+        // temporaries are alive across calls that may raise.
+        VALUE str = rb_utf8_str_new("", 0);
+        if (!func_info.method_name.empty()) {
+            rb_str_cat(str, func_info.classpath.data(), func_info.classpath.size());
+            rb_str_cat(str, func_info.is_singleton ? "." : "#", 1);
+            rb_str_cat(str, func_info.method_name.data(), func_info.method_name.size());
+        } else {
+            rb_str_cat(str, func_info.label.data(), func_info.label.size());
+        }
+        return rb_str_to_interned_str(str);
     }
 }
 
@@ -202,8 +215,7 @@ StackTable::stack_table_func_filename(VALUE self, VALUE idxval) {
         return Qnil;
     } else {
         const auto &func_info = table[idx];
-        std::string filename = func_info.absolute_path;
-        if (filename.empty()) filename = func_info.path;
+        const std::string &filename = func_info.absolute_path.empty() ? func_info.path : func_info.absolute_path;
 
         // Technically filesystems are binary and then Ruby interprets that as
         // default_external encoding. But to keep things simple for now we are
@@ -222,7 +234,7 @@ StackTable::stack_table_func_path(VALUE self, VALUE idxval) {
         return Qnil;
     } else {
         const auto &func_info = table[idx];
-        std::string filename = func_info.path;
+        const std::string &filename = func_info.path;
 
         // Technically filesystems are binary and then Ruby interprets that as
         // default_external encoding. But to keep things simple for now we are
@@ -241,7 +253,7 @@ StackTable::stack_table_func_absolute_path(VALUE self, VALUE idxval) {
         return Qnil;
     } else {
         const auto &func_info = table[idx];
-        std::string filename = func_info.absolute_path;
+        const std::string &filename = func_info.absolute_path;
 
         // Technically filesystems are binary and then Ruby interprets that as
         // default_external encoding. But to keep things simple for now we are

data/ext/vernier/stack_table.hh

@@ -2,7 +2,7 @@
 #define STACK_TABLE_HH STACK_TABLE_HH
 
 #include <mutex>
-#include <stdexcept>
+#include <algorithm>
 #include <string>
 #include <unordered_map>
 #include <vector>
@@ -30,7 +30,11 @@ namespace std {
     {
         std::size_t operator()(Frame const& s) const noexcept
         {
-            return s.frame ^ s.line;
+            // VALUEs are aligned so their low bits carry no entropy; mix in
+            // the line number rather than xoring it into the low bits.
+            std::size_t h = static_cast<std::size_t>(s.frame) >> 3;
+            h ^= static_cast<std::size_t>(s.line) + 0x9e3779b97f4a7c15ULL + (h << 6) + (h >> 2);
+            return h;
         }
     };
 }
@@ -50,7 +54,7 @@ class RawSample {
 
     public:
 
-    RawSample() : len(0), gc(false), offset(0) { }
+    RawSample() : len(0), offset(0), gc(false) { }
 
     int size() const {
         return len - offset;
@@ -58,7 +62,7 @@ class RawSample {
 
     Frame frame(int i) const {
         int idx = len - i - 1;
-        if (idx < 0) throw std::out_of_range("VERNIER BUG: index out of range");
+        if (idx < 0) rb_bug("VERNIER BUG: index out of range");
         const Frame frame = {frames[idx], lines[idx]};
         return frame;
     }
@@ -95,34 +99,22 @@ struct FuncInfo {
         return NIL_P(first_lineno) ? 0 : FIX2INT(first_lineno);
     }
 
+    // Must not raise: this runs while std::string members are under
+    // construction, and a longjmp would skip their destructors.
     static std::string convert_rstring(VALUE rstring) {
-        if (NIL_P(rstring)) {
+        if (!RB_TYPE_P(rstring, T_STRING)) {
             return "";
-        } else {
-            const char *cstring = StringValueCStr(rstring);
-            return cstring;
-        }
-    }
-
-    std::string full_label() const {
-        std::string output;
-        if (!method_name.empty()) {
-            output.append(classpath);
-            output.append(is_singleton ? "." : "#");
-            output.append(method_name);
-        } else {
-            output.append(label);
         }
-        return output;
+        return std::string(RSTRING_PTR(rstring), RSTRING_LEN(rstring));
     }
 
     FuncInfo(VALUE frame) :
         label(convert_rstring(rb_profile_frame_label(frame))),
         base_label(convert_rstring(rb_profile_frame_base_label(frame))),
         classpath(convert_rstring(rb_profile_frame_classpath(frame))),
+        path(convert_rstring(rb_profile_frame_path(frame))),
         absolute_path(convert_rstring(rb_profile_frame_absolute_path(frame))),
         method_name(convert_rstring(rb_profile_frame_method_name(frame))),
-        path(convert_rstring(rb_profile_frame_path(frame))),
         first_lineno(first_lineno_int(frame)),
         is_singleton(RTEST(rb_profile_frame_singleton_method_p(frame)))
     { }
@@ -171,6 +163,10 @@ class IndexMap {
 };
 
 struct StackTable {
+    StackTable() = default;
+    StackTable(const StackTable &) = delete;
+    StackTable &operator=(const StackTable &) = delete;
+
     private:
 
     IndexMap<Frame> frame_map;
@@ -184,10 +180,10 @@ struct StackTable {
         int parent;
         int index;
 
-        StackNode(Frame frame, int index, int parent) : frame(frame), index(index), parent(parent) {}
+        StackNode(Frame frame, int index, int parent) : frame(frame), parent(parent), index(index) {}
 
         // root
-        StackNode() : frame(Frame{0, 0}), index(-1), parent(-1) {}
+        StackNode() : frame(Frame{0, 0}), parent(-1), index(-1) {}
     };
 
     // This mutex guards the StackNodes only. The rest of the maps and vectors
@@ -218,9 +214,11 @@ struct StackTable {
 
     public:
 
+    // Returns -1 for an empty stack. Never throws, as it may be called from
+    // C callbacks invoked by Ruby.
     int stack_index(const RawSample &stack) {
         if (stack.empty()) {
-            throw std::runtime_error("VERNIER BUG: empty stack");
+            return -1;
         }
 
         const std::lock_guard<std::mutex> lock(stack_mutex);
@@ -260,8 +258,8 @@ struct StackTable {
                 const auto &stack_node = stack_node_list[i];
                 frame_map.index(stack_node.frame);
                 func_map.index(stack_node.frame.frame);
-                stack_node_list_finalized_idx = i;
             }
+            stack_node_list_finalized_idx = stack_node_list.size();
         }
 
         for (int i = func_info_list.size(); i < func_map.size(); i++) {
@@ -274,7 +272,7 @@ struct StackTable {
     void mark_frames() {
         const std::lock_guard<std::mutex> lock(stack_mutex);
 
-        for (auto stack_node: stack_node_list) {
+        for (const auto &stack_node: stack_node_list) {
             rb_gc_mark(stack_node.frame.frame);
         }
     }