vernier 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a5b535bebdbcc91aa853b53657893c37531e8acffe5f00df1753ca1c52e7508
-  data.tar.gz: 7aa9509fdfb009956bd2eeab6b74bc8fa832e078d9c8fce92445c82a5699ea27
+  metadata.gz: 2419244a8929351d5c81f18b90766f20d7d9e29d4909c876deb06d2a9ad39f2d
+  data.tar.gz: 94ead7ad3797a5cca2311cebc0ba0a57de369b7a6d09a07cbe4b6fad1f8826ac
 SHA512:
-  metadata.gz: 45584b395431f8135928011d03d427f42aa747dda76c4bca3bc063837571e3cc168b3fbc04cd268353e17299f47c7be3c6c486e0885488c6e7b5aba94bcb4190
-  data.tar.gz: d8df8d3a0ac7ce752cfb4c8fc0f57e0af1bf7640a3f228f52a8cd4a32211cbe21686338ca6068257d49df0a2a0206773da89d93aa673a2915c5ea5881d1f4be2
+  metadata.gz: 25551c8b2d537ca00de410e0bbd2173a2cd0452462f8c8ed5c27fd9b6592fa60f7ff1eceb01b429eba69b1989287a7244acef7448b4335b3e2ef87e731af59df
+  data.tar.gz: e510284f293ae3efd17e82c8e643b800ccbce5d84ffca04ef35fb16b5edf796672080465384cb40ea59eeacc7cc3cea57cb25e73805183956359a4e58e464f8c

data/README.md

@@ -4,9 +4,11 @@ Next-generation Ruby 3.2.1+ sampling profiler. Tracks multiple threads, GVL acti
 
 <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">
 
-## Examples
+## Demos and Examples
 
-[Livestreamed demo: Pairin' with Aaron (YouTube)](https://www.youtube.com/watch?v=9nvX3OHykGQ#t=27m43)
+[Livestreamed demo: Pairin' with Aaron (YouTube)](https://www.youtube.com/watch?v=9nvX3OHykGQ#t=27m40)
+
+[Overview at RubyKaigi 2024 (YouTube)](https://youtu.be/QSjN-H4hGsM)
 
 Sidekiq jobs from Mastodon (time, threaded)
 : https://share.firefox.dev/44jZRf3
@@ -22,7 +24,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 and a Unix-like operating system.
 
 ```ruby
 gem "vernier", "~> 1.0"
@@ -30,7 +32,7 @@ gem "vernier", "~> 1.0"
 
 ## Usage
 
-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 `vernier view` command in the CLI.
+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 compatible with), or by using the `vernier 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.
@@ -41,14 +43,14 @@ The output can be viewed in the web app at https://vernier.prof, locally using t
 
 The easiest way to record a program or script is via the CLI:
 
-```
+```sh
 $ vernier run -- ruby -e 'sleep 1'
 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
 ```
 
-```
+```sh
 $ 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>
@@ -85,13 +87,39 @@ some_other_slow_method
 Vernier.stop_profile
 ```
 
+#### Rack middleware
+
+You can also use `Vernier::Middleware` to profile a Rack application:
+
+```ruby
+# config.ru
+
+require "vernier"
+
+use Vernier::Middleware
+
+run ->(env) { [200, { "Content-Type" => "text/plain" }, ["Hello, Profiling World!"]] }
+```
+
+If you're using Rails, you can add the middleware to your `config/application.rb`:
+
+```ruby
+config.middleware.use Vernier::Middleware, permit: ->(env) { env["PATH_INFO"].start_with?("/api") }
+```
+
+You can then enable profiling and configure options with query parameters:
+
+```sh
+curl http://localhost:3000?vernier=true&vernier_interval=100&vernier_allocation_interval=10
+```
+
 ### Retained memory
 
 #### Block of code
 
 Record a flamegraph of all **retained** allocations from loading `irb`:
 
-```
+```sh
 ruby -r vernier -e 'Vernier.trace_retained(out: "irb_profile.json") { require "irb" }'
 ```
 
@@ -100,13 +128,14 @@ ruby -r vernier -e 'Vernier.trace_retained(out: "irb_profile.json") { require "i
 
 ### Options
 
-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_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.
+| 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`/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)                   |
 
 ## Development
 

data/exe/vernier

@@ -7,6 +7,15 @@ require "vernier/version"
 
 module Vernier
   module CLI
+    class Metadata < Array
+      require 'json'
+      require 'base64'
+
+      def to_s
+        Base64.encode64(to_json)
+      end
+    end
+
     def self.run(options)
       banner = <<-END
 Usage: vernier run [FLAGS] -- COMMAND
@@ -38,6 +47,11 @@ FLAGS:
         o.on('--hooks [HOOKS]', String, "enable instrumentation hooks, currently supported: rails") do |s|
           options[:hooks] = s
         end
+        o.on("--metadata KEY=VALUE", String, "Set metadata key-value pairs (can be specified multiple times)") do |kv|
+          key, value = kv.split('=')
+          options[:metadata] ||= Metadata.new
+          options[:metadata] << [key, value]
+        end
       end
     end
 

data/ext/vernier/vernier.cc

@@ -74,10 +74,12 @@ static const char *gvl_event_name(rb_event_flag_t event) {
     return "no-event";
 }
 
-// TODO: Rename FuncInfo
-struct FrameInfo {
+struct FuncInfo {
     static const char *label_cstr(VALUE frame) {
         VALUE label = rb_profile_frame_full_label(frame);
+        // Currently (2025-03-22, Ruby 3.4.2) this occurs when an iseq method
+        // entry is replaced with a refinement
+        if (NIL_P(label)) return "(nil)";
         return StringValueCStr(label);
     }
 
@@ -86,7 +88,7 @@ struct FrameInfo {
         if (NIL_P(file))
             file = rb_profile_frame_path(frame);
         if (NIL_P(file)) {
-            return "";
+            return "(nil)";
         } else {
             return StringValueCStr(file);
         }
@@ -97,7 +99,7 @@ struct FrameInfo {
         return NIL_P(first_lineno) ? 0 : FIX2INT(first_lineno);
     }
 
-    FrameInfo(VALUE frame) :
+    FuncInfo(VALUE frame) :
         label(label_cstr(frame)),
         file(file_cstr(frame)),
         first_lineno(first_lineno_int(frame)) { }
@@ -107,7 +109,7 @@ struct FrameInfo {
     int first_lineno;
 };
 
-bool operator==(const FrameInfo& lhs, const FrameInfo& rhs) noexcept {
+bool operator==(const FuncInfo& lhs, const FuncInfo& rhs) noexcept {
     return
         lhs.label == rhs.label &&
         lhs.file == rhs.file &&
@@ -263,13 +265,13 @@ struct StackTable {
 
     struct FrameWithInfo {
         Frame frame;
-        FrameInfo info;
+        FuncInfo info;
     };
 
     IndexMap<Frame> frame_map;
 
     IndexMap<VALUE> func_map;
-    std::vector<FrameInfo> func_info_list;
+    std::vector<FuncInfo> func_info_list;
 
     struct StackNode {
         std::unordered_map<Frame, int> children;
@@ -360,7 +362,7 @@ struct StackTable {
         for (int i = func_info_list.size(); i < func_map.size(); i++) {
             const auto &func = func_map[i];
             // must not hold a mutex here
-            func_info_list.push_back(FrameInfo(func));
+            func_info_list.push_back(FuncInfo(func));
         }
     }
 

data/lib/vernier/autorun.rb

@@ -1,5 +1,7 @@
 require "tempfile"
 require "vernier"
+require "base64"
+require "json"
 
 module Vernier
   module Autorun
@@ -19,10 +21,15 @@ module Vernier
       interval = options.fetch(:interval, 500).to_i
       allocation_interval = options.fetch(:allocation_interval, 0).to_i
       hooks = options.fetch(:hooks, "").split(",")
+      metadata = if options[:metadata]
+        JSON.parse(Base64.decode64(@options[:metadata])).to_h { |k, v| [k.to_sym, v] }
+      else
+        {}
+      end
 
       STDERR.puts("starting profiler with interval #{interval} and allocation interval #{allocation_interval}")
 
-      @collector = Vernier::Collector.new(:wall, interval:, allocation_interval:, hooks:)
+      @collector = Vernier::Collector.new(:wall, interval:, allocation_interval:, hooks:, metadata:)
       @collector.start
     end
 

data/lib/vernier/collector.rb

@@ -25,6 +25,8 @@ module Vernier
       @hooks.each do |hook|
         hook.enable
       end
+
+      @user_metadata = options[:metadata] || {}
     end
 
     private def add_hook(hook)
@@ -79,6 +81,7 @@ module Vernier
       result.meta[:mode] = @mode
       result.meta[:out] = @out
       result.meta[:gc] = @gc
+      result.meta[:user_metadata] = @user_metadata
 
       result.stack_table = stack_table
       @thread_names.finish

data/lib/vernier/middleware.rb

@@ -1,6 +1,6 @@
 module Vernier
   class Middleware
-    def initialize(app, permit: ->(_) { true })
+    def initialize(app, permit: ->(_env) { true })
       @app = app
       @permit = permit
     end

data/lib/vernier/output/file_listing.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "filename_filter"
+require "cgi/util"
 
 module Vernier
   module Output
@@ -23,29 +24,24 @@ module Vernier
         @profile = profile
       end
 
-      def output
-        output = +""
-
+      def samples_by_file
         thread = @profile.main_thread
         if Hash === thread
           # live profile
           stack_table = @profile._stack_table
-          weights = thread[:weights]
-          samples = thread[:samples]
           filename_filter = FilenameFilter.new
         else
           stack_table = thread.stack_table
-          weights = thread.weights
-          samples = thread.samples
           filename_filter = ->(x) { x }
         end
 
+        weights = thread[:weights]
+        samples = thread[:samples]
+
         self_samples_by_frame = Hash.new do |h, k|
           h[k] = SamplesByLocation.new
         end
 
-        total = weights.sum
-
         samples.zip(weights).each do |stack_idx, weight|
           # self time
           top_frame_index = stack_table.stack_frame_idx(stack_idx)
@@ -76,6 +72,10 @@ module Vernier
         samples_by_file.transform_keys! do |filename|
           filename_filter.call(filename)
         end
+      end
+
+      def output(template: nil)
+        output = +""
 
         relevant_files = samples_by_file.select do |k, v|
           next if k.start_with?("gem:")
@@ -83,13 +83,23 @@ module Vernier
           next if k.start_with?("<")
           v.values.map(&:total).sum > total * 0.01
         end
-        relevant_files.keys.sort.each do |filename|
+
+        if template == "html"
+          html_output(output, relevant_files)
+        else
+          relevant_files.keys.sort.each do |filename|
+            output << "="*80 << "\n"
+            output << filename << "\n"
+            output << "-"*80 << "\n"
+            format_file(output, filename, samples_by_file, total: total)
+          end
           output << "="*80 << "\n"
-          output << filename << "\n"
-          output << "-"*80 << "\n"
-          format_file(output, filename, samples_by_file, total: total)
         end
-        output << "="*80 << "\n"
+      end
+
+      def total
+        thread = @profile.main_thread
+        thread[:weights].sum
       end
 
       def format_file(output, filename, all_samples, total:)
@@ -108,6 +118,35 @@ module Vernier
           end
         end
       end
+
+      def html_output(output, relevant_files)
+        output << "<pre>"
+        output << "  SELF     FILE\n"
+        relevant_files.sort_by {|k, v| -v.values.map(&:self).sum }.each do |filename, file_contents|
+          tmpl = "<details style=\"display:inline-block;vertical-align:top;\"><summary>%s</summary>"
+          output << sprintf("% 5.1f%%   #{tmpl}\n", file_contents.values.map(&:self).sum * 100 / total.to_f, filename)
+          format_file_html(output, filename, relevant_files)
+          output << "</details>\n"
+        end
+        output << "</pre>"
+      end
+
+      def format_file_html(output, filename, relevant_files)
+        samples = relevant_files[filename]
+
+        # file_name, lines, file_wall, file_cpu, file_idle, file_sort
+        output << sprintf(" TOTAL |  SELF  | LINE SOURCE\n")
+        File.readlines(filename).each_with_index do |line, i|
+          lineno = i + 1
+          calls = samples[lineno]
+
+          if calls && calls.total > 0
+            output << sprintf("%5.1f%% | %5.1f%% | % 4i  %s", 100 * calls.total / total.to_f, 100 * calls.self / total.to_f, lineno, CGI::escapeHTML(line))
+          else
+            output << sprintf("       |        | % 4i  %s", lineno, CGI::escapeHTML(line))
+          end
+        end
+      end
     end
   end
 end

data/lib/vernier/output/firefox.rb

@@ -145,7 +145,18 @@ module Vernier
             end,
             sourceCodeIsNotOnSearchfox: true,
             initialVisibleThreads: threads.each_index.to_a,
-            initialSelectedThreads: Array(threads.find_index(&:is_start))
+            initialSelectedThreads: Array(threads.find_index(&:is_start)),
+            vernierUserMetadata: profile.meta[:user_metadata],
+            extra: [
+              label: "User-Supplied Metadata",
+              entries: profile.meta[:user_metadata].map do |k, v|
+                {
+                  label: k,
+                  format: "string",
+                  value: v
+                }
+              end
+            ]
           },
           counters: counter_data,
           libs: [],
@@ -487,17 +498,21 @@ module Vernier
         def frame_table
           funcs = @stack_table_hash[:frame_table].fetch(:func)
           lines = @stack_table_hash[:frame_table].fetch(:line)
-          size = funcs.length
+          raise unless lines.size == funcs.size
+
+          size = funcs.size
           none = [nil] * size
-          categories = @frame_categories.map(&:idx)
+          default = [0] * size
+          unidentified = [-1] * size
 
-          raise unless lines.size == funcs.size
+          categories = @frame_categories.map(&:idx)
+          subcategories = @frame_subcategories
 
           {
-            address: [-1] * size,
-            inlineDepth: [0] * size,
+            address: unidentified,
+            inlineDepth: default,
             category: categories,
-            subcategory: nil,
+            subcategory: subcategories,
             func: funcs,
             nativeSymbol: none,
             innerWindowID: none,

data/lib/vernier/stack_table_helpers.rb

@@ -90,7 +90,7 @@ module Vernier
     end
 
     class Stack < BaseType
-      def each_frame
+      def each
         return enum_for(__method__) unless block_given?
 
         stack_idx = idx
@@ -100,6 +100,17 @@ module Vernier
           stack_idx = stack_table.stack_parent_idx(stack_idx)
         end
       end
+      alias each_frame each
+
+      def [](n)
+        raise RangeError if n < 0
+        stack_idx = idx
+        while n > 0
+          stack_idx = stack_table.stack_parent_idx(stack_idx)
+          n -= 1
+        end
+        Frame.new(stack_table, stack_table.stack_frame_idx(stack_idx))
+      end
 
       def leaf_frame_idx
         stack_table.stack_frame_idx(idx)

data/lib/vernier/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vernier
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - John Hawthorn
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-12-18 00:00:00.000000000 Z
+date: 2025-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -112,7 +111,6 @@ metadata:
   homepage_uri: https://github.com/jhawthorn/vernier
   source_code_uri: https://github.com/jhawthorn/vernier
   changelog_uri: https://github.com/jhawthorn/vernier
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -127,8 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A next generation CRuby profiler
 test_files: []