method_timer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68ce55408cf9543b2a34106b4dc700f6f7c5e49e12e3caa55a14502d06ec4bf4
+  data.tar.gz: 1782abd41e506211c86e0c02e6c29549354563f9a0404e7eccab10ad3b209add
+SHA512:
+  metadata.gz: 9c760f1a4ffd0788a0c88392793ad3d3879f79f58fe3da4e3f9b85ccf79f8f61e22a17e1abc716c3a166df175ecea068bea135f71ac6d22c6fb8f9452ef75cc9
+  data.tar.gz: b6f0d33089cd55d60ce0def864aebe13b3c096d4dc564612507201eb3ad76ae0fd6b8464588bcead4dd517520e678752df008a65a5a45d2178200735ea2f2a60

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konrad Jurkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,296 @@
+# MethodTimer
+
+Per-method timing for Ruby code, for profiling interactively from a console. It instruments every method under a
+class or namespace and reports, per method: self and total time, SQL time, GC time, call count and allocations.
+Wrappers are allocation-free, and the report includes an estimate of the profiler's own overhead.
+
+**This is a console tool: use it from an interactive console session, never from application code.** Running it
+in a production console against real data is fine and a common use. Don't call it from code that serves requests or
+runs jobs: instrumentation patches classes until you `uninstall`, adds a fixed cost to every
+instrumented call, keeps global state and isn't thread-safe. Profile in a throwaway console session (e.g.
+`rails console`), then exit.
+
+Requires Ruby 3.4+: the wrappers forward arguments with `(...)`, which only stopped allocating in Ruby 3.4 (on
+older versions every instrumented call would add objects to the `allocs` column). No runtime dependencies; SQL is
+tracked automatically when ActiveSupport is loaded (ActiveRecord's `sql.active_record` notifications).
+
+## Installation
+
+Add it with `require: false`, so it's installed everywhere you might open a console but never loaded when the app
+boots:
+
+```ruby
+# Gemfile
+gem 'method_timer', require: false
+```
+
+If you only profile locally, put it in the development group instead.
+
+Then load it in the console session where you want to profile:
+
+```ruby
+require 'method_timer'
+```
+
+### Loading it in every Rails console
+
+Use Rails' `console` hook in `config/application.rb`, which runs only when a console starts (not in the server,
+jobs or tests):
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+    console do
+      require 'method_timer' if Gem.loaded_specs.key?('method_timer')
+    end
+  end
+end
+```
+
+The `Gem.loaded_specs` guard keeps consoles starting in environments where the gem isn't installed (e.g. when it's
+in the development group and you open a production console).
+
+## Usage
+
+MethodTimer works with any Ruby code: plain classes and modules, Rails models and services, or classes from other
+gems. Point `install` at a class or a namespace; every instance method defined there (public, protected and
+private, plus methods of modules included directly into those classes) gets timed.
+
+### Where does the time go?
+
+```ruby
+MethodTimer.install(MyApp::Billing)              # a class or a namespace (all classes under it)
+MethodTimer.run { thing_to_profile }             # prints the report to stderr, returns the block's value
+MethodTimer.run(rss: true) { thing_to_profile }  # also samples peak process memory every second
+MethodTimer.report(threshold: 0.5)               # reprint, showing only methods with total >= 0.5s (default 0.001s)
+MethodTimer.stats                                # the numbers as a hash
+MethodTimer.uninstall                            # remove all wrappers (methods run at full speed again)
+```
+
+`install` options:
+
+- `strip_root: false`: keep the full namespace in labels (by default the namespace shared by all instrumented
+  classes is stripped).
+- `silence_sql: false`: keep the ActiveRecord logger (it's silenced by default, as logging every query distorts
+  timings).
+
+You can call `install` several times to time a few unrelated classes together. To profile a different piece of
+code in the same session, `uninstall` first, so the previous classes stop paying the per-call cost and don't show
+up in the next report. (`run` already clears the numbers from the previous run.)
+
+### Example: plain Ruby
+
+A CSV export of 50,000 orders, each with 5 items:
+
+```ruby
+require 'csv'
+require 'method_timer'
+
+module Shop
+  Order = Struct.new(:id, :customer, :items)
+  Item = Struct.new(:name, :price, :quantity)
+
+  class PriceCalculator
+    TAX = 0.23
+
+    def total(order) = order.items.sum { |item| line_total(item) }
+
+    private
+
+    def line_total(item) = (item.price * item.quantity * (1 + TAX)).round(2)
+  end
+
+  class CsvExport
+    def initialize(orders) = @orders = orders
+
+    def call
+      CSV.generate do |csv|
+        csv << %w[id customer total]
+        @orders.each { |order| csv << row(order) }
+      end
+    end
+
+    private
+
+    def row(order) = [order.id, order.customer.upcase, calculator.total(order)]
+
+    def calculator = @calculator ||= PriceCalculator.new
+  end
+end
+
+orders = Array.new(50_000) do |i|
+  Shop::Order.new(i, "customer #{i}", Array.new(5) { |n| Shop::Item.new("item #{n}", 9.99, n + 1) })
+end
+
+MethodTimer.install(Shop)
+MethodTimer.run { Shop::CsvExport.new(orders).call }
+```
+
+```
+MethodTimer: instrumented 4 classes/modules under Shop (overhead 0.77µs per call).
+
+method                      self(ruby)  self(sql)   self(gc)      total      calls  sql calls       allocs
+-----------------------------------------------------------------------------------------------------------
+PriceCalculator#line_total    0.36301s   0.00000s   0.00000s   0.42104s     250000          0           12
+PriceCalculator#total         0.21378s   0.00000s   0.00000s   0.64071s      50000          0            9
+CsvExport#row                 0.15167s   0.00000s   0.00000s   0.81289s      50000          0       150014
+CsvExport#call                0.11139s   0.00000s   0.00000s   0.92428s          1          0       250123
+Item#quantity                 0.03049s   0.00000s   0.00000s   0.03049s     250000          0            2
+Item#price                    0.02753s   0.00000s   0.00000s   0.02753s     250000          0            2
+CsvExport#calculator          0.00823s   0.00000s   0.00000s   0.00823s      50000          0            6
+Order#id                      0.00656s   0.00000s   0.00000s   0.00656s      50000          0            2
+Order#items                   0.00590s   0.00000s   0.00000s   0.00590s      50000          0            2
+Order#customer                0.00572s   0.00000s   0.00000s   0.00572s      50000          0            2
+-----------------------------------------------------------------------------------------------------------
+TOTAL (wall time of run block)                                                    0.92429s
+  of which captured (sum of self ruby)            0.92428s
+  of which SQL (sum of self sql / calls)                     0.00000s                                    0
+  of which GC (sum of self gc)                                          0.00000s
+  of which instrumentation overhead (estimated)   0.80849s  (1050002 calls x 0.77µs, counted in callers' self)
+  total allocations (sum of self allocs)                                                            400176
+```
+
+Two things to notice:
+
+- `Struct` accessors are real methods, so they're timed too. `allocs` shows where objects are created:
+  `CsvExport#row` allocates 3 per call, `PriceCalculator` almost nothing.
+- The overhead line says 0.81 s of the 0.92 s is the profiler itself: a million calls to tiny methods. When that
+  happens, instrument only the classes you care about:
+
+```ruby
+MethodTimer.install(Shop::CsvExport)
+MethodTimer.install(Shop::PriceCalculator)
+MethodTimer.run { Shop::CsvExport.new(orders).call }
+# 400,002 instrumented calls instead of 1,050,002; wall time 0.42 s instead of 0.92 s
+```
+
+### Example: a Rails model and service
+
+In `rails console`, SQL time and query counts are filled in from ActiveRecord's notifications:
+
+```ruby
+MethodTimer.install(Invoice)   # an ActiveRecord model
+MethodTimer.install(Billing)   # a namespace of service objects, e.g. Billing::MonthlyRun
+MethodTimer.run { Billing::MonthlyRun.new(month: Date.current).call }
+```
+
+`self(sql)` and `sql calls` show which method ran the queries (cached queries are skipped), so an N+1 stands out as
+a method with as many `sql calls` as `calls`. Association readers are included (Rails defines them in a named
+`GeneratedAssociationMethods` module), e.g. loading 3 records and calling `download.template` on each:
+
+```
+Download::GeneratedAssociationMethods#template      3 calls      3 sql calls
+```
+
+Attribute readers (`invoice.amount`) aren't timed: Rails defines them lazily on first use, after `install` ran.
+
+### Example: a class from another gem
+
+```ruby
+MethodTimer.install(CSV)   # CSV and everything under it (CSV::Writer, CSV::Parser, ...)
+MethodTimer.run { CSV.generate { |csv| 1_000.times { |i| csv << [i, 'x'] } } }
+# CSV::Writer#quote 2000 calls, CSV#<< 1000 calls, ...
+```
+
+### How long does it really take?
+
+`bench` times a block without instrumenting anything, so it works for any code, including top-level methods and
+lambdas that `install` can't reach. Use it to compare two versions:
+
+```ruby
+titles = Array.new(200_000) { |i| "Hello World #{i}!" }
+
+MethodTimer.bench { titles.map { |t| t.downcase.gsub(/[^a-z0-9]+/, '-').delete_suffix('-') } }
+# wall                     0.320s
+# GC                       0.085s
+# SQL                      0.000s (0 queries)
+# allocations             2600038
+
+MethodTimer.bench { titles.map { |t| t.downcase.tr('^a-z0-9', '-').squeeze('-').delete_suffix('-') } }
+# wall                     0.150s
+# GC                       0.043s
+# SQL                      0.000s (0 queries)
+# allocations             1800022
+
+MethodTimer.bench(rss: true) { thing_to_measure } # plus memory at start, peak (sampled every second) and end
+```
+
+When comparing two versions of real code, run `bench` in a fresh process without `install`.
+
+### What isn't timed
+
+- Class (singleton) methods such as `Report.build`: only instance methods are wrapped. Their time counts toward
+  the instance methods they call, or use `bench`.
+- Top-level methods, lambdas and blocks: they aren't methods of an instrumented class.
+- Methods defined after `install` (e.g. ActiveRecord attribute readers, which Rails defines on first use) and
+  methods in anonymous modules: `install` wraps the methods that exist when it runs.
+
+## Reading the report
+
+```
+method                        self(ruby)  self(sql)   self(gc)      total      calls  sql calls       allocs
+------------------------------------------------------------------------------------------------------------
+Supply#build_csv               36.52825s  21.26017s   4.77200s  86.66200s          1         27     52580175
+Supply#build_row               22.22469s   0.00000s   0.09000s  24.03738s    4865224          0      4918938
+...
+------------------------------------------------------------------------------------------------------------
+TOTAL (wall time of run block)                                             163.27384s
+  of which captured (sum of self ruby)           101.23146s
+  of which SQL (sum of self sql / calls)                    49.77568s                                    250
+  of which GC (sum of self gc)                                         12.26600s
+  of which instrumentation overhead (estimated)  31.75190s  (43720945 calls x 0.73µs, counted in callers' self)
+  total allocations (sum of self allocs)                                                           112497459
+```
+
+- **self(ruby)**: time spent in the method's own code, excluding instrumented callees, SQL and GC.
+- **self(sql)**: SQL run directly by the method (not by instrumented callees). Cached queries are skipped.
+- **self(gc)**: GC pauses that started while the method itself was running. Without this column, GC time would
+  land on whatever method happened to be on the stack.
+- **total**: wall time including everything the method called.
+- **allocs**: objects allocated directly by the method.
+- **wall time of run block** = self(ruby) + self(sql) + self(gc) summed over all methods (plus anything outside
+  instrumented methods). It **includes the profiler's overhead**.
+- **instrumentation overhead (estimated)**: every instrumented call costs a fixed amount (measured when you call
+  `install`), and that cost shows up in the callers' self(ruby). Subtract it from the wall time to estimate the
+  code's real run time. A method's `total` includes the overhead of every instrumented call beneath it, so methods
+  that make millions of calls look relatively more expensive than they are.
+
+For an exact real run time, use `bench`.
+
+## Caveats
+
+- `uninstall` removes the timing code, but each instrumented class keeps an empty prepended module until the
+  process exits (Ruby can't un-prepend). It has no per-call cost.
+- Only the thread running `run` is profiled: instrumented methods called from other threads run untimed (and
+  their SQL isn't counted). Run one profiled block at a time.
+- With `rss: true`, memory is sampled by a child `sh` process (reading `/proc/<pid>/statm` on Linux, `ps`
+  elsewhere), so sampling doesn't add allocations or GC to the profiled process.
+- Lambdas and blocks aren't methods, so their time is counted in the method that calls them.
+- The per-call overhead is about 0.4–0.7µs depending on the process. With tens of millions of calls, expect tens
+  of seconds of overhead; the report tells you how much.
+
+## Development
+
+The code is split into modules extended onto `MethodTimer`, so they share its state and the generated wrappers
+call `MethodTimer.enter`/`MethodTimer.leave` without an extra object per call:
+
+- `lib/method_timer.rb`: `run` and `bench`
+- `lib/method_timer/instrumenter.rb`: `install`, class discovery, labels, wrapper generation, overhead calibration
+- `lib/method_timer/recorder.rb`: per-method stats (`enter`/`leave`, `stats`, `reset`)
+- `lib/method_timer/reporter.rb`: report output
+- `lib/method_timer/sql.rb`: SQL tracking via ActiveSupport notifications
+- `lib/method_timer/memory.rb`: RSS sampling
+
+Each module has its own spec under `spec/method_timer/`; `spec/method_timer_spec.rb` covers `run` and `bench` end to end.
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake # both
+gem build method_timer.gemspec
+```
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/lib/method_timer/instrumenter.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  # Wraps every method of the instrumented classes (and their directly included modules) in a prepended module
+  # that calls MethodTimer.enter / MethodTimer.leave around it.
+  module Instrumenter
+    CALIBRATION_CALLS = 200_000
+
+    def install(root, silence_sql: true, strip_root: true)
+      @root = root
+      @strip_root = strip_root
+      ActiveRecord::Base.logger = nil if silence_sql && defined?(ActiveRecord::Base)
+      classes = []
+      classes << root if root.is_a?(Class)
+      each_class(root) { |k| classes << k }
+      sources = classes.flat_map { |k| [k, *own_included_modules(k)] }
+      @common_prefix = common_namespace(sources.filter_map(&:name))
+      already = @instrumented.size
+      classes.each { |k| instrument(k) }
+      calibrate
+      warn "MethodTimer: instrumented #{@instrumented.size - already} classes/modules under #{root} " \
+           '(overhead %.2fµs per call).' % (@overhead * 1e6)
+    end
+
+    # Removes every wrapper added by `install`, so instrumented methods run at full speed again and a different
+    # class or namespace can be installed from scratch. A module can't be un-prepended, but an emptied one adds
+    # no per-call cost.
+    def uninstall
+      @instrumented.each_value do |wrapper|
+        (wrapper.instance_methods(false) + wrapper.private_instance_methods(false)).each do |m|
+          wrapper.send(:remove_method, m)
+        end
+      end
+      count = @instrumented.size
+      @instrumented.clear
+      reset
+      count
+    end
+
+    # Longest `::`-delimited namespace shared by all names, always leaving at least the leaf segment.
+    def common_namespace(names)
+      return '' if names.empty?
+      parts = names.map { |n| n.split('::') }
+      min_len = parts.map(&:size).min
+      shared = (0...min_len).take_while { |i| parts.map { |p| p[i] }.uniq.size == 1 }.size
+      shared = min_len - 1 if shared >= min_len
+      parts.first.first(shared).join('::')
+    end
+
+    private
+
+    # Times an empty instrumented method against a plain one to estimate the fixed cost of each wrapper call.
+    def calibrate
+      plain = Class.new { def noop = nil }
+      timed = Class.new { def noop = nil }
+      wrapper = Module.new
+      @calibration_id ||= register('MethodTimer#calibration')
+      define_wrapper(wrapper, :noop, @calibration_id)
+      timed.prepend(wrapper)
+      @thread = Thread.current
+      @overhead = [elapsed(timed.new) - elapsed(plain.new), 0.0].max / CALIBRATION_CALLS
+    ensure
+      @thread = nil
+      @depth = 0
+      Recorder::STATS[@calibration_id] = [0.0, 0.0, 0, 0.0, 0, 0, 0] if @calibration_id
+    end
+
+    def elapsed(object)
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      CALIBRATION_CALLS.times { object.noop }
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+    end
+
+    def each_class(mod, seen = {}, &blk)
+      return if seen[mod]
+      seen[mod] = true
+      mod.constants(false).each do |c|
+        val = mod.const_get(c)
+        next unless val.is_a?(Module) && val.name&.start_with?(mod.name.to_s)
+        yield(val) if val.is_a?(Class)
+        each_class(val, seen, &blk)
+      end
+    rescue StandardError
+      nil
+    end
+
+    # Strips the namespace shared by all instrumented sources, so labels stay short yet unique
+    # (a single fixed prefix removed from already-unique names cannot collide).
+    def label_for(klass)
+      return klass.name unless @strip_root && klass.name && !@common_prefix.to_s.empty?
+      klass.name.sub(/\A#{Regexp.escape(@common_prefix)}::/, '')
+    end
+
+    def instrument(klass)
+      instrument_owner(klass)
+      own_included_modules(klass).each { |mod| instrument_owner(mod) }
+    end
+
+    # Prepend a timing wrapper into the method owner itself (class or module) so that each ancestor
+    # layer is measured independently: a method reached via `super` still records its own-owner timing.
+    def instrument_owner(source)
+      return if @instrumented[source]
+      wrapper = @instrumented[source] = Module.new
+      wrap_methods(wrapper, source, label_for(source))
+      source.prepend(wrapper)
+    end
+
+    # Modules mixed directly into klass (not inherited from its superclass, not anonymous wrappers).
+    def own_included_modules(klass)
+      inherited = klass.superclass ? klass.superclass.ancestors : []
+      (klass.ancestors - inherited).select { |a| a.instance_of?(Module) && a != klass && a.name }
+    end
+
+    def wrap_methods(wrapper, source, label)
+      privates = source.private_instance_methods(false)
+      protecteds = source.protected_instance_methods(false)
+      methods = source.instance_methods(false) + privates
+      methods.each do |m|
+        define_wrapper(wrapper, m, register("#{label}##{m}"))
+        wrapper.send(:private, m) if privates.include?(m)
+        wrapper.send(:protected, m) if protecteds.include?(m)
+      end
+    end
+
+    # `(...)` with a bare `super` forwards arguments without allocating, unlike `define_method { |*a, **k| }`.
+    def define_wrapper(wrapper, method_name, id)
+      wrapper.module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def #{method_name}(...)
+          MethodTimer.enter
+          super
+        ensure
+          MethodTimer.leave(#{id})
+        end
+      RUBY
+    rescue SyntaxError
+      wrapper.define_method(method_name) do |*a, **k, &b|
+        MethodTimer.enter
+        super(*a, **k, &b)
+      ensure
+        MethodTimer.leave(id)
+      end
+    end
+  end
+end

data/lib/method_timer/memory.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  # Process memory (RSS) sampling for `run(rss: true)` and `bench(rss: true)`.
+  module Memory
+    RSS_INTERVAL = 1 # seconds
+    # Args: $1 = PID to watch, $2 = interval in seconds. Prints the peak RSS in KB on SIGTERM. POSIX sh only
+    # (dash, busybox ash, bash, macOS sh). Linux reads VmRSS from /proc (kB, independent of page size), other
+    # systems use ps. The sleep doesn't hold stdout, so the pipe closes as soon as the script exits.
+    RSS_SAMPLER_SCRIPT = <<~SH
+      peak=0
+      trap 'echo "$peak"; exit 0' TERM
+      while kill -0 "$1" 2>/dev/null; do
+        rss=
+        if [ -r "/proc/$1/status" ]; then
+          while read -r key value _; do
+            [ "$key" = "VmRSS:" ] && rss=$value
+          done < "/proc/$1/status"
+        else
+          rss=$(ps -o rss= -p "$1" | tr -d ' ')
+        fi
+        [ -n "$rss" ] && [ "$rss" -gt "$peak" ] && peak=$rss
+        sleep "$2" > /dev/null 2>&1 &
+        wait $!
+      done
+      echo "$peak"
+    SH
+
+    private
+
+    # Samples the peak RSS from a child shell process, so sampling allocates nothing in this process and can't
+    # skew allocs or self(gc). The child keeps the maximum and prints it (in KB) once, when stopped.
+    def start_rss_sampler
+      reader, writer = IO.pipe
+      pid = Process.spawn('sh', '-c', RSS_SAMPLER_SCRIPT, 'rss_sampler', Process.pid.to_s, RSS_INTERVAL.to_s,
+                          out: writer, err: File::NULL)
+      writer.close
+      [pid, reader]
+    rescue SystemCallError
+      reader&.close
+      writer&.close
+      nil
+    end
+
+    # Stops the sampler and returns the peak RSS it saw, in bytes (nil if unavailable).
+    def stop_rss_sampler(sampler)
+      return unless sampler
+
+      pid, reader = sampler
+      Process.kill('TERM', pid)
+      peak_kb = reader.read.to_i
+      Process.wait(pid)
+      peak_kb.positive? ? peak_kb * 1024 : nil
+    rescue SystemCallError
+      nil
+    ensure
+      reader&.close
+    end
+
+    # RSS in bytes. Linux: /proc/self/statm. macOS/other: shell out to ps. Returns nil if unavailable.
+    def current_rss
+      if File.exist?('/proc/self/status')
+        File.read('/proc/self/status')[/^VmRSS:\s+(\d+)/, 1].to_i * 1024 # kB, independent of page size
+      else
+        `ps -o rss= -p #{Process.pid}`.to_i * 1024 # ps reports KB
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/method_timer/recorder.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  # Collects per-method stats during a run.
+  module Recorder
+    # Per-method stats, indexed by method id: [self_t, sql_t, gc_ms, total_t, calls, sql_calls, allocs]
+    NAMES = []
+    STATS = []
+    # Per-depth frame data; depth 0 is the code running outside instrumented methods.
+    START_T = [0.0]
+    START_A = [0]
+    START_G = [0]
+    CHILD_T = [0.0]
+    CHILD_A = [0]
+    CHILD_G = [0]
+    SQL_T = [0.0]
+    SQL_N = [0]
+
+    def reset
+      STATS.map! { [0.0, 0.0, 0, 0.0, 0, 0, 0] }
+      @depth = 0
+      @grand_total = 0.0
+    end
+
+    # { "Class#method" => { self_t:, sql_t:, gc_t:, total_t:, calls:, sql_calls:, allocs: } } for called methods
+    def stats
+      STATS.each_with_index.filter_map do |(self_t, sql_t, gc_ms, total_t, calls, sql_calls, allocs), id|
+        next if calls.zero?
+
+        [NAMES[id], { self_t:, sql_t:, gc_t: gc_ms / 1000.0, total_t:, calls:, sql_calls:, allocs: }]
+      end.to_h
+    end
+
+    # Called by every wrapper. Kept allocation-free (flat arrays, no blocks or splats) so that profiling
+    # millions of calls neither skews the allocation counts nor triggers extra GC. Frame state is global, so
+    # calls from any thread other than the one running `run` are ignored instead of corrupting it.
+    def enter
+      return unless Thread.current.equal?(@thread)
+
+      d = @depth += 1
+      CHILD_T[d] = 0.0
+      CHILD_A[d] = 0
+      CHILD_G[d] = 0
+      SQL_T[d] = 0.0
+      SQL_N[d] = 0
+      START_G[d] = GC.stat(:time)
+      START_A[d] = GC.stat(:total_allocated_objects)
+      START_T[d] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def leave(id)
+      return unless Thread.current.equal?(@thread)
+
+      d = @depth
+      total = Process.clock_gettime(Process::CLOCK_MONOTONIC) - START_T[d]
+      allocs = GC.stat(:total_allocated_objects) - START_A[d]
+      gc_ms = GC.stat(:time) - START_G[d]
+      @depth = d - 1
+      record(STATS[id], d, total, allocs, gc_ms)
+      CHILD_T[d - 1] += total
+      CHILD_A[d - 1] += allocs
+      CHILD_G[d - 1] += gc_ms
+    end
+
+    private
+
+    def record(stat, depth, total, allocs, gc_ms)
+      stat[0] += total - CHILD_T[depth]
+      stat[1] += SQL_T[depth] # SQL fired directly in this method (not in instrumented children)
+      stat[2] += gc_ms - CHILD_G[depth] # GC pauses that started directly in this method
+      stat[3] += total
+      stat[4] += 1
+      stat[5] += SQL_N[depth]
+      stat[6] += allocs - CHILD_A[depth] # objects allocated directly in this method
+    end
+
+    def record_sql(start, finish)
+      return if @depth.zero? || !Thread.current.equal?(@thread)
+
+      SQL_T[@depth] += finish - start
+      SQL_N[@depth] += 1
+    end
+
+    def register(name)
+      NAMES << name.freeze
+      STATS << [0.0, 0.0, 0, 0.0, 0, 0, 0]
+      NAMES.size - 1
+    end
+  end
+end

data/lib/method_timer/reporter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  # Prints the `run` and `bench` reports to stderr.
+  module Reporter
+    def report(threshold: 0.001)
+      all = stats
+      @name_width = [65, *all.keys.map(&:length)].max
+      warn "\n%-*s %10s %10s %10s %10s %10s %10s %12s" %
+        [@name_width, 'method', 'self(ruby)', 'self(sql)', 'self(gc)', 'total', 'calls', 'sql calls', 'allocs']
+      warn '-' * (@name_width + 79)
+      all.sort_by { |_, v| -self_ruby(v) }.each do |name, v|
+        next if v[:total_t] < threshold
+        warn '%-*s %9.5fs %9.5fs %9.5fs %9.5fs %10d %10d %12d' %
+          [@name_width, name, self_ruby(v), v[:sql_t], v[:gc_t], v[:total_t], v[:calls], v[:sql_calls], v[:allocs]]
+      end
+      warn '-' * (@name_width + 79)
+      report_totals(all.values)
+      report_rss("peak (sampled every #{Memory::RSS_INTERVAL}s)") if @rss_peak
+      warn '-' * (@name_width + 79)
+    end
+
+    private
+
+    def self_ruby(stats)
+      stats[:self_t] - stats[:sql_t] - stats[:gc_t]
+    end
+
+    def report_totals(values)
+      w = @name_width
+      calls = values.sum { |v| v[:calls] }
+      sql_t = values.sum { |v| v[:sql_t] }
+      sql_calls = values.sum { |v| v[:sql_calls] }
+      gc_t = values.sum { |v| v[:gc_t] }
+      allocs = values.sum { |v| v[:allocs] }
+      warn '%-*s %10s %10s %10s %9.5fs' % [w, 'TOTAL (wall time of run block)', '', '', '', @grand_total]
+      warn '%-*s %9.5fs' % [w, '  of which captured (sum of self ruby)', values.sum { |v| self_ruby(v) }]
+      warn '%-*s %10s %9.5fs %10s %10s %10s %10d' % [w, '  of which SQL (sum of self sql / calls)', '', sql_t,
+                                                     '', '', '', sql_calls]
+      warn '%-*s %10s %10s %9.5fs' % [w, '  of which GC (sum of self gc)', '', '', gc_t]
+      warn '%-*s %9.5fs  (%d calls x %.2fµs, counted in callers\' self)' %
+        [w, '  of which instrumentation overhead (estimated)', calls * @overhead, calls, @overhead * 1e6]
+      warn '%-*s %10s %10s %10s %10s %10s %10s %12d' % [w, '  total allocations (sum of self allocs)', '', '', '', '',
+                                                        '', '', allocs]
+    end
+
+    def report_bench((t0, gc0, alloc0), (sql_t, sql_calls), rss, sampler)
+      warn "\n%-20s %9.3fs" % ['wall', Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0]
+      warn '%-20s %9.3fs' % ['GC', (GC.stat(:time) - gc0) / 1000.0]
+      warn '%-20s %9.3fs (%d queries)' % ['SQL', sql_t, sql_calls]
+      warn '%-20s %10d' % ['allocations', GC.stat(:total_allocated_objects) - alloc0]
+      return unless rss
+
+      @rss_end = current_rss
+      @rss_peak = [@rss_start, stop_rss_sampler(sampler), @rss_end].compact.max
+      report_rss("peak (sampled every #{Memory::RSS_INTERVAL}s)")
+    end
+
+    def report_rss(peak_label = 'peak')
+      warn ''
+      warn '%-*s %10s' % [@name_width, '  RSS start', format_bytes(@rss_start)]
+      warn '%-*s %10s' % [@name_width, "  RSS #{peak_label}", format_bytes(@rss_peak)]
+      warn '%-*s %10s' % [@name_width, '  RSS end', format_bytes(@rss_end)]
+      return unless @rss_peak && @rss_start
+
+      warn '%-*s %10s' % [@name_width, '  RSS growth (peak - start)', format_bytes(@rss_peak - @rss_start)]
+    end
+
+    def format_bytes(bytes)
+      return '-' unless bytes
+      value = bytes.to_f
+      %w[B KB MB GB].each do |unit|
+        return '%.1f%s' % [value, unit] if value < 1024 || unit == 'GB'
+        value /= 1024
+      end
+    end
+  end
+end

data/lib/method_timer/sql.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  # SQL tracking through ActiveRecord's `sql.active_record` notifications; a no-op without ActiveSupport.
+  module Sql
+    private
+
+    def subscribe_sql
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.subscribe('sql.active_record') do |_, start, finish, _, payload|
+        yield(start, finish) unless payload[:cached] || payload[:name] == 'SCHEMA'
+      end
+    end
+
+    def unsubscribe_sql(subscriber)
+      ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+    end
+  end
+end

data/lib/method_timer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MethodTimer
+  VERSION = '0.1.0'
+end

data/lib/method_timer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'method_timer/version'
+require_relative 'method_timer/recorder'
+require_relative 'method_timer/instrumenter'
+require_relative 'method_timer/reporter'
+require_relative 'method_timer/sql'
+require_relative 'method_timer/memory'
+
+# Times every method under a class or namespace, reporting self/total time, SQL time, GC time, allocations and
+# call counts. See README.md for usage and how to read the report.
+#
+# The parts are modules extended onto MethodTimer, so they share its state and the generated wrappers call
+# MethodTimer.enter / MethodTimer.leave directly, without an extra object per call.
+module MethodTimer
+  extend Recorder
+  extend Instrumenter
+  extend Reporter
+  extend Sql
+  extend Memory
+
+  @depth = 0
+  @thread = nil
+  @instrumented = {}
+  @grand_total = 0.0
+  @overhead = 0.0
+  @root = nil
+  @strip_root = true
+  @common_prefix = ''
+  @name_width = 65
+
+  class << self
+    def run(rss: false)
+      reset
+      subscriber = subscribe_sql { |start, finish| record_sql(start, finish) }
+      GC.start
+      @rss_start = @rss_peak = rss ? current_rss : nil
+      sampler = start_rss_sampler if rss
+      @thread = Thread.current
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    ensure
+      @grand_total = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+      @thread = nil
+      if rss
+        @rss_end = current_rss
+        @rss_peak = [@rss_start, stop_rss_sampler(sampler), @rss_end].compact.max
+      end
+      unsubscribe_sql(subscriber)
+      report
+    end
+
+    def bench(rss: false)
+      sql = [0.0, 0] # [time, calls]
+      subscriber = subscribe_sql do |start, finish|
+        sql[0] += finish - start
+        sql[1] += 1
+      end
+      GC.start
+      @rss_start = @rss_peak = rss ? current_rss : nil
+      sampler = start_rss_sampler if rss
+      start = [Process.clock_gettime(Process::CLOCK_MONOTONIC), GC.stat(:time), GC.stat(:total_allocated_objects)]
+      yield
+    ensure
+      unsubscribe_sql(subscriber)
+      report_bench(start, sql, rss, sampler) if start
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: method_timer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Konrad Jurkowski
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Instruments every method under a class or namespace and reports self/total
+  time, SQL time, GC time, allocations and call counts, with allocation-free wrappers
+  and an estimate of its own overhead.
+email:
+- konrad@jurkowski.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/method_timer.rb
+- lib/method_timer/instrumenter.rb
+- lib/method_timer/memory.rb
+- lib/method_timer/recorder.rb
+- lib/method_timer/reporter.rb
+- lib/method_timer/sql.rb
+- lib/method_timer/version.rb
+homepage: https://github.com/msx2/method_timer
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/msx2/method_timer
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Low-overhead per-method timing for Ruby code, made for profiling from a console.
+test_files: []