method_timer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68ce55408cf9543b2a34106b4dc700f6f7c5e49e12e3caa55a14502d06ec4bf4
-  data.tar.gz: 1782abd41e506211c86e0c02e6c29549354563f9a0404e7eccab10ad3b209add
+  metadata.gz: 4b6c0f87fb633ecd9cd510739a6c7fa7a1ae25ed4ec5c58b9f7f6a12ff4e8b6a
+  data.tar.gz: 4d06cfd6f2aeb071d995c992d39964221f8a0d8bf693bfd54431d5fd68a3d3e3
 SHA512:
-  metadata.gz: 9c760f1a4ffd0788a0c88392793ad3d3879f79f58fe3da4e3f9b85ccf79f8f61e22a17e1abc716c3a166df175ecea068bea135f71ac6d22c6fb8f9452ef75cc9
-  data.tar.gz: b6f0d33089cd55d60ce0def864aebe13b3c096d4dc564612507201eb3ad76ae0fd6b8464588bcead4dd517520e678752df008a65a5a45d2178200735ea2f2a60
+  metadata.gz: '039f1b71e315e945067d16ee974c26aba84541fa1c435282b53aee2535bfaacbdb7bfaed50c1ed72ef63b87749b1ac151fac6adae2277842732ccfafdeb940fb'
+  data.tar.gz: ba1a9caba01065d9a16750531bec324b0f0ebbac2c7abc8e8ef4c6c50d8381ff9c24d639a3c01745228567f02bf8a1c1d1943b984cd2adc09a82b010a883895b

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.2.0 - November 14, 2026
+
+### Added
+
+- Select instrumented methods with `install(..., only: [:call])`
+- Profile class and module methods with `singleton: true`, including `extend`, `extend self`,
+  `module_function`, and inherited implementations when their owners are installed
+- Sort reports by timing, call counts or allocations, and limit displayed rows without reducing totals
+- Choose `MethodTimer.format = :hash` for on-demand reports with method metrics, totals and optional RSS data
+- Add detailed examples and an API reference, included in the gem package
+
+### Fixed
+
+- Remove constructor instrumentation silently on uninstall without changing the console's warning settings
+- Preserve results for classes with overlapping short names across multiple installs
+- Measure SQL with a monotonic clock and avoid counting GC twice with ActiveSupport 7.2+
+- Exclude report output and cleanup from benchmark timing, GC and allocation measurements;
+  finish RSS sampling before printing
+- Ignore SQL from other threads during benchmarking
+- Restore the original ActiveRecord logger on uninstall without overwriting a replacement logger
+
+### Changed
+
+- Keep one snapshot of the last run or benchmark; previously returned hashes remain independent
+- Re-render saved measurements without collecting new data, keeping their labels and overhead calibration
+- Clear saved measurements on reset or uninstall while preserving the configured report format
+- Reorganize the README around a minimal Ruby example, retaining Rails console installation instructions
+
+## 0.1.0 - October 17, 2026
+
+- Initial release with per-method profiling, SQL and GC timing, call counts and allocations
+- Add block benchmarking, optional RSS memory sampling and instrumentation overhead estimates
+- Require Ruby 3.4+

data/README.md

@@ -1,43 +1,39 @@
 # 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.
+Find out where your Ruby code spends time and allocates objects, one method at a time.
+MethodTimer reports self and total time, SQL time, GC time, calls and allocations, with
+allocation-free wrappers and an estimate of its 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.
+**For interactive consoles, not application code.** A production console is a valid place
+to profile, but never call MethodTimer from request handlers or jobs. It patches classes
+and keeps global, non-thread-safe state. Use a throwaway console session, 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).
+Requires **Ruby 3.4+**. No runtime dependencies. SQL is tracked automatically when
+ActiveSupport notifications are loaded.
 
 ## Installation
 
-Add it with `require: false`, so it's installed everywhere you might open a console but never loaded when the app
-boots:
+Add the gem with `require: false`, so it is available in consoles without loading at app boot:
 
 ```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:
+If you only profile locally, put it in the development group instead. Run `bundle install`,
+then load the gem in your console:
 
 ```ruby
 require 'method_timer'
 ```
 
-### Loading it in every Rails console
+### Load automatically in Rails consoles
 
-Use Rails' `console` hook in `config/application.rb`, which runs only when a console starts (not in the server,
-jobs or tests):
+Keep this in `config/application.rb`. Rails runs the `console` hook only when a console
+starts, not in the server, jobs or tests:
 
 ```ruby
+# config/application.rb
 module MyApp
   class Application < Rails::Application
     console do
@@ -47,250 +43,150 @@ module MyApp
 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.)
+The guard lets consoles start when the gem is not installed in that environment.
+For a walkthrough using application models and SQL, see the [Rails console example](docs/examples/rails-console.md).
 
-### Example: plain Ruby
+## A complete, ordinary Ruby example
 
-A CSV export of 50,000 orders, each with 5 items:
+No options, Rails or extra dependencies are needed. Paste this into a fresh Ruby console:
 
 ```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)
+class NameFormatter
+  def call(names)
+    names.map { |name| normalize(name) }
   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)]
+  private
 
-    def calculator = @calculator ||= PriceCalculator.new
+  def normalize(name)
+    name.strip.downcase.gsub(/\s+/, '-')
   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
+names = Array.new(10_000) { |i| " Product #{i} " }
 
-MethodTimer.install(Shop)
-MethodTimer.run { Shop::CsvExport.new(orders).call }
-```
+MethodTimer.install(NameFormatter)
+slugs = MethodTimer.run { NameFormatter.new.call(names) }
+MethodTimer.uninstall
 
+slugs.first # => "product-0"
 ```
-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
-```
+`install` wraps existing instance methods, including private helpers. `run` prints the
+report to stderr and returns the block's value. `uninstall` removes the wrappers and clears
+the measurements.
 
-### Example: a Rails model and service
+Complete stderr output captured on Ruby 4.0.9 (arm64 macOS). Timings, allocations and
+row order can vary between runs; the table and footer below are not reformatted:
 
-In `rails console`, SQL time and query counts are filled in from ActiveRecord's notifications:
+```text
+MethodTimer: instrumented 1 classes/modules under NameFormatter (overhead 0.61µs per call).
 
-```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 }
+method                                                            self(ruby)  self(sql)   self(gc)      total      calls  sql calls       allocs
+------------------------------------------------------------------------------------------------------------------------------------------------
+NameFormatter#call                                                  0.00655s   0.00000s   0.00000s   0.01182s          1          0            7
+NameFormatter#normalize                                             0.00378s   0.00000s   0.00150s   0.00527s      10000          0        80003
+------------------------------------------------------------------------------------------------------------------------------------------------
+TOTAL (wall time of run block)                                                                       0.01183s
+  of which captured (sum of self ruby)                              0.01033s
+  of which SQL (sum of self sql / calls)                                       0.00000s                                           0
+  of which GC (sum of self gc)                                                            0.00150s
+  of which instrumentation overhead (estimated)                     0.00607s  (10001 calls x 0.61µs, counted in callers' self)
+  total allocations (sum of self allocs)                                                                                                   80010
+------------------------------------------------------------------------------------------------------------------------------------------------
 ```
 
-`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:
+Here, `normalize` creates most of the objects. `call` includes all helper calls in its
+**total**, but not in its **self** time. The overhead estimate matters: timing 10,000 tiny
+methods can cost more than their useful work.
 
-```
-Download::GeneratedAssociationMethods#template      3 calls      3 sql calls
-```
+For a larger workload and ways to reduce that cost, see the [CSV export walkthrough](docs/examples/plain-ruby.md).
 
-Attribute readers (`invoice.amount`) aren't timed: Rails defines them lazily on first use, after `install` ran.
+## When you need more control
 
-### Example: a class from another gem
+Select fewer methods, collect data instead of printing, and sort the saved report:
 
 ```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, ...
-```
+MethodTimer.format = :hash
+MethodTimer.install(NameFormatter, only: [:call])
+MethodTimer.run { NameFormatter.new.call(names) }
 
-### How long does it really take?
+data = MethodTimer.report(sort: :allocs, limit: 10, threshold: 0)
+# data contains :methods, :totals and :rss
 
-`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:
+MethodTimer.uninstall
+MethodTimer.format = :table
+```
 
-```ruby
-titles = Array.new(200_000) { |i| "Hello World #{i}!" }
+- `only:` reduces instrumentation overhead, not just the number of displayed rows.
+- `singleton: true` also profiles class and module methods, including `extend`.
+- `report` sorts by self Ruby time by default. Its limit and threshold never change totals.
+- `format = :hash` suppresses automatic reports; `.report` returns data on demand.
+  Only the last measurement is kept. Previously returned hashes stay independent.
+- `run(rss: true)` and `bench(rss: true)` also sample process memory.
+
+All options, defaults and hash fields are in the [API reference](docs/reference.md).
 
-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
+### Measure a block without method instrumentation
 
-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
+Use `bench` in a fresh console without `install`, for example to compare implementations:
 
-MethodTimer.bench(rss: true) { thing_to_measure } # plus memory at start, peak (sampled every second) and end
+```ruby
+MethodTimer.bench { names.map { |name| name.strip.downcase } }
 ```
 
-When comparing two versions of real code, run `bench` in a fresh process without `install`.
+It reports wall time, GC, SQL and allocations, and still returns the block's value.
+See [benchmarking and memory](docs/examples/benchmarking.md) for a complete comparison.
 
-### What isn't timed
+## Reading the columns
 
-- 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.
+| Column | Meaning |
+| --- | --- |
+| `self(ruby)` | Own code, excluding instrumented callees, SQL and GC. |
+| `self(sql)` | SQL run directly here, excluding instrumented callees. |
+| `self(gc)` | GC time attributed directly here, excluding instrumented callees. |
+| `total` | Wall time including callees; do not sum this column across methods. |
+| `calls` / `sql calls` | Method calls / uncached, non-schema SQL events. |
+| `allocs` | Objects allocated directly here, excluding instrumented callees. |
 
-## Reading the report
+The run's wall time includes code outside instrumented methods and the profiler's overhead.
+With ActiveSupport 7.2+, GC during SQL is counted only as GC; older versions cannot separate
+that overlap. See [measurement semantics](docs/reference.md#measurement-semantics).
 
-```
-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
-```
+## Examples and reference
 
-- **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.
+- [Plain Ruby: CSV export, allocations and overhead](docs/examples/plain-ruby.md)
+- [Rails console: finding an N+1](docs/examples/rails-console.md)
+- [Class methods, modules, `include`, `extend` and inheritance](docs/examples/class-and-module-methods.md)
+- [Sorting, hashes and the last measurement](docs/examples/reports-as-data.md)
+- [Benchmarking implementations and sampling memory](docs/examples/benchmarking.md)
+- [Historical report from a real export](docs/examples/real-world-export.md)
+- [Full API and limitations](docs/reference.md)
+- [Release notes](CHANGELOG.md)
 
-## 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:
+## Important limits
 
-- `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
+- Run one measurement at a time. Only the measuring thread's methods and SQL are recorded;
+  GC, allocation and RSS counters are process-wide.
+- Installation wraps methods that already exist. Later definitions and anonymous modules
+  are not discovered. Inherited implementations need their defining owners installed too.
+- To change an installed owner's method selection, call `uninstall` first.
+- Uninstall leaves empty prepended modules in place because Ruby cannot un-prepend.
+- The block executes normally: profiling does not sandbox or undo its side effects.
 
-Each module has its own spec under `spec/method_timer/`; `spec/method_timer_spec.rb` covers `run` and `bench` end to end.
+## Development
 
 ```sh
 bundle install
 bundle exec rspec
 bundle exec rubocop
-bundle exec rake # both
 gem build method_timer.gemspec
 ```
 
+See the [internal layout](docs/reference.md#development) before changing collection or reporting.
+
 ## License
 
 MIT, see [LICENSE.txt](LICENSE.txt).

data/docs/examples/benchmarking.md

@@ -0,0 +1,95 @@
+# Comparing implementations and sampling memory
+
+[README](../../README.md) · [Benchmark reference](../reference.md#bench)
+
+`bench` reports the block's wall time, GC, SQL and allocations without enabling per-method
+recording. Use a fresh process without `install` so inactive wrappers do not add overhead.
+
+## Compare the same workload
+
+This standalone example creates its inputs before measurement and checks a few outputs
+before comparing the two implementations:
+
+```ruby
+require 'method_timer'
+
+titles = Array.new(200_000) { |i| "Hello World #{i}!" }
+regexp_slug = ->(title) { title.downcase.gsub(/[^a-z0-9]+/, '-').delete_suffix('-') }
+tr_slug = ->(title) { title.downcase.tr('^a-z0-9', '-').squeeze('-').delete_suffix('-') }
+
+sample = titles.first(5)
+raise 'Implementations disagree' unless sample.map(&regexp_slug) == sample.map(&tr_slug)
+
+MethodTimer.bench { titles.map(&regexp_slug) }
+MethodTimer.bench { titles.map(&tr_slug) }
+```
+
+Complete stderr captured on Ruby 4.0.9 (arm64 macOS), in the same process and order as above.
+The first report is the regexp implementation; the second is the `tr` implementation:
+
+```text
+wall                     0.204s
+GC                       0.034s
+SQL                      0.000s (0 queries)
+allocations             1600006
+
+wall                     0.102s
+GC                       0.023s
+SQL                      0.000s (0 queries)
+allocations             1800002
+```
+
+These are individual measurements, not a general speed claim. Compare `wall` for elapsed time,
+`GC` for time spent collecting, and `allocations` for object creation. Lower allocation
+counts can explain a wall-time improvement, but do not measure retained memory.
+
+`bench` forces GC before timing; work and GC inside the block are included. Cleanup and
+report rendering are excluded. Its return value is the original block value.
+Inputs, warmup, cache state, retained results and execution order can all affect a comparison;
+for stronger conclusions, repeat in fresh processes with equivalent setup.
+
+## Sample process memory
+
+```ruby
+memory_result = MethodTimer.bench(rss: true) do
+  strings = Array.new(100_000) { 'x' * 100 }
+  sleep(1.1)
+  strings.length
+end
+```
+
+`memory_result` is `100_000`. The pause deliberately keeps the strings alive through a
+sampling interval; it is part of this block's wall time, not a way to benchmark string creation.
+Complete stderr from the same Ruby 4.0.9 session:
+
+```text
+wall                     1.115s
+GC                       0.000s
+SQL                      0.000s (0 queries)
+allocations              200006
+
+  RSS start                                                           66.9MB
+  RSS peak (sampled every 1s)                                         67.6MB
+  RSS end                                                             67.6MB
+  RSS growth (peak - start)                                          784.0KB
+```
+
+The low growth here follows earlier allocation-heavy benchmarks in the same process:
+the Ruby heap already had memory available. This is not a retained-size estimate for the strings.
+
+The child process samples every second. A short-lived spike can be missed, and RSS includes
+the entire process, not just Ruby objects. Start and end samples are included in the peak.
+Sampling itself does not allocate in the measured Ruby process.
+
+To collect these readings without printing, choose `MethodTimer.format = :hash` before the
+benchmark and then call `.report`; `report[:rss]` contains byte counts. See
+[reports as data](reports-as-data.md).
+
+## Avoid misleading results
+
+- Do not compare an instrumented `run` directly with an uninstrumented `bench` as a code optimization.
+- Do not put fixture creation in just one candidate's measured block.
+- Both candidates execute normally; repeating a benchmark can repeat writes or external calls.
+- SQL is optional and counts only events from the measuring thread; query caching can change counts.
+- GC, allocations and RSS are process-wide, so background activity can contaminate results.
+- Run one measurement at a time. Each replaces the saved report, so capture hashes if you need both results.