vernier 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56faced9b5a5fe99a124ab7743609eb23a981ca27888a5a8957e509d28f508ef
-  data.tar.gz: 0b258dc2f1f4c143568527213a3f39055a44aed3c983c84a14f71d6af68c900a
+  metadata.gz: 73ae72f3ced0043f71cc0fd1f8b5c829b57d6d4c7c39536a6564c8bcb654dfbd
+  data.tar.gz: c392fff41de6efe80ed825087ed92760493345aa04a18b288bae8d5afa166b88
 SHA512:
-  metadata.gz: '096133a98cfc38236c89025c51f70a0c4def9c6208031775d11640291d08b17d53fb2817d6f9b7fea1e7d0551ac0e58471d757fd5568c732969d73134ca20fc3'
-  data.tar.gz: 063ce46032770d8d2cd161071587dea386af0497a9437d8bc19148c54263e32c2d4d00b164c926ff19f1236f704f1c76aabff8be63bb2b66cd7409f69742004b
+  metadata.gz: e8c95c63b4836d7a160003a7ad2be68c54d135ba34ad663246b563f4e2f5954351a0e8c1e47ee4392b27a980cba8d395b607b1093487305abbcb21dd5467d5f1
+  data.tar.gz: 3a516ab9a0f52dfeaeecf8332c92cd63e160c9e51478ac6e8f30b846e1319d16b5132a8e7a6007ca582c46f3d6bdd8d96a88b9c686fb208de97779646f070a38

data/README.md

@@ -22,7 +22,7 @@ Rails benchmark - lobste.rs (time)
 
 ## Installation
 
-Vernier requires Ruby version 3.2.1 or greater
+Vernier requires Ruby version 3.2.1 or greater.
 
 ```ruby
 gem "vernier", "~> 1.0"
@@ -30,24 +30,29 @@ gem "vernier", "~> 1.0"
 
 ## Usage
 
-The output can be viewed in the web app at https://vernier.prof or locally using the [`profile-viewer` gem](https://github.com/tenderlove/profiler/tree/ruby) (both are lightly customized versions of the firefox profiler frontend, which profiles are also compatible with).
+The output can be viewed in the web app at https://vernier.prof, locally using the [`profile-viewer` gem](https://github.com/tenderlove/profiler/tree/ruby) (both lightly customized versions of the firefox profiler frontend, which profiles are also compatible with) or by using the `verrnier view` command in the CLI.
 
 - **Flame Graph**: Shows proportionally how much time is spent within particular stack frames. Frames are grouped together, which means that x-axis / left-to-right order is not meaningful.
 - **Stack Chart**: Shows the stack at each sample with the x-axis representing time and can be read left-to-right.
 
-
-### Time
-
+### Time and Allocations
 
 #### Command line
 
-The easiest way to record a program or script is via the CLI
+The easiest way to record a program or script is via the CLI:
 
 ```
 $ vernier run -- ruby -e 'sleep 1'
-starting profiler with interval 500
-#<Vernier::Result 1.001589 seconds, 1 threads, 2002 samples, 1 unique>
-written to /tmp/profile20240328-82441-gkzffc.vernier.json
+starting profiler with interval 500 and allocation interval 0
+#<Vernier::Result 1.001589 seconds, 1 threads, 1 samples, 1 unique>
+written to /tmp/profile20240328-82441-gkzffc.vernier.json.gz
+```
+
+```
+$ vernier run --interval 100 --allocation-interval 10 -- ruby -e '10.times { Object.new }'
+starting profiler with interval 100 and allocation interval 10
+#<Vernier::Result 0.00067 seconds, 1 threads, 1 samples, 1 unique>
+written to /tmp/profile20241029-26525-dalmym.vernier.json.gz
 ```
 
 #### Block of code
@@ -58,12 +63,18 @@ Vernier.profile(out: "time_profile.json") do
 end
 ```
 
+``` ruby
+Vernier.profile(out: "time_profile.json", interval: 100, allocation_interval: 10) do
+  some_slow_method
+end
+```
+
 Alternatively you can use the aliases `Vernier.run` and `Vernier.trace`.
 
 #### Start and stop
 
 ```ruby
-Vernier.start_profile(out: "time_profile.json")
+Vernier.start_profile(out: "time_profile.json", interval: 10_000, allocation_interval: 100_000)
 
 some_slow_method
 
@@ -78,13 +89,14 @@ Vernier.stop_profile
 
 #### Block of code
 
-Record a flamegraph of all **retained** allocations from loading `irb`.
+Record a flamegraph of all **retained** allocations from loading `irb`:
 
 ```
 ruby -r vernier -e 'Vernier.trace_retained(out: "irb_profile.json") { require "irb" }'
 ```
 
-Retained-memory flamegraphs must be interpreted a little differently than a typical profiling flamegraph. In a retained-memory flamegraph, the x-axis represents a proportion of memory in bytes,  _not time or samples_ The topmost boxes on the y-axis represent the retained objects, with their stacktrace below; their width represents the percentage of overall retained memory each object occupies.
+> [!NOTE]
+> Retained-memory flamegraphs must be interpreted a little differently than a typical profiling flamegraph. In a retained-memory flamegraph, the x-axis represents a proportion of memory in bytes,  _not time or samples_ The topmost boxes on the y-axis represent the retained objects, with their stacktrace below; their width represents the percentage of overall retained memory each object occupies.
 
 ### Options
 
@@ -93,7 +105,7 @@ Option | Description
 `mode` | The sampling mode to use. One of `:wall`, `:retained` or `:custom`. Default is `:wall`.
 `out` | The file to write the profile to.
 `interval` | The sampling interval in microseconds. Default is `500`. Only available in `:wall` mode.
-`allocation_sample_rate` | The allocation sampling interval in number of allocations. Default is `0` (disabled). Only available in `:wall` mode.
+`allocation_interval` | The allocation sampling interval in number of allocations. Default is `0` (disabled). Only available in `:wall` mode.
 `gc` | Initiate a full and immediate garbage collection cycle before profiling. Default is `true`. Only available in `:retained` mode.
 
 ## Development

data/examples/measure_overhead.rb

@@ -30,10 +30,10 @@ compare do
   end
 end
 
-compare(allocation_sample_rate: 1000) do
+compare(allocation_interval: 1000) do
   Object.new
 end
 
-compare(allocation_sample_rate: 1) do
+compare(allocation_interval: 1) do
   Object.new
 end

data/examples/rails.rb

@@ -123,7 +123,7 @@ end
 # warm up
 make_request.call
 
-Vernier.trace(out: "rails.json", hooks: [:rails], allocation_sample_rate: 100) do |collector|
+Vernier.trace(out: "rails.json", hooks: [:rails], allocation_interval: 100) do |collector|
   1000.times do
     make_request.call
   end

data/examples/threaded_http_requests.rb

@@ -1,6 +1,6 @@
 require "vernier"
 
-Vernier.trace(out: "http_requests.json", allocation_sample_rate: 100) do
+Vernier.trace(out: "http_requests.json", allocation_interval: 100) do
 
 require "net/http"
 require "uri"

data/exe/vernier

@@ -21,8 +21,8 @@ FLAGS:
         o.on('--interval [MICROSECONDS]', Integer, "sampling interval (default 500)") do |i|
           options[:interval] = i
         end
-        o.on('--allocation_sample_rate [ALLOCATIONS]', Integer, "allocation sampling interval (default 0 disabled)") do |i|
-          options[:allocation_sample_rate] = i
+        o.on('--allocation-interval [ALLOCATIONS]', Integer, "allocation sampling interval (default 0 disabled)") do |i|
+          options[:allocation_interval] = i
         end
         o.on('--signal [NAME]', String, "specify a signal to start and stop the profiler") do |s|
           options[:signal] = s
@@ -30,7 +30,7 @@ FLAGS:
         o.on('--start-paused', "don't automatically start the profiler") do
           options[:start_paused] = true
         end
-        o.on('--hooks [HOOKS]', String, "Enable instrumentation hooks. Currently supported: rails") do |s|
+        o.on('--hooks [HOOKS]', String, "enable instrumentation hooks, currently supported: rails") do |s|
           options[:hooks] = s
         end
       end
@@ -38,7 +38,7 @@ FLAGS:
 
     def self.view(options)
       banner = <<-END
-Usage: vernier view [FLAGS] FILENAME
+Usage: vernier view [FLAGS] -- FILENAME
 
 FLAGS:
       END

data/ext/vernier/vernier.cc

@@ -1114,7 +1114,11 @@ class Thread {
             sample.sample();
 
             int stack_idx = translator.translate(frame_list, sample);
-            allocation_samples.record_sample(stack_idx, TimeStamp::Now(), 1);
+            if (stack_idx >= 0) {
+                allocation_samples.record_sample(stack_idx, TimeStamp::Now(), 1);
+            } else {
+                // TODO: should we log an empty frame?
+            }
         }
 
         void set_state(State new_state) {
@@ -1333,7 +1337,7 @@ class BaseCollector {
     virtual void write_meta(VALUE meta, VALUE result) {
         rb_hash_aset(meta, sym("started_at"), ULL2NUM(started_at.nanoseconds()));
         rb_hash_aset(meta, sym("interval"), Qnil);
-        rb_hash_aset(meta, sym("allocation_sample_rate"), Qnil);
+        rb_hash_aset(meta, sym("allocation_interval"), Qnil);
 
     }
 
@@ -1356,6 +1360,9 @@ class BaseCollector {
         rb_gc_mark(stack_table_value);
     };
 
+    virtual void compact() {
+    };
+
     virtual VALUE get_markers() {
         return rb_ary_new();
     };
@@ -1543,6 +1550,23 @@ class RetainedCollector : public BaseCollector {
         rb_gc_mark(tp_newobj);
         rb_gc_mark(tp_freeobj);
     }
+
+    void compact() {
+        RetainedCollector *collector = this;
+        for (auto& obj: collector->object_list) {
+            VALUE reloc_obj = rb_gc_location(obj);
+            
+            const auto search = collector->object_frames.find(obj);
+            if (search != collector->object_frames.end()) {
+                int stack_index = search->second;
+                
+                collector->object_frames.erase(search);
+                collector->object_frames.emplace(reloc_obj, stack_index);
+            }
+            
+            obj = reloc_obj;
+        }
+    }
 };
 
 class GlobalSignalHandler {
@@ -1623,8 +1647,8 @@ class TimeCollector : public BaseCollector {
     SignalSafeSemaphore thread_stopped;
 
     TimeStamp interval;
-    unsigned int allocation_sample_rate;
-    unsigned int allocation_sample_tick = 0;
+    unsigned int allocation_interval;
+    unsigned int allocation_tick = 0;
 
     VALUE tp_newobj = Qnil;
 
@@ -1637,14 +1661,14 @@ class TimeCollector : public BaseCollector {
     }
 
     public:
-    TimeCollector(VALUE stack_table, TimeStamp interval, unsigned int allocation_sample_rate) : BaseCollector(stack_table), interval(interval), allocation_sample_rate(allocation_sample_rate), threads(*get_stack_table(stack_table)) {
+    TimeCollector(VALUE stack_table, TimeStamp interval, unsigned int allocation_interval) : BaseCollector(stack_table), interval(interval), allocation_interval(allocation_interval), threads(*get_stack_table(stack_table)) {
     }
 
     void record_newobj(VALUE obj) {
-        if (++allocation_sample_tick < allocation_sample_rate) {
+        if (++allocation_tick < allocation_interval) {
             return;
         }
-        allocation_sample_tick = 0;
+        allocation_tick = 0;
 
         VALUE current_thread = rb_thread_current();
         threads.mutex.lock();
@@ -1662,7 +1686,7 @@ class TimeCollector : public BaseCollector {
     void write_meta(VALUE meta, VALUE result) {
         BaseCollector::write_meta(meta, result);
         rb_hash_aset(meta, sym("interval"), ULL2NUM(interval.microseconds()));
-        rb_hash_aset(meta, sym("allocation_sample_rate"), ULL2NUM(allocation_sample_rate));
+        rb_hash_aset(meta, sym("allocation_interval"), ULL2NUM(allocation_interval));
 
     }
 
@@ -1860,7 +1884,7 @@ class TimeCollector : public BaseCollector {
             this->threads.initial(thread);
         }
 
-        if (allocation_sample_rate > 0) {
+        if (allocation_interval > 0) {
             tp_newobj = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_NEWOBJ, newobj_i, this);
             rb_tracepoint_enable(tp_newobj);
         }
@@ -1965,12 +1989,19 @@ collector_free(void *data) {
     delete collector;
 }
 
+static void
+collector_compact(void *data) {
+    BaseCollector *collector = static_cast<BaseCollector *>(data);
+    collector->compact();
+}
+
 static const rb_data_type_t rb_collector_type = {
     .wrap_struct_name = "vernier/collector",
     .function = {
         //.dmemsize = rb_collector_memsize,
         .dmark = collector_mark,
         .dfree = collector_free,
+        .dcompact = collector_compact,
     },
 };
 
@@ -1985,7 +2016,7 @@ collector_start(VALUE self) {
     auto *collector = get_collector(self);
 
     if (!collector->start()) {
-        rb_raise(rb_eRuntimeError, "already running");
+        rb_raise(rb_eRuntimeError, "collector already running");
     }
 
     return Qtrue;
@@ -2038,14 +2069,17 @@ static VALUE collector_new(VALUE self, VALUE mode, VALUE options) {
             interval = TimeStamp::from_microseconds(NUM2UINT(intervalv));
         }
 
-        VALUE allocation_sample_ratev = rb_hash_aref(options, sym("allocation_sample_rate"));
-        unsigned int allocation_sample_rate;
-        if (NIL_P(allocation_sample_ratev)) {
-            allocation_sample_rate = 0;
+        VALUE allocation_intervalv = rb_hash_aref(options, sym("allocation_interval"));
+        if (NIL_P(allocation_intervalv))
+            allocation_intervalv = rb_hash_aref(options, sym("allocation_sample_rate"));
+
+        unsigned int allocation_interval;
+        if (NIL_P(allocation_intervalv)) {
+            allocation_interval = 0;
         } else {
-            allocation_sample_rate = NUM2UINT(allocation_sample_ratev);
+            allocation_interval = NUM2UINT(allocation_intervalv);
         }
-        collector = new TimeCollector(stack_table, interval, allocation_sample_rate);
+        collector = new TimeCollector(stack_table, interval, allocation_interval);
     } else {
         rb_raise(rb_eArgError, "invalid mode");
     }

data/lib/vernier/autorun.rb

@@ -17,12 +17,12 @@ module Vernier
 
     def self.start
       interval = options.fetch(:interval, 500).to_i
-      allocation_sample_rate = options.fetch(:allocation_sample_rate, 0).to_i
+      allocation_interval = options.fetch(:allocation_interval, 0).to_i
       hooks = options.fetch(:hooks, "").split(",")
 
-      STDERR.puts("starting profiler with interval #{interval}")
+      STDERR.puts("starting profiler with interval #{interval} and allocation interval #{allocation_interval}")
 
-      @collector = Vernier::Collector.new(:wall, interval:, allocation_sample_rate:, hooks:)
+      @collector = Vernier::Collector.new(:wall, interval:, allocation_interval:, hooks:)
       @collector.start
     end
 

data/lib/vernier/collector.rb

@@ -32,7 +32,7 @@ module Vernier
       when :rails, :activesupport
         @hooks << Vernier::Hooks::ActiveSupport.new(self)
       else
-        warn "Unknown hook: #{hook.inspect}"
+        warn "unknown hook: #{hook.inspect}"
       end
     end
 

data/lib/vernier/middleware.rb

@@ -13,9 +13,9 @@ module Vernier
       return @app.call(env) unless permitted
 
       interval = request.GET.fetch("vernier_interval", 200).to_i
-      allocation_sample_rate = request.GET.fetch("vernier_allocation_sample_rate", 200).to_i
+      allocation_interval = request.GET.fetch("vernier_allocation_interval", 200).to_i
 
-      result = Vernier.trace(interval:, allocation_sample_rate:, hooks: [:rails]) do
+      result = Vernier.trace(interval:, allocation_interval:, hooks: [:rails]) do
         @app.call(env)
       end
       body = result.to_gecko(gzip: true)

data/lib/vernier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vernier
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/vernier.rb

@@ -40,7 +40,7 @@ module Vernier
       @collector.stop
       @collector = nil
 
-      raise "Profile already started, stopping..."
+      raise "profile already started, stopping..."
     end
 
     @collector = Vernier::Collector.new(mode, collector_options)
@@ -48,7 +48,7 @@ module Vernier
   end
 
   def self.stop_profile
-    raise "No profile started" unless @collector
+    raise "profile not started" unless @collector
 
     result = @collector.stop
     @collector = nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vernier
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - John Hawthorn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-11 00:00:00.000000000 Z
+date: 2024-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport