ruby_method_tracer 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d467252ce5eedf8fe0111fe1afb3983d0d4a80ad7558940908543804e963b58
-  data.tar.gz: e650becb6eee60e5bc118cf287a8dc05cbafbcb404536f1b2ab2aba2072f88f9
+  metadata.gz: 172daf6a55bb4350983cdf15aafbe4b954f418183401ef2be69c6b68c31a575d
+  data.tar.gz: '019cd6fd2053967bff554ae244eed994c614a585b16d16f1509e57a5ec5a444e'
 SHA512:
-  metadata.gz: 890623622e3f183687caba11a65577d20a82f9fc0032da94f8471b2947a2a0c805df3492b686623c3384584e338d625710531b37ca35adf7a251451fb0907e9f
-  data.tar.gz: 5cac3c1469df35c933e45a525e9384a7411553059633e98762fffdc1d56afe2eca1ab73b74d12c975a1d6dc2d6a7cd87720f3619aec9beffdf38d41a67961f0c
+  metadata.gz: 86454302178091a987db42dc9eff6e3fd320822ec38c29b27b35c7c0e92ffc16b4f2844131716202969929df8c90f3870e5b0a403ad290df7339d4fc986d2dc9
+  data.tar.gz: 3acee9f7dd4398d23ce23d34150dd88e258b9fe09cc420f364132d1fbdea4fb6bed07cdcef7a2710b2264763fb83b7dc8365534991c3057488aa3f41e3d45440

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [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

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/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

@@ -83,6 +83,17 @@ module RubyMethodTracer
 
     private
 
+    # 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
@@ -139,7 +150,7 @@ module RubyMethodTracer
     # 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

@@ -3,6 +3,7 @@
 require "set"
 require "logger"
 require_relative "formatters/base_formatter"
+require_relative "exportable"
 
 module RubyMethodTracer
   # SimpleTracer wraps instance methods on a target class and records
@@ -20,7 +21,10 @@ module RubyMethodTracer
   #   tracer = RubyMethodTracer::SimpleTracer.new(MyClass, threshold: 0.005)
   #   tracer.trace_method(:expensive_call)
   #   results = tracer.fetch_results
+  # rubocop:disable Metrics/ClassLength
   class SimpleTracer
+    include Exportable
+
     def initialize(target_class, **options)
       @target_class = target_class
       @options = default_options.merge(options)
@@ -88,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
 
@@ -172,4 +183,5 @@ module RubyMethodTracer
       @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.3"
+  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/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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_method_tracer
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Seun Adekunle
@@ -20,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