ruby_method_tracer 0.3.3 → 0.5.0

data/lib/ruby_method_tracer/enhanced_tracer.rb

@@ -15,6 +15,12 @@ module RubyMethodTracer
   # - All options from SimpleTracer
   # - :track_hierarchy (Boolean): Enable call tree tracking; defaults to true
   #
+  # The call tree honours the same :threshold and :max_calls limits as the flat
+  # results, so leaving a tracer enabled cannot grow the tree without bound.
+  #
+  # The tree is the only store: `fetch_results` is derived from it rather than
+  # maintained alongside it, so a traced call is recorded once, not twice.
+  #
   # Usage:
   #   tracer = RubyMethodTracer::EnhancedTracer.new(MyClass, threshold: 0.005)
   #   tracer.trace_method(:expensive_call)
@@ -24,29 +30,11 @@ module RubyMethodTracer
 
     def initialize(target_class, **options)
       super
-      @call_tree = CallTree.new
+      @call_tree = CallTree.new(threshold: @options[:threshold], max_calls: @options[:max_calls])
       @track_hierarchy = @options.fetch(:track_hierarchy, true)
       @formatter = Formatters::TreeFormatter.new
     end
 
-    def trace_method(name)
-      method_name = name.to_sym
-      visibility = method_visibility(method_name)
-      return unless visibility
-      return unless mark_wrapped?(method_name)
-
-      aliased = alias_for(method_name)
-      @target_class.send(:alias_method, aliased, method_name)
-
-      tracer = self
-      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))
-
-      @target_class.send(visibility, method_name)
-    end
-
     # Print the call tree visualization
     #
     # @param options [Hash] Formatting options
@@ -64,6 +52,25 @@ module RubyMethodTracer
       @formatter.format(@call_tree, options)
     end
 
+    # Flat results, derived from the call tree.
+    #
+    # The tree already holds every completed call with its duration, status and
+    # error, so keeping a second parallel list would mean recording each call
+    # twice. The projection below is what makes the two views agree by
+    # construction.
+    #
+    # @return [Hash] Totals and the flat call list
+    def fetch_results
+      return super unless @track_hierarchy
+
+      snapshot = @call_tree.calls_snapshot
+      {
+        total_calls: snapshot.size,
+        total_time: snapshot.sum { |call| call[:execution_time] },
+        calls: snapshot.map { |call| flat_record(call) }
+      }
+    end
+
     # Get enhanced results including both flat list and hierarchy
     #
     # @return [Hash] Results with call tree and statistics
@@ -75,6 +82,28 @@ module RubyMethodTracer
       }
     end
 
+    # Wrapper entry point: open a call-tree entry.
+    #
+    # Public because the generated wrapper calls it with an explicit receiver,
+    # which cannot reach a private method.
+    #
+    # @param display_name [String] Name as it should appear in reports
+    def start_call(display_name)
+      @call_tree.start_call(display_name)
+    end
+
+    # Wrapper entry point: close the call-tree entry for this invocation.
+    #
+    # Nothing is stored in the flat list — `fetch_results` derives it from the
+    # tree — so a traced call is recorded once. `end_call` returns nil when the
+    # call fell below the threshold, which is what gates auto output.
+    def record_call(method_name, execution_time, status, error = nil)
+      return super unless @track_hierarchy
+
+      call = @call_tree.end_call(status, error, execution_time)
+      output_call(flat_record(call)) if call && @options[:auto_output]
+    end
+
     # Clear both simple tracer results and call tree
     def clear_results
       super
@@ -83,63 +112,43 @@ module RubyMethodTracer
 
     private
 
-    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|
-        # 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
-
-        if track_hierarchy
-          tracer.__send__(:run_with_hierarchy, method_name, method_key, call_aliased)
-        else
-          tracer.__send__(:wrap_call, method_name, key) { call_aliased.call }
-        end
-      end
+    def flat_record(call)
+      {
+        method_name: call[:method_name],
+        execution_time: call[:execution_time],
+        status: call[:status],
+        error: call[:error],
+        timestamp: call[:timestamp]
+      }
+    end
+
+    # Per-method reentrancy key so that *different* wrapped methods can nest
+    # inside each other; only self-recursion is blocked. Baked into the wrapper
+    # as a literal, so no lookup happens on the call path.
+    def wrapper_plan(method_name)
+      return super unless @track_hierarchy
+
+      Wrapper::Plan.new(
+        key: :"#{@tracer_key}_#{method_name}",
+        close: :record_call,
+        open: :start_call,
+        display_name: qualified_name(method_name)
+      )
     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
+    # 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
-    # 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,77 @@
+# 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
+      when "tree" then raise ArgumentError, "the :tree format needs a call tree; use EnhancedTracer"
+      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.
+      # It is a POSIX open(2) flag and is absent on some platforms (Windows);
+      # there the stat-based guard alone applies.
+      flags = File::WRONLY | File::CREAT | File::TRUNC
+      flags |= File::NOFOLLOW if File.const_defined?(: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/base_formatter.rb

@@ -40,8 +40,9 @@ module RubyMethodTracer
       # Abstract method to be implemented by subclasses
       #
       # @param _data [Object] Data to format
+      # @param _options [Hash] Formatter-specific options
       # @raise [NotImplementedError] Must be implemented by subclass
-      def format(_data)
+      def format(_data, _options = {})
         raise NotImplementedError, "#{self.class} must implement #format"
       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