ruby_method_tracer 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c68cde18a5b8ae25abfbefdee213491e5f325aa7d47308e406fac073a4311e1d
-  data.tar.gz: 44a7c4e3ee69f0c34747e1a9f6b3b69ea0cbb12732c3b25d44471163ed7620cd
+  metadata.gz: 172daf6a55bb4350983cdf15aafbe4b954f418183401ef2be69c6b68c31a575d
+  data.tar.gz: '019cd6fd2053967bff554ae244eed994c614a585b16d16f1509e57a5ec5a444e'
 SHA512:
-  metadata.gz: 3f7ba3648b90cabfc0752f40e2f3b50b0fdb261162f67ad80e2832f8df922700e8837e04c70f874e3b6e3eb201df79b827f516cd74792b63753ba70424f3dd1f
-  data.tar.gz: 3031618de6d982cc269e3b1f7220156ce67f648fcd1699c9dba10df3cd9e344d6eeb4e72550a03dcbf259fdb6caa5fae895a8c7d9718fbb9e6ba8a22f761860d
+  metadata.gz: 86454302178091a987db42dc9eff6e3fd320822ec38c29b27b35c7c0e92ffc16b4f2844131716202969929df8c90f3870e5b0a403ad290df7339d4fc986d2dc9
+  data.tar.gz: 3acee9f7dd4398d23ce23d34150dd88e258b9fe09cc420f364132d1fbdea4fb6bed07cdcef7a2710b2264763fb83b7dc8365534991c3057488aa3f41e3d45440

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [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
+- `CallTree` now stores its call stack in per-thread storage (keyed per instance) instead of a single shared `@call_stack`, so concurrent callers each track their own nesting depth. `@calls` and `@root_calls` remain shared and `Mutex`-guarded.
+- `SimpleTracer` and `EnhancedTracer` now use a per-instance reentrancy key (`__ruby_method_tracer_in_trace_<object_id>`) so separate tracer instances no longer interfere with each other's re-entry guards.
+- `EnhancedTracer` hierarchy tracking extracted into a dedicated `run_with_hierarchy` method; the call-tree entry is now always closed in an `ensure` block (even for non-`StandardError` exceptions) to prevent the per-thread call stack from becoming corrupted.
+- `SimpleTracer` now delegates `format_time` and `colorize` to a `Formatters::BaseFormatter` instance instead of duplicating the formatting logic inline.
+
+### Fixed
+- Keyword-argument forwarding in `EnhancedTracer`'s wrapper now avoids passing `**{}`, preventing `SystemStackError` on Ruby 3.4+ (mirrors the `SimpleTracer` fix from 0.3.2).
+
 ## [0.3.2] - 2025-11-22
 
 ### Fixed

data/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bundle exec rspec          # Run all tests (also generates coverage report in coverage/)
+bundle exec rubocop        # Lint
+bundle exec rake           # Run both spec and rubocop (default task)
+
+# Run a single spec file
+bundle exec rspec spec/ruby_method_tracer/simple_tracer_spec.rb
+
+# Run a specific example by description
+bundle exec rspec spec/ruby_method_tracer/simple_tracer_spec.rb -e "records call details"
+
+# Install gem locally for manual testing
+bundle exec rake install
+
+# Release: bump version in lib/ruby_method_tracer/version.rb, then:
+bundle exec rake release
+```
+
+## Commit conventions
+
+- Do NOT add a `Co-authored-by:` trailer (or any "Generated with"/agent attribution) to commit messages.
+
+## Architecture
+
+The gem provides two ways to trace methods:
+
+1. **Mixin API** — `include RubyMethodTracer` in a class, then call `trace_methods(:method_name, **opts)` at the class level. This creates a `SimpleTracer` internally and is the simplest entry point.
+
+2. **Direct tracer API** — instantiate `SimpleTracer` or `EnhancedTracer` directly for programmatic access to results.
+
+### Tracing mechanism (SimpleTracer)
+
+`SimpleTracer#trace_method` wraps a method by:
+1. Detecting visibility (public/protected/private) via `method_defined?` etc.
+2. Aliasing the original to `__ruby_method_tracer_original_<name>__`
+3. Redefining the method with a proc that times the call and delegates to the alias
+4. Restoring the original visibility
+
+The wrapper uses `Thread.current[:__ruby_method_tracer_in_trace]` as a reentrancy flag to avoid recursive double-recording. Kwargs are forwarded conditionally (`kwargs.empty?` check) to stay compatible with Ruby 3.x.
+
+Results are stored in `@calls` (an Array) guarded by a `Mutex`. The `max_calls` option enforces a sliding window by `shift`-ing the oldest entry.
+
+### EnhancedTracer
+
+Inherits from `SimpleTracer` and adds call-tree tracking via `CallTree`. It overrides `trace_method` to use a per-method reentrancy key (`__ruby_method_tracer_in_trace_<method_name>`) so that *different* wrapped methods can nest inside each other (unlike `SimpleTracer` which blocks all nesting).
+
+### CallTree
+
+Stack-based hierarchy tracker. `start_call` pushes a record (with a `parent` pointer and `children` array) onto `@call_stack`; `end_call` pops it, fills timing/status, and appends to the flat `@calls` list. Root-level calls (depth 0) are also collected in `@root_calls` for tree rendering.
+
+### Formatters
+
+`Formatters::BaseFormatter` — abstract base providing `format_time` and `colorize` (ANSI).
+
+`Formatters::TreeFormatter < BaseFormatter` — renders a `CallTree` as an ASCII tree with `└──`/`├──` connectors, then appends a statistics block (slowest methods, most-called methods).

data/README.md

@@ -8,7 +8,9 @@ RubyMethodTracer is a lightweight Ruby mixin for targeted method tracing. It wra
 ## Highlights
 - Wrap only the methods you care about; public, protected, and private methods are supported.
 - 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.
+- **NEW: JSON and flat-table formatters plus file export**, alongside the existing tree output.
+- **NEW: 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.
 
@@ -214,6 +216,51 @@ 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.

data/lib/ruby_method_tracer/call_tree.rb

@@ -4,45 +4,48 @@ module RubyMethodTracer
   # CallTree manages the hierarchical structure of method calls,
   # tracking parent-child relationships and call depths.
   #
-  # It uses a stack-based approach to manage nested calls and builds
+  # It uses a per-thread stack to manage nested calls and builds
   # a tree structure showing the complete call hierarchy.
+  #
+  # 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.
   class CallTree
     attr_reader :calls, :root_calls
 
     def initialize
-      @calls = []           # All recorded calls (flat list)
-      @call_stack = []      # Current execution stack
-      @root_calls = []      # Top-level calls (depth 0)
-      @lock = Mutex.new     # Thread safety
+      @calls = []           # All recorded calls (flat list, shared)
+      @root_calls = []      # 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
 
     # Start tracking a method call
     #
     # @param method_name [String] The name of the method being called
     # @return [Hash] The call record that was pushed to the stack
-    def start_call(method_name) # rubocop:disable Metrics/MethodLength
-      @lock.synchronize do
-        call_record = {
-          method_name: method_name,
-          start_time: monotonic_time,
-          depth: @call_stack.size,
-          parent: @call_stack.last,
-          children: [],
-          status: nil,
-          error: nil,
-          execution_time: nil,
-          timestamp: Time.now
-        }
+    def start_call(method_name)
+      stack = thread_call_stack
+
+      call_record = {
+        method_name: method_name,
+        start_time: monotonic_time,
+        depth: stack.size,
+        children: [],
+        status: nil,
+        error: nil,
+        execution_time: nil,
+        timestamp: Time.now
+      }
 
-        # Add as child to parent if we're nested
-        @call_stack.last[:children] << call_record if @call_stack.any?
+      # Add as child to parent if we're nested
+      stack.last[:children] << call_record if stack.any?
 
-        # Track root-level calls
-        @root_calls << call_record if @call_stack.empty?
+      # Track root-level calls (lock required since @root_calls is shared)
+      @lock.synchronize { @root_calls << call_record } if stack.empty?
 
-        @call_stack.push(call_record)
-        call_record
-      end
+      stack.push(call_record)
+      call_record
     end
 
     # End tracking a method call
@@ -51,24 +54,23 @@ module RubyMethodTracer
     # @param error [Exception, nil] The exception if status is :error
     # @return [Hash, nil] The completed call record
     def end_call(status = :success, error = nil)
-      @lock.synchronize do
-        return nil if @call_stack.empty?
+      stack = thread_call_stack
+      return nil if stack.empty?
 
-        call_record = @call_stack.pop
-        call_record[:status] = status
-        call_record[:error] = error
-        call_record[:execution_time] = monotonic_time - call_record[:start_time]
+      call_record = stack.pop
+      call_record[:status] = status
+      call_record[:error] = error
+      call_record[:execution_time] = monotonic_time - call_record[:start_time]
 
-        @calls << call_record
-        call_record
-      end
+      @lock.synchronize { @calls << call_record }
+      call_record
     end
 
-    # Get the current call depth
+    # Get the current call depth for the calling thread
     #
     # @return [Integer] The current nesting level
     def current_depth
-      @lock.synchronize { @call_stack.size }
+      thread_call_stack.size
     end
 
     # Get call hierarchy as nested structure
@@ -100,23 +102,33 @@ module RubyMethodTracer
     end
 
     # Clear all recorded calls and reset state
+    #
+    # Note: only the current thread's call stack is cleared; other threads
+    # that are mid-trace retain their stacks.
     def clear
       @lock.synchronize do
         @calls.clear
-        @call_stack.clear
         @root_calls.clear
       end
+      thread_call_stack.clear
     end
 
-    # Check if call stack is empty (no active calls)
+    # Check if the current thread has no active calls
     #
     # @return [Boolean]
     def empty?
-      @lock.synchronize { @call_stack.empty? }
+      thread_call_stack.empty?
     end
 
     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)
     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

data/lib/ruby_method_tracer/enhanced_tracer.rb

@@ -39,7 +39,7 @@ module RubyMethodTracer
       @target_class.send(:alias_method, aliased, method_name)
 
       tracer = self
-      key = :__ruby_method_tracer_in_trace
+      key = @tracer_key # unique per tracer instance; prevents cross-tracer interference
 
       # Build wrapper that tracks hierarchy
       @target_class.define_method(method_name, &build_enhanced_wrapper(aliased, method_name, key, tracer))
@@ -83,55 +83,74 @@ module RubyMethodTracer
 
     private
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    # Expose the call tree so JSON/flat exports include hierarchy + statistics.
+    def report_source
+      @call_tree
+    end
+
+    def build_formatter(format)
+      return Formatters::TreeFormatter.new if format.to_sym == :tree
+
+      super
+    end
+
     def build_enhanced_wrapper(aliased, method_name, key, tracer)
       track_hierarchy = tracer.instance_variable_get(:@track_hierarchy)
       # Use method-specific key to prevent only SELF-recursion, not all nested calls
       method_key = :"#{key}_#{method_name}"
 
       proc do |*args, **kwargs, &block|
-        if track_hierarchy
-          # Prevent only recursive calls to the SAME method
-          return __send__(aliased, *args, **kwargs, &block) if Thread.current[method_key]
-
-          Thread.current[method_key] = true
-          full_method_name = "#{tracer.instance_variable_get(:@target_class)}##{method_name}"
-
-          # Start tracking in call tree
-          tracer.call_tree.start_call(full_method_name)
-
-          start = tracer.__send__(:monotonic_time)
-          begin
-            result = __send__(aliased, *args, **kwargs, &block)
-            execution_time = tracer.__send__(:monotonic_time) - start
-
-            # Record in both places
-            tracer.__send__(:record_call, method_name, execution_time, :success)
-            tracer.call_tree.end_call(:success)
-
-            result
-          rescue StandardError => e
-            execution_time = tracer.__send__(:monotonic_time) - start
-
-            # Record in both places
-            tracer.__send__(:record_call, method_name, execution_time, :error, e)
-            tracer.call_tree.end_call(:error, e)
+        # Ruby 3+ compatible forwarding helper (avoids passing **{} which caused
+        # SystemStackError with Ruby 3.4+ keyword argument forwarding)
+        call_aliased = lambda do
+          kwargs.empty? ? __send__(aliased, *args, &block) : __send__(aliased, *args, **kwargs, &block)
+        end
 
-            raise
-          ensure
-            Thread.current[method_key] = false
-          end
+        if track_hierarchy
+          tracer.__send__(:run_with_hierarchy, method_name, method_key, call_aliased)
         else
-          tracer.__send__(:wrap_call, method_name, key) do
-            __send__(aliased, *args, **kwargs, &block)
-          end
+          tracer.__send__(:wrap_call, method_name, key) { call_aliased.call }
         end
       end
     end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def run_with_hierarchy(method_name, method_key, call_aliased)
+      # Prevent only recursive calls to the SAME method
+      return call_aliased.call if Thread.current[method_key]
+
+      Thread.current[method_key] = true
+      full_method_name = "#{@target_class}##{method_name}"
+
+      # Start tracking in call tree before entering the timed section
+      @call_tree.start_call(full_method_name)
+
+      start = monotonic_time
+      call_status = :success
+      call_error = nil
+
+      begin
+        result = call_aliased.call
+        execution_time = monotonic_time - start
+        record_call(method_name, execution_time, :success)
+        result
+      rescue StandardError => e
+        call_status = :error
+        call_error = e
+        execution_time = monotonic_time - start
+        record_call(method_name, execution_time, :error, e)
+        raise
+      ensure
+        Thread.current[method_key] = false
+        # Always end the call tree entry, even for non-StandardError exceptions,
+        # to prevent the per-thread call stack from becoming corrupted.
+        @call_tree.end_call(call_status, call_error)
+      end
+    end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def default_options
-      super.merge(track_hierarchy: true)
+      super.merge(track_hierarchy: RubyMethodTracer.configuration.track_hierarchy)
     end
   end
 end

data/lib/ruby_method_tracer/exportable.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  # Exportable provides render/export helpers shared by the tracers.
+  #
+  # Host classes must implement a private `#report_source` returning the data
+  # handed to formatters (a results hash or a CallTree).
+  #
+  # Security notes:
+  # - `export` never invokes a shell and never interpolates the path into a
+  #   command; it writes via `File.open` with `O_NOFOLLOW`.
+  # - The destination directory must already exist (no recursive mkdir of
+  #   attacker-influenced paths) and the tracer refuses to write through an
+  #   existing symlink, guarding against symlink-redirection.
+  #
+  # Concurrency: `render`/`export` read the tracer's in-memory buffers and are
+  # intended to be called when tracing is quiescent (e.g. after the traced work
+  # has finished). The flat results path is snapshotted under a lock; the call
+  # tree is read via its locked hierarchy/statistics accessors.
+  module Exportable
+    # Render the current results to a string.
+    #
+    # @param format [Symbol] :json, :flat (and :tree for EnhancedTracer)
+    # @return [String]
+    def render(format: :json, **opts)
+      build_formatter(format).format(report_source, opts)
+    end
+
+    # Render results and write them to a file.
+    #
+    # @param path [String] Destination file path
+    # @param format [Symbol] :json, :flat (and :tree for EnhancedTracer)
+    # @return [String] The absolute path written
+    def export(path, format: :json, **opts)
+      write_export(path, render(format: format, **opts))
+    end
+
+    private
+
+    # Compare on the string form so an unknown format never interns an
+    # arbitrary symbol (avoids unbounded symbol-table growth if a caller
+    # forwards untrusted input as the format).
+    def build_formatter(format)
+      case format.to_s
+      when "json" then Formatters::JsonFormatter.new
+      when "flat" then Formatters::FlatFormatter.new
+      else raise ArgumentError, "unknown export format: #{format.inspect}"
+      end
+    end
+
+    def write_export(path, content)
+      safe_path = validate_export_path(path)
+      # O_NOFOLLOW makes the open fail if the final component is a symlink,
+      # closing the check-then-write race left by the stat-based guard below.
+      flags = File::WRONLY | File::CREAT | File::TRUNC | File::NOFOLLOW
+      File.open(safe_path, flags) { |file| file.write(content) }
+      safe_path
+    rescue Errno::ELOOP
+      raise ArgumentError, "refusing to write through symlink: #{path}"
+    end
+
+    def validate_export_path(path)
+      raise ArgumentError, "export path must be provided" if path.nil? || path.to_s.strip.empty?
+
+      expanded = File.expand_path(path.to_s)
+      dir = File.dirname(expanded)
+      raise ArgumentError, "export directory does not exist: #{dir}" unless File.directory?(dir)
+      raise ArgumentError, "refusing to overwrite symlink: #{expanded}" if File.symlink?(expanded)
+
+      expanded
+    end
+  end
+end

data/lib/ruby_method_tracer/formatters/flat_formatter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "base_formatter"
+
+module RubyMethodTracer
+  module Formatters
+    # FlatFormatter renders trace data as a flat, aggregated text table:
+    # one row per unique method with call count, total time, average time,
+    # and error count, sorted by total time descending.
+    #
+    # Accepts either a CallTree or a flat results hash from
+    # `SimpleTracer#fetch_results`.
+    class FlatFormatter < BaseFormatter
+      HEADERS = %w[Method Calls Total Avg Errors].freeze
+
+      def format(data, options = {})
+        opts = default_options.merge(options)
+        calls = extract_calls(data)
+        return "No method calls recorded.\n" if calls.empty?
+
+        rows = build_rows(calls)
+        render(rows, opts)
+      end
+
+      private
+
+      def default_options
+        { colorize: true }
+      end
+
+      def extract_calls(data)
+        if data.respond_to?(:call_hierarchy)
+          # Read the call tree through its lock-protected accessor, then flatten
+          # the hierarchy into a single list of calls.
+          data.call_hierarchy.flat_map { |node| flatten_node(node) }
+        elsif data.is_a?(Hash)
+          data[:calls] || []
+        else
+          []
+        end
+      end
+
+      def flatten_node(node)
+        [node, *(node[:children] || []).flat_map { |child| flatten_node(child) }]
+      end
+
+      def build_rows(calls)
+        rows = aggregate(calls).map { |name, agg| build_row(name, agg) }
+        rows.sort_by { |row| -row[:total] }
+      end
+
+      def build_row(name, agg)
+        {
+          method: name,
+          calls: agg[:count],
+          total: agg[:total_time],
+          avg: agg[:total_time] / agg[:count],
+          errors: agg[:errors]
+        }
+      end
+
+      def aggregate(calls)
+        stats = Hash.new { |h, k| h[k] = { count: 0, total_time: 0.0, errors: 0 } }
+        calls.each do |call|
+          agg = stats[call[:method_name]]
+          agg[:count] += 1
+          agg[:total_time] += call[:execution_time].to_f
+          agg[:errors] += 1 if call[:status] == :error
+        end
+        stats
+      end
+
+      def render(rows, opts)
+        cell_rows = rows.map { |row| cells_for(row) }
+        widths = column_widths(cell_rows)
+        lines = [align(HEADERS, widths), separator(widths)]
+        rows.zip(cell_rows).each { |row, cells| lines << data_line(row, cells, widths, opts) }
+        "#{lines.join("\n")}\n"
+      end
+
+      # Plain (uncolored) cell strings, used for both width calc and rendering.
+      def cells_for(row)
+        [row[:method], row[:calls].to_s, format_time(row[:total]), format_time(row[:avg]), row[:errors].to_s]
+      end
+
+      def column_widths(cell_rows)
+        HEADERS.each_index.map do |i|
+          (cell_rows.map { |cells| cells[i].length } + [HEADERS[i].length]).max
+        end
+      end
+
+      def align(cells, widths)
+        cells.each_index.map { |i| pad(cells[i], widths[i], i.zero?) }.join("  ")
+      end
+
+      # Justify a plain cell, then wrap it in color so ANSI codes never affect
+      # the computed column width.
+      def data_line(row, cells, widths, opts)
+        cells.each_index.map { |i| color_cell(pad(cells[i], widths[i], i.zero?), i, row, opts) }.join("  ")
+      end
+
+      def pad(text, width, left)
+        left ? text.ljust(width) : text.rjust(width)
+      end
+
+      def color_cell(padded, index, row, opts)
+        return padded unless opts[:colorize]
+        return colorize(padded, :cyan) if index.zero?
+        return colorize(padded, :red) if index == 4 && row[:errors].positive?
+
+        padded
+      end
+
+      def separator(widths)
+        widths.map { |w| "-" * w }.join("  ")
+      end
+    end
+  end
+end

data/lib/ruby_method_tracer/formatters/json_formatter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "base_formatter"
+
+module RubyMethodTracer
+  module Formatters
+    # JsonFormatter serializes trace data to JSON.
+    #
+    # Security/privacy notes:
+    # - Serialization uses `JSON.generate` only; no `Marshal`/`eval`/`YAML` is
+    #   involved, so the output cannot be used as a deserialization gadget.
+    # - Method arguments are never captured or emitted, avoiding accidental
+    #   leakage of secrets passed as parameters.
+    # - Exceptions are reduced to their class name and message. Backtraces are
+    #   opt-in (`include_backtrace: true`) and truncated to `backtrace_limit`
+    #   lines to avoid leaking large amounts of internal path information.
+    #
+    # Accepts either a CallTree (serializes hierarchy + statistics) or a flat
+    # results hash as produced by `SimpleTracer#fetch_results`.
+    class JsonFormatter < BaseFormatter
+      def format(data, options = {})
+        opts = default_options.merge(options)
+        payload = build_payload(data, opts)
+        opts[:pretty] ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      end
+
+      private
+
+      def default_options
+        {
+          pretty: false,
+          include_backtrace: false,
+          backtrace_limit: 10
+        }
+      end
+
+      def build_payload(data, opts)
+        if data.respond_to?(:call_hierarchy) && data.respond_to?(:statistics)
+          {
+            generated_at: Time.now.utc.iso8601,
+            call_hierarchy: data.call_hierarchy.map { |node| serialize_node(node, opts) },
+            statistics: serialize_statistics(data.statistics)
+          }
+        else
+          serialize_flat(data, opts)
+        end
+      end
+
+      def serialize_flat(results, opts)
+        results = {} unless results.is_a?(Hash)
+        calls = results[:calls] || []
+        {
+          generated_at: Time.now.utc.iso8601,
+          total_calls: results[:total_calls] || calls.size,
+          total_time: results[:total_time] || 0.0,
+          calls: calls.map { |call| serialize_call(call, opts) }
+        }
+      end
+
+      def serialize_call(call, opts)
+        {
+          method_name: call[:method_name],
+          execution_time: call[:execution_time],
+          status: call[:status],
+          error: serialize_error(call[:error], opts),
+          timestamp: iso8601(call[:timestamp])
+        }
+      end
+
+      def serialize_node(node, opts)
+        {
+          method_name: node[:method_name],
+          execution_time: node[:execution_time],
+          status: node[:status],
+          depth: node[:depth],
+          error: serialize_error(node[:error], opts),
+          timestamp: iso8601(node[:timestamp]),
+          children: (node[:children] || []).map { |child| serialize_node(child, opts) }
+        }
+      end
+
+      def serialize_statistics(stats)
+        stats
+      end
+
+      # Reduce an exception to a safe, bounded representation.
+      def serialize_error(error, opts)
+        return nil unless error
+
+        result = { class: error.class.name, message: error.message.to_s }
+        if opts[:include_backtrace] && error.backtrace
+          limit = opts[:backtrace_limit].to_i
+          result[:backtrace] = limit.positive? ? error.backtrace.first(limit) : []
+        end
+        result
+      end
+
+      def iso8601(time)
+        time.respond_to?(:iso8601) ? time.iso8601(6) : time
+      end
+    end
+  end
+end

data/lib/ruby_method_tracer/simple_tracer.rb

@@ -2,6 +2,8 @@
 
 require "set"
 require "logger"
+require_relative "formatters/base_formatter"
+require_relative "exportable"
 
 module RubyMethodTracer
   # SimpleTracer wraps instance methods on a target class and records
@@ -19,7 +21,10 @@ module RubyMethodTracer
   #   tracer = RubyMethodTracer::SimpleTracer.new(MyClass, threshold: 0.005)
   #   tracer.trace_method(:expensive_call)
   #   results = tracer.fetch_results
-  class SimpleTracer # rubocop:disable Metrics/ClassLength
+  # rubocop:disable Metrics/ClassLength
+  class SimpleTracer
+    include Exportable
+
     def initialize(target_class, **options)
       @target_class = target_class
       @options = default_options.merge(options)
@@ -27,6 +32,9 @@ module RubyMethodTracer
       @lock  = Mutex.new # Mutex to make writes to @calls thread safe.
       @wrapped_methods = Set.new
       @logger = @options[:logger] || Logger.new($stdout)
+      # Unique per instance so separate tracers don't interfere with each other.
+      @tracer_key = :"__ruby_method_tracer_in_trace_#{object_id}"
+      @formatter = Formatters::BaseFormatter.new
     end
 
     def trace_method(name)
@@ -39,7 +47,7 @@ module RubyMethodTracer
       @target_class.send(:alias_method, aliased, method_name) # Aliases original implementation to our private name.
 
       tracer = self
-      key = :__ruby_method_tracer_in_trace # local key to avoid recursive tracing.
+      key = @tracer_key # unique per tracer instance; prevents cross-tracer interference
 
       # Defines a new method with the original name that delegates to our wrapper.
       @target_class.define_method(method_name, &build_wrapper(aliased, method_name, key, tracer))
@@ -84,12 +92,19 @@ module RubyMethodTracer
 
     private
 
+    # Data passed to formatters by Exportable. Overridden by EnhancedTracer to
+    # expose the call tree.
+    def report_source
+      fetch_results
+    end
+
     def default_options
+      config = RubyMethodTracer.configuration
       {
-        threshold: 0.001,
-        auto_output: false,
-        max_calls: 1000,
-        logger: nil
+        threshold: config.threshold,
+        auto_output: config.auto_output,
+        max_calls: config.max_calls,
+        logger: config.logger
       }
     end
 
@@ -161,27 +176,12 @@ module RubyMethodTracer
     end
 
     def format_time(seconds)
-      if seconds >= 1.0
-        "#{seconds.round(3)}s"
-      elsif seconds >= 0.001
-        "#{(seconds * 1000).round(1)}ms"
-      else
-        "#{(seconds * 1_000_000).round(0)}µs"
-      end
+      @formatter.format_time(seconds)
     end
 
     def colorize(text, color)
-      colors = {
-        red: "31",
-        green: "32",
-        yellow: "33",
-        blue: "34",
-        magenta: "35",
-        cyan: "36",
-        white: "37",
-        reset: "0"
-      }
-      "\e[#{colors[color]}m#{text}\e[#{colors[:reset]}m"
+      @formatter.colorize(text, color)
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/ruby_method_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyMethodTracer
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/ruby_method_tracer.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "ruby_method_tracer/version"
+require_relative "ruby_method_tracer/configuration"
+require_relative "ruby_method_tracer/formatters/base_formatter"
 require_relative "ruby_method_tracer/simple_tracer"
 require_relative "ruby_method_tracer/call_tree"
 require_relative "ruby_method_tracer/enhanced_tracer"
-require_relative "ruby_method_tracer/formatters/base_formatter"
 require_relative "ruby_method_tracer/formatters/tree_formatter"
+require_relative "ruby_method_tracer/formatters/json_formatter"
+require_relative "ruby_method_tracer/formatters/flat_formatter"
 
 # Public: Mixin that adds lightweight method tracing to classes.
 #
@@ -26,6 +29,39 @@ require_relative "ruby_method_tracer/formatters/tree_formatter"
 module RubyMethodTracer
   class Error < StandardError; end
 
+  @configuration = Configuration.new
+  @configuration_mutex = Mutex.new
+
+  class << self
+    # Global configuration shared as defaults by tracers created via the mixin.
+    #
+    # @return [RubyMethodTracer::Configuration]
+    attr_reader :configuration
+
+    # Yield the global configuration for mutation. Intended to be called once
+    # at application boot.
+    #
+    #   RubyMethodTracer.configure do |config|
+    #     config.threshold = 0.005
+    #   end
+    #
+    # @yieldparam config [RubyMethodTracer::Configuration]
+    # @return [RubyMethodTracer::Configuration]
+    def configure
+      @configuration_mutex.synchronize do
+        yield(@configuration) if block_given?
+      end
+      @configuration
+    end
+
+    # Reset the global configuration back to built-in defaults.
+    #
+    # @return [RubyMethodTracer::Configuration]
+    def reset_configuration!
+      @configuration_mutex.synchronize { @configuration.reset! }
+    end
+  end
+
   def self.included(base)
     base.extend(ClassMethods)
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_method_tracer
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Seun Adekunle
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A developer-friendly gem for tracing method calls, execution times, with
   minimal overhead.
@@ -21,14 +20,19 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/ruby_method_tracer.rb
 - lib/ruby_method_tracer/call_tree.rb
+- lib/ruby_method_tracer/configuration.rb
 - lib/ruby_method_tracer/enhanced_tracer.rb
+- lib/ruby_method_tracer/exportable.rb
 - lib/ruby_method_tracer/formatters/base_formatter.rb
+- lib/ruby_method_tracer/formatters/flat_formatter.rb
+- lib/ruby_method_tracer/formatters/json_formatter.rb
 - lib/ruby_method_tracer/formatters/tree_formatter.rb
 - lib/ruby_method_tracer/simple_tracer.rb
 - lib/ruby_method_tracer/version.rb
@@ -42,7 +46,6 @@ metadata:
   source_code_uri: https://github.com/Seunadex/ruby_method_tracer
   changelog_uri: https://github.com/Seunadex/ruby_method_tracer/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -57,8 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Lightweight method tracing for Ruby applications
 test_files: []