ruby_method_tracer 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d467252ce5eedf8fe0111fe1afb3983d0d4a80ad7558940908543804e963b58
-  data.tar.gz: e650becb6eee60e5bc118cf287a8dc05cbafbcb404536f1b2ab2aba2072f88f9
+  metadata.gz: 30805a204ee568f587faac32d8436594b0b7268751c1c51d297a63a35f727a97
+  data.tar.gz: e5fc11f03078cca02c167ccff3fa306e7d1a433b31677f98193a29c506289a27
 SHA512:
-  metadata.gz: 890623622e3f183687caba11a65577d20a82f9fc0032da94f8471b2947a2a0c805df3492b686623c3384584e338d625710531b37ca35adf7a251451fb0907e9f
-  data.tar.gz: 5cac3c1469df35c933e45a525e9384a7411553059633e98762fffdc1d56afe2eca1ab73b74d12c975a1d6dc2d6a7cd87720f3619aec9beffdf38d41a67961f0c
+  metadata.gz: 06d263839600dd89c18155ddc836a08aa6d304a763d4c92bb7235c28974e1a8ed1ce83eb7db174f81b75b1d0f5d98ecb1acf84ce6b1c2f875a9ab8b3b21f7fd7
+  data.tar.gz: f441ede20bd32db451673f5643a12292e2609d6c884a89f255cded0e60ff3ee2fab170a1396d7ae86e23e6a6af77b89bf5a32aa0049394107ed050a4cd98cf8e

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-30
+
+### Fixed
+- Tracing a method that is already traced no longer aliases the wrapper onto itself and raises `SystemStackError`. The duplicate-wrap guard now checks the target class for the alias instead of only consulting the tracer's own bookkeeping, so a second `trace_methods` call, or a second tracer instance, is refused with a warning rather than crashing at call time.
+- `CallTree` now honours `:max_calls`, capping both completed calls and retained root trees. Previously only the flat results list was bounded, so an `EnhancedTracer` left enabled grew without limit — every node, parent pointer and `Time` object stayed reachable for the life of the tracer.
+- `:threshold` now applies to the call tree as well as the flat list. Calls below the threshold are dropped unless they have children worth reporting, so `print_tree`, the JSON hierarchy and the tree statistics no longer disagree with `fetch_results`.
+- `trace_method` warns instead of silently doing nothing when the named method does not exist, and returns `false`. A typo, a rename or a method defined after the `trace_methods` call previously produced empty results with no explanation.
+- `RubyMethodTracer.configure` no longer holds a `Mutex` across the caller's block, which made a nested `configure` — reachable through any helper or engine initializer — fail with `ThreadError: deadlock; recursive locking`. The lock provided no real safety, since `configuration` hands out the same mutable object without it.
+- Methods that exit via `throw` or a non-`StandardError` exception are now recorded with a new `:incomplete` status instead of vanishing from the results.
+- `Exportable#export` no longer raises `NameError` on platforms without the POSIX `O_NOFOLLOW` flag (notably Windows); the flag is applied only where `File::NOFOLLOW` is defined, and the stat-based symlink guard still applies everywhere.
+- `Formatters::BaseFormatter#format` now takes `(_data, _options = {})`, matching every subclass. The abstract contract previously described a signature no implementation used.
+- On Ruby 3.0, tracing a method that uses `...` argument forwarding raised `ArgumentError` on any keyword argument. Ruby 3.0 describes `def m(...)` as a bare rest plus a block and omits the keyword rest that 3.1+ reports, so the generated wrapper funnelled keywords into the positional array. The missing keyword rest is put back on that version only — on 3.1+ the same shape means `def m(*, &)`, which genuinely takes no keywords.
+- Tracing a method whose name is not a plain identifier — a predicate (`ready?`), bang (`save!`), setter (`val=`) or operator (`==`, `[]`, `[]=`, `<=>`, `<<`, `-@`) — now works. The saved original is aliased under a name the parser accepts, since the generated wrapper calls it directly; previously such an alias could misparse silently rather than fail loudly.
+
+### Added
+- `CallTree#calls_snapshot`, and an optional `execution_time` argument to `CallTree#end_call` so a caller that already timed the call does not pay for a second clock read.
+- `SimpleTracer#untrace_method` and `#untrace_all` restore traced methods to their original implementation and visibility.
+- `trace_class_methods` on the mixin traces class (singleton) methods, which the documented API previously could not reach. Traced singleton methods are reported as `Klass.method` rather than `#<Class:Klass>#method`.
+- Real RBS signatures for the whole public API, validated in CI and by `rake rbs`. The shipped file was previously the generated template declaring only `VERSION`.
+- `RubyMethodTracer::Wrapper`, which generates the traced replacement for a method from the original's `parameters`.
+- `RubyMethodTracer::CallTreeStatistics`, extracted from `CallTree`.
+
+### Changed
+- **Breaking:** `trace_methods` now returns the `SimpleTracer` it created instead of the array of method names, and memoizes one tracer per class. Results collected through the mixin were previously unreachable unless `auto_output: true` was set.
+- Tracing a method preserves its `Method#arity` and `Method#parameters`. The wrapper is generated from the original signature rather than being a generic `proc { |*args, **kwargs, &block| }`, so reflection-driven callers (dependency injection, serializers, argument validators, documentation tooling) still see the real signature. Two limitations remain: a block parameter is always declared, because a method may `yield` without declaring one, and anonymous parameters (`def m(*)`, `def m(...)`) keep their arity but are given generated names.
+- The alias holding the original implementation (`__ruby_method_tracer_original_<name>__`) is now private. It previously inherited the original's visibility and appeared in the public API of every instance.
+- **Per-call overhead roughly halved for `EnhancedTracer` and cut by about a third for `SimpleTracer`.** Measured on one machine with the same harness for both versions, against an untraced call at ~54ns: `SimpleTracer` 464ns → 354ns below threshold and 836ns → 665ns when recording; `EnhancedTracer` 2144ns → 1081ns below threshold and 2264ns → 1344ns when recording. Three changes account for it:
+  - The timing path is now emitted inline in the generated wrapper — the reentrancy guard, both clock reads and the `begin/rescue/ensure` all live in the method itself. It calls the tracer once per invocation instead of threading a block down through `dispatch`, `wrap_call` and `timed`, each of which cost a frame and a `Proc`.
+  - `EnhancedTracer` no longer maintains a flat call list alongside the tree. `fetch_results` is derived from the tree instead, so a traced call is recorded once rather than twice — and the two views now agree by construction.
+  - Everything knowable at trace time is baked into the wrapper as a literal (the reentrancy key, the method name, the display name) and methods whose parameters all forward unconditionally skip building an argument array, so the common case allocates nothing and does no hash lookups on the call path.
+- CI now runs the specs on Ruby 3.0 through 3.4 and head, with RuboCop and RBS validation as a separate job. The matrix previously tested only 3.3.5 even though the gemspec supports `>= 3.0.0` — and two of the last four releases fixed keyword-forwarding breakage that only shows up on specific versions.
+- `render(format: :tree)` on a `SimpleTracer` now explains that the format needs a call tree instead of reporting an unknown format.
+- The gemspec globs `lib/` and `sig/` instead of deriving its file list from `git ls-files`, and no longer ships development files. The git-based list silently omitted any file that was new and not yet staged — which is how the released 0.3.0 shipped without `EnhancedTracer` and the formatters (fixed in 0.3.1). A `gem-smoke` CI job now builds the gem, installs it and traces through it, so a missing file fails the build instead of a user's install.
+
+## [0.4.0] - 2026-06-09
+
+### Added
+- Global configuration via `RubyMethodTracer.configure { |c| ... }`, with `RubyMethodTracer.configuration` and `RubyMethodTracer.reset_configuration!`. Tracers created through the mixin now use these as defaults; explicit per-tracer options still take precedence.
+- `Formatters::JsonFormatter` — serializes flat results or a call tree to JSON. Method arguments are never captured; exceptions are reduced to class + message; backtraces are opt-in (`include_backtrace:`) and length-bounded (`backtrace_limit:`). Uses `JSON.generate` only (no `Marshal`/`eval`/`YAML`).
+- `Formatters::FlatFormatter` — renders an aggregated text table (method, calls, total, avg, errors) sorted by total time.
+- `Exportable` mixin adding `render(format:)` and `export(path, format:)` to both tracers. Supported formats: `:json`, `:flat`, and `:tree` (EnhancedTracer only).
+
+### Security
+- File export never invokes a shell and never interpolates the path into a command; it writes via `File.open` with `O_NOFOLLOW`, requires the destination directory to already exist (no recursive mkdir of attacker-influenced paths), and refuses to write through an existing symlink.
+- Export format dispatch compares on the string form to avoid interning arbitrary symbols from potentially untrusted input.
+
 ## [0.3.3] - 2026-06-08
 
 ### Changed

data/README.md

@@ -6,11 +6,15 @@
 RubyMethodTracer is a lightweight Ruby mixin for targeted method tracing. It wraps instance methods, measures wall-clock runtime, flags errors, and can stream results to your logger without pulling in a full APM agent. Use it to surface slow paths in production or gather quick instrumentation while debugging.
 
 ## Highlights
-- Wrap only the methods you care about; public, protected, and private methods are supported.
+- Wrap only the methods you care about; public, protected, and private methods are supported, along with class methods.
 - Records duration, success/error state, and timestamps with thread-safe storage.
-- **NEW: Hierarchical call tree visualization** to understand nested method calls and dependencies.
+- **Hierarchical call tree visualization** to understand nested method calls and dependencies.
+- **Signature-preserving wrappers**: a traced method keeps its `arity` and `parameters`, so reflection-driven code still sees the real signature.
+- **Reversible**: `untrace_method` puts the original implementation and visibility back.
+- JSON and flat-table formatters plus file export, alongside the tree output.
+- Global configuration via `RubyMethodTracer.configure` for process-wide defaults.
 - Configurable threshold to ignore fast calls and optional log streaming via `Logger`.
-- Zero dependencies beyond the Ruby standard library, keeping overhead minimal.
+- Zero dependencies beyond the Ruby standard library.
 
 ## Installation
 
@@ -61,7 +65,7 @@ class Worker
   end
 end
 
-Worker.trace_methods(:perform, threshold: 0.005, auto_output: true)
+tracer = Worker.trace_methods(:perform, threshold: 0.005, auto_output: true)
 
 Worker.new.perform(42)
 ```
@@ -72,11 +76,13 @@ With `auto_output: true`, each invocation prints a colorized summary:
 TRACE: Worker#perform [OK] took 6.3ms
 ```
 
-To inspect trace results programmatically, manage the tracer yourself:
+`trace_methods` returns the tracer it created, so results are available directly.
+One tracer is memoized per class: calling `trace_methods` again adds methods to
+the same tracer rather than wrapping anything twice, and options are read on the
+first call.
 
 ```ruby
-tracer = RubyMethodTracer::SimpleTracer.new(Worker, threshold: 0.002)
-tracer.trace_method(:perform)
+tracer = Worker.trace_methods(:perform, threshold: 0.002)
 
 Worker.new.perform(42)
 
@@ -91,6 +97,40 @@ pp tracer.fetch_results
 
 # Clear results when needed to free memory
 tracer.clear_results
+
+# Put the original method back when you are done
+tracer.untrace_method(:perform)
+```
+
+You can also construct a tracer directly, which is what you want when the class
+is not yours to modify:
+
+```ruby
+tracer = RubyMethodTracer::SimpleTracer.new(Worker, threshold: 0.002)
+tracer.trace_method(:perform)
+```
+
+### Tracing class methods
+
+Class (singleton) methods need `trace_class_methods`, or a tracer built on the
+singleton class. They are reported as `Klass.method`.
+
+```ruby
+class Report
+  include RubyMethodTracer
+
+  def self.generate(range)
+    # ...
+  end
+end
+
+tracer = Report.trace_class_methods(:generate, threshold: 0.0)
+Report.generate(1..10)
+
+tracer.fetch_results[:calls].first[:method_name] # => "Report.generate"
+
+# Equivalent, without the mixin:
+RubyMethodTracer::SimpleTracer.new(Report.singleton_class).trace_method(:generate)
 ```
 
 ### Example 2
@@ -214,11 +254,56 @@ Most Called Methods:
 - Color-coded output for better readability
 
 
+### Global Configuration
+
+Set process-wide defaults once at boot. Per-tracer options always override these globals.
+
+```ruby
+RubyMethodTracer.configure do |config|
+  config.threshold       = 0.005   # record calls slower than 5ms
+  config.auto_output     = false
+  config.max_calls       = 1000
+  config.logger          = Rails.logger if defined?(Rails)
+  config.track_hierarchy = true      # EnhancedTracer call-tree tracking
+end
+```
+
+`RubyMethodTracer.reset_configuration!` restores the built-in defaults (useful in tests).
+
+### Reporting & Export
+
+Both tracers can render their results to a string or write them to a file via the formatter layer.
+
+```ruby
+tracer = RubyMethodTracer::EnhancedTracer.new(OrderProcessor, threshold: 0.0)
+tracer.trace_method(:process_order)
+OrderProcessor.new.process_order(order)
+
+# Render to a string
+puts tracer.render(format: :flat)              # aggregated table
+json = tracer.render(format: :json, pretty: true)
+tree = tracer.render(format: :tree)            # EnhancedTracer only
+
+# Write to a file (returns the absolute path written)
+tracer.export("tmp/trace.json", format: :json)
+tracer.export("tmp/trace.txt",  format: :flat, colorize: false)
+```
+
+Supported formats: `:json`, `:flat`, and `:tree` (EnhancedTracer only).
+
+**JSON options**
+
+- `pretty` (Boolean, default `false`): pretty-print the JSON.
+- `include_backtrace` (Boolean, default `false`): include exception backtraces. Off by default to avoid leaking internal paths.
+- `backtrace_limit` (Integer, default `10`): maximum backtrace lines when `include_backtrace` is enabled.
+
+> Security/privacy: method **arguments are never captured**, so secrets passed as parameters are not recorded. Exceptions are reduced to class + message (backtrace is opt-in). Export never invokes a shell, requires the target directory to already exist, and refuses to write through a symlink. Call `render`/`export` when tracing is quiescent (after the traced work completes).
+
 ### Options (SimpleTracer)
 
-- `threshold` (Float, default `0.001`): minimum duration (in seconds) to record.
+- `threshold` (Float, default `0.001`): minimum duration (in seconds) to record. On `EnhancedTracer` this also filters the call tree; a call below the threshold is kept only if it has children worth reporting.
 - `auto_output` (Boolean, default `false`): emit a log line using `Logger` for each recorded call.
-- `max_calls` (Integer, default `1000`): maximum number of calls to store in memory. When exceeded, the oldest calls are automatically removed to prevent memory leaks.
+- `max_calls` (Integer, default `1000`): maximum number of calls to store in memory. When exceeded, the oldest calls are automatically removed to prevent memory leaks. On `EnhancedTracer` this bounds the call tree and the retained root trees as well.
 - `logger` (Logger, default `Logger.new($stdout)`): custom logger instance for output. Useful for directing logs to files or custom log handlers.
 
 ### Options (EnhancedTracer)
@@ -227,6 +312,15 @@ EnhancedTracer supports all SimpleTracer options plus:
 
 - `track_hierarchy` (Boolean, default `true`): enable call tree tracking. Set to `false` to use EnhancedTracer like SimpleTracer.
 
+### API Methods (SimpleTracer)
+
+- `trace_method(name)` - Wrap a method. Returns `false` and warns if the method does not exist, or if it is already traced.
+- `untrace_method(name)` - Restore the original implementation and visibility. Returns `false` if this tracer did not trace it.
+- `untrace_all` - Restore every method this tracer wrapped; returns the method names.
+- `fetch_results` - Hash with `:total_calls`, `:total_time` and `:calls`.
+- `clear_results` - Discard recorded calls.
+- `render(format:)` / `export(path, format:)` - See Reporting & Export.
+
 ### API Methods (EnhancedTracer)
 
 - `print_tree(options = {})` - Print formatted call tree to stdout
@@ -235,11 +329,41 @@ EnhancedTracer supports all SimpleTracer options plus:
 - `fetch_enhanced_results` - Get hash with `:flat_calls`, `:call_hierarchy`, and `:statistics`
 - `clear_results` - Clear both flat results and call tree
 
+## Overhead
+
+Tracing wraps each call, so it is not free. As a rough shape on a warm VM,
+`SimpleTracer` costs a handful of times what an empty method call costs, and
+`EnhancedTracer` costs a few times that again to maintain the call tree.
+
+The wrapper is generated per method and does the timing inline — one tracer call
+per invocation, no intermediate frames, no `Proc` allocation, and the reentrancy
+key and display name baked in as literals — so the floor is close to the cost of
+two clock reads plus the bookkeeping you asked for.
+
+In practice that is invisible next to a method that does real work: a database
+query, an HTTP call, a template render. That is the case this gem is built for.
+It is not something to leave enabled on a hot inner method in a tight loop; for
+whole-process profiling, reach for a sampling profiler instead. Raising
+`threshold` avoids storing a record, which is the larger half of the cost, but
+the wrapper still runs on every call — so prefer tracing fewer methods over
+tracing many with a high threshold.
+
+## Known limitations
+
+- A traced method keeps its `arity` and `parameters`, with two exceptions: a
+  block parameter is always declared (a method may `yield` without declaring
+  one, and block parameters do not affect arity), and anonymous parameters
+  (`def m(*)`, `def m(...)`) keep their arity but are given generated names.
+- Tracing changes the method on the class itself, so it affects every instance
+  and every subclass that inherits it.
+- A method can only be traced by one tracer at a time. A second attempt warns
+  and is refused rather than wrapping twice.
+
 ## Choosing Between SimpleTracer and EnhancedTracer
 
 **Use SimpleTracer when:**
 - You only need flat timing data
-- You want minimal overhead
+- You want the lower overhead of the two — roughly a third of `EnhancedTracer`'s
 - You're tracing independent methods
 
 **Use EnhancedTracer when:**

data/lib/ruby_method_tracer/call_tree.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "call_tree_statistics"
+
 module RubyMethodTracer
   # CallTree manages the hierarchical structure of method calls,
   # tracking parent-child relationships and call depths.
@@ -10,12 +12,22 @@ module RubyMethodTracer
   # Note: @calls and @root_calls are shared across threads and protected
   # by a Mutex. The call stack is stored in thread-local storage so that
   # concurrent callers each maintain their own independent call depth.
+  #
+  # Retention is bounded on both ends: calls faster than :threshold are
+  # dropped unless they have children worth keeping, and :max_calls caps how
+  # many completed calls and root trees are retained.
   class CallTree
     attr_reader :calls, :root_calls
 
-    def initialize
+    DEFAULT_MAX_CALLS = 1000
+
+    # @param threshold [Float] Minimum duration in seconds for a leaf call to be kept
+    # @param max_calls [Integer] Maximum completed calls and root trees to retain
+    def initialize(threshold: 0.0, max_calls: DEFAULT_MAX_CALLS)
+      @threshold = threshold
+      @max_calls = max_calls
       @calls = []           # All recorded calls (flat list, shared)
-      @root_calls = []      # Top-level calls (depth 0, shared)
+      @root_calls = []      # Completed top-level calls (depth 0, shared)
       @lock = Mutex.new     # Protects @calls and @root_calls
       @thread_key = :"__ruby_method_tracer_call_stack_#{object_id}" # per-instance thread-local key
     end
@@ -41,29 +53,32 @@ module RubyMethodTracer
       # Add as child to parent if we're nested
       stack.last[:children] << call_record if stack.any?
 
-      # Track root-level calls (lock required since @root_calls is shared)
-      @lock.synchronize { @root_calls << call_record } if stack.empty?
-
+      # Root calls are collected on completion rather than here, so an
+      # in-flight call is never visible to readers of the hierarchy.
       stack.push(call_record)
       call_record
     end
 
     # End tracking a method call
     #
-    # @param status [Symbol] :success or :error
+    # @param status [Symbol] :success, :error or :incomplete
     # @param error [Exception, nil] The exception if status is :error
-    # @return [Hash, nil] The completed call record
-    def end_call(status = :success, error = nil)
+    # @param execution_time [Float, nil] Duration in seconds. Callers that
+    #   already timed the call pass it in, which saves a clock read here; when
+    #   omitted it is measured from the record's start time.
+    # @return [Hash, nil] The completed call record, or nil if it was dropped
+    def end_call(status = :success, error = nil, execution_time = nil)
       stack = thread_call_stack
       return nil if stack.empty?
 
       call_record = stack.pop
       call_record[:status] = status
       call_record[:error] = error
-      call_record[:execution_time] = monotonic_time - call_record[:start_time]
+      call_record[:execution_time] = execution_time || (monotonic_time - call_record[:start_time])
 
-      @lock.synchronize { @calls << call_record }
-      call_record
+      return discard(call_record, stack.last) if discardable?(call_record)
+
+      retain(call_record)
     end
 
     # Get the current call depth for the calling thread
@@ -73,6 +88,13 @@ module RubyMethodTracer
       thread_call_stack.size
     end
 
+    # Snapshot of every retained call, flat.
+    #
+    # @return [Array<Hash>] Completed call records, oldest first
+    def calls_snapshot
+      @lock.synchronize { @calls.dup }
+    end
+
     # Get call hierarchy as nested structure
     #
     # @return [Array<Hash>] Root calls with nested children
@@ -84,21 +106,7 @@ module RubyMethodTracer
     #
     # @return [Hash] Statistics including total calls, time, slowest methods, etc.
     def statistics
-      @lock.synchronize do
-        return default_statistics if @calls.empty?
-
-        method_stats = calculate_method_stats
-
-        {
-          total_calls: @calls.size,
-          total_time: @calls.sum { |c| c[:execution_time] },
-          unique_methods: method_stats.size,
-          slowest_methods: slowest_methods(method_stats),
-          most_called_methods: most_called_methods(method_stats),
-          average_time_per_method: average_times(method_stats),
-          max_depth: @calls.map { |c| c[:depth] }.max || 0
-        }
-      end
+      CallTreeStatistics.new(calls_snapshot).to_h
     end
 
     # Clear all recorded calls and reset state
@@ -122,58 +130,42 @@ module RubyMethodTracer
 
     private
 
-    # Returns the call stack for the current thread, creating it if needed.
-    # Using a per-instance key prevents interference between multiple CallTree
-    # instances running in the same thread.
-    def thread_call_stack
-      Thread.current[@thread_key] ||= []
-    end
-
-    def monotonic_time
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    # A call is dropped only when it is too fast to be interesting and has no
+    # children — dropping a parent would orphan the descendants it recorded.
+    def discardable?(call_record)
+      call_record[:execution_time] < @threshold && call_record[:children].empty?
     end
 
-    def default_statistics
-      {
-        total_calls: 0,
-        total_time: 0.0,
-        unique_methods: 0,
-        slowest_methods: [],
-        most_called_methods: [],
-        average_time_per_method: {},
-        max_depth: 0
-      }
+    # The record is always the last child appended by this thread's stack, so
+    # detaching it is a pop rather than a scan.
+    def discard(call_record, parent)
+      parent[:children].pop if parent && parent[:children].last.equal?(call_record)
+      nil
     end
 
-    def calculate_method_stats
-      method_stats = Hash.new { |h, k| h[k] = { calls: 0, total_time: 0.0, times: [] } }
-
-      @calls.each do |call|
-        stats = method_stats[call[:method_name]]
-        stats[:calls] += 1
-        stats[:total_time] += call[:execution_time]
-        stats[:times] << call[:execution_time]
+    def retain(call_record)
+      @lock.synchronize do
+        @calls << call_record
+        @calls.shift while @calls.size > @max_calls
+        next unless call_record[:depth].zero?
+
+        # Dropping the oldest root releases its whole subtree; without this the
+        # flat cap above could not actually free anything.
+        @root_calls << call_record
+        @root_calls.shift while @root_calls.size > @max_calls
       end
-
-      method_stats
-    end
-
-    def slowest_methods(method_stats)
-      method_stats
-        .map { |name, stats| { method: name, avg_time: stats[:total_time] / stats[:calls] } }
-        .sort_by { |m| -m[:avg_time] }
-        .take(10)
+      call_record
     end
 
-    def most_called_methods(method_stats)
-      method_stats
-        .map { |name, stats| { method: name, count: stats[:calls] } }
-        .sort_by { |m| -m[:count] }
-        .take(10)
+    # Returns the call stack for the current thread, creating it if needed.
+    # Using a per-instance key prevents interference between multiple CallTree
+    # instances running in the same thread.
+    def thread_call_stack
+      Thread.current[@thread_key] ||= []
     end
 
-    def average_times(method_stats)
-      method_stats.transform_values { |stats| stats[:total_time] / stats[:calls] }
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
 end

data/lib/ruby_method_tracer/call_tree_statistics.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  # CallTreeStatistics summarises a list of completed call records.
+  #
+  # It is a pure function of the records handed to it — the caller is
+  # responsible for reading them under whatever lock protects them.
+  class CallTreeStatistics
+    TOP_N = 10
+
+    EMPTY = {
+      total_calls: 0,
+      total_time: 0.0,
+      unique_methods: 0,
+      slowest_methods: [],
+      most_called_methods: [],
+      average_time_per_method: {},
+      max_depth: 0
+    }.freeze
+
+    def initialize(calls)
+      @calls = calls
+    end
+
+    # @return [Hash] Totals, the slowest and most-called methods, and max depth
+    def to_h
+      return EMPTY.dup if @calls.empty?
+
+      stats = per_method
+
+      {
+        total_calls: @calls.size,
+        total_time: @calls.sum { |call| call[:execution_time] },
+        unique_methods: stats.size,
+        slowest_methods: slowest(stats),
+        most_called_methods: most_called(stats),
+        average_time_per_method: averages(stats),
+        max_depth: max_depth
+      }
+    end
+
+    private
+
+    def per_method
+      blank = Hash.new { |hash, key| hash[key] = { calls: 0, total_time: 0.0 } }
+      @calls.each_with_object(blank) do |call, stats|
+        entry = stats[call[:method_name]]
+        entry[:calls] += 1
+        entry[:total_time] += call[:execution_time]
+      end
+    end
+
+    def slowest(stats)
+      stats
+        .map { |name, entry| { method: name, avg_time: entry[:total_time] / entry[:calls] } }
+        .sort_by { |method| -method[:avg_time] }
+        .take(TOP_N)
+    end
+
+    def most_called(stats)
+      stats
+        .map { |name, entry| { method: name, count: entry[:calls] } }
+        .sort_by { |method| -method[:count] }
+        .take(TOP_N)
+    end
+
+    def averages(stats)
+      stats.transform_values { |entry| entry[:total_time] / entry[:calls] }
+    end
+
+    def max_depth
+      @calls.map { |call| call[:depth] }.max || 0
+    end
+  end
+end

data/lib/ruby_method_tracer/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  # Configuration holds global defaults for tracers created through the
+  # mixin API. Per-tracer options passed to `trace_methods` or to a tracer's
+  # constructor always take precedence over these globals.
+  #
+  # Configure once during application boot:
+  #
+  #   RubyMethodTracer.configure do |config|
+  #     config.threshold   = 0.005
+  #     config.max_calls   = 500
+  #     config.auto_output = true
+  #   end
+  #
+  # The object is intended to be set at boot and then read concurrently.
+  # Mutating it after threads are tracing is not recommended.
+  class Configuration
+    # Minimum duration (seconds) a call must take to be recorded.
+    attr_accessor :threshold
+    # When true, each recorded call is emitted to the logger.
+    attr_accessor :auto_output
+    # Maximum number of calls retained in memory (sliding window).
+    attr_accessor :max_calls
+    # Logger instance used for auto output. Nil means each tracer builds its own.
+    attr_accessor :logger
+    # Whether EnhancedTracer builds a hierarchical call tree.
+    attr_accessor :track_hierarchy
+
+    def initialize
+      reset!
+    end
+
+    # Restore all settings to their built-in defaults.
+    def reset!
+      @threshold = 0.001
+      @auto_output = false
+      @max_calls = 1000
+      @logger = nil
+      @track_hierarchy = true
+      self
+    end
+
+    # Snapshot of the option keys consumed by the tracers.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        threshold: @threshold,
+        auto_output: @auto_output,
+        max_calls: @max_calls,
+        logger: @logger,
+        track_hierarchy: @track_hierarchy
+      }
+    end
+  end
+end