ruby_method_tracer 0.3.3 → 0.5.0

data/lib/ruby_method_tracer/simple_tracer.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require "set"
 require "logger"
 require_relative "formatters/base_formatter"
+require_relative "exportable"
+require_relative "wrapper"
 
 module RubyMethodTracer
   # SimpleTracer wraps instance methods on a target class and records
@@ -20,42 +21,83 @@ module RubyMethodTracer
   #   tracer = RubyMethodTracer::SimpleTracer.new(MyClass, threshold: 0.005)
   #   tracer.trace_method(:expensive_call)
   #   results = tracer.fetch_results
+  #
+  # To trace class (singleton) methods, pass the singleton class:
+  #   RubyMethodTracer::SimpleTracer.new(MyClass.singleton_class)
+  # rubocop:disable Metrics/ClassLength
   class SimpleTracer
+    include Exportable
+
+    # Method names the parser accepts as a bare identifier in a call.
+    PLAIN_IDENTIFIER = /\A[a-z_][A-Za-z0-9_]*\z/
+    private_constant :PLAIN_IDENTIFIER
+
     def initialize(target_class, **options)
       @target_class = target_class
       @options = default_options.merge(options)
       @calls = []
       @lock  = Mutex.new # Mutex to make writes to @calls thread safe.
-      @wrapped_methods = Set.new
+      @wrapped_methods = {} # method name => visibility it had before wrapping
+      @qualified_names = {} # method name => display name, precomputed
       @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}"
+      @accessor = :"__ruby_method_tracer_#{object_id}__"
       @formatter = Formatters::BaseFormatter.new
     end
 
+    # Wrap a method so its calls are recorded.
+    #
+    # @param name [Symbol, String] Method to trace
+    # @return [Boolean] true if the method was wrapped by this call
     def trace_method(name)
       method_name = name.to_sym
       visibility = method_visibility(method_name)
-      return unless visibility
-      return unless mark_wrapped?(method_name)
+      unless visibility
+        warn_missing(method_name)
+        return false
+      end
+      return false if already_traced?(method_name)
 
-      aliased = alias_for(method_name)
-      @target_class.send(:alias_method, aliased, method_name) # Aliases original implementation to our private name.
+      install_wrapper(method_name, visibility)
+      @wrapped_methods[method_name] = visibility
+      @qualified_names[method_name] = qualified_name(method_name)
+      true
+    end
 
-      tracer = self
-      key = @tracer_key # unique per tracer instance; prevents cross-tracer interference
+    # Restore a traced method to its original implementation and visibility.
+    #
+    # @param name [Symbol, String] Method to untrace
+    # @return [Boolean] true if the method was traced by this tracer
+    def untrace_method(name)
+      method_name = name.to_sym
+      visibility = @wrapped_methods.delete(method_name)
+      return false unless visibility
 
-      # 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))
+      aliased = alias_for(method_name)
+      @target_class.send(:alias_method, method_name, aliased)
+      @target_class.send(:remove_method, aliased)
+      @target_class.send(visibility, method_name)
+      @qualified_names.delete(method_name)
+      true
+    end
 
-      @target_class.send(visibility, method_name) # Restores the original visibility after redefine.
+    # Restore every method this tracer wrapped.
+    #
+    # @return [Array<Symbol>] The methods that were untraced
+    def untrace_all
+      @wrapped_methods.keys.each_with_object([]) do |method_name, untraced|
+        untraced << method_name if untrace_method(method_name)
+      end
     end
 
+    # Called by the generated wrapper once per invocation. Kept public because
+    # it is the documented way to feed a tracer by hand.
     def record_call(method_name, execution_time, status, error = nil)
       return if execution_time < @options[:threshold]
 
       call_details = {
-        method_name: "#{@target_class}##{method_name}",
+        method_name: @qualified_names[method_name] || qualified_name(method_name),
         execution_time: execution_time,
         status: status,
         error: error,
@@ -88,12 +130,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
 
@@ -105,55 +154,92 @@ module RubyMethodTracer
       nil
     end
 
-    # Marks a method as wrapped to avoid duplicates
-    def mark_wrapped?(method_name)
-      return false if @wrapped_methods.include?(method_name)
+    # Alias the original body aside, define the traced replacement in its
+    # place, and put the original visibility back.
+    def install_wrapper(method_name, visibility)
+      aliased = alias_for(method_name)
+      @target_class.send(:alias_method, aliased, method_name)
+      # Keep the alias out of the public API: alias_method inherits the
+      # original's visibility, which would otherwise expose it on every object.
+      @target_class.send(:private, aliased)
+      define_accessor
+      Wrapper.install(@target_class, method_name, aliased, @accessor, wrapper_plan(method_name))
+      @target_class.send(visibility, method_name)
+    end
+
+    # What the generated wrapper should do around the call. Overridden by
+    # EnhancedTracer to add the call-tree hook.
+    def wrapper_plan(_method_name)
+      Wrapper::Plan.new(key: @tracer_key, close: :record_call)
+    end
+
+    # Generated wrappers are compiled from a string and cannot close over the
+    # tracer, so they reach it through this private accessor instead.
+    def define_accessor
+      return if @accessor_defined
 
-      @wrapped_methods << method_name
+      tracer = self
+      @target_class.define_method(@accessor) { tracer }
+      @target_class.send(:private, @accessor)
+      @accessor_defined = true
+    end
+
+    # A method is already traced when this tracer wrapped it, or when the alias
+    # is present because some other tracer did. Wrapping twice would alias the
+    # existing wrapper onto itself and recurse until the stack runs out.
+    def already_traced?(method_name)
+      return true if @wrapped_methods.key?(method_name)
+
+      aliased = alias_for(method_name)
+      return false unless @target_class.private_method_defined?(aliased) ||
+                          @target_class.method_defined?(aliased)
+
+      @logger.warn("RubyMethodTracer: #{@target_class}##{method_name} is already traced; skipping")
       true
     end
 
-    def alias_for(method_name)
-      :"__ruby_method_tracer_original_#{method_name}__"
-    end
-
-    def build_wrapper(aliased, method_name, key, tracer)
-      proc do |*args, **kwargs, &block|                                # Captures args and block exactly like original.
-        tracer.__send__(:wrap_call, method_name, key) do               # Delegates to wrapper to handle timing and flag.
-          # Ruby 3+ compatible keyword argument forwarding
-          if kwargs.empty?
-            __send__(aliased, *args, &block)                           # Calls without kwargs to avoid Ruby warnings
-          else
-            __send__(aliased, *args, **kwargs, &block)                 # Calls the original aliased implementation.
-          end
-        end
-      end
+    def warn_missing(method_name)
+      @logger.warn("RubyMethodTracer: #{@target_class} has no method ##{method_name}; not traced")
     end
 
-    def wrap_call(method_name, key)
-      return yield if Thread.current[key]
-
-      Thread.current[key] = true
-      start = monotonic_time
-      begin
-        result = yield
-        record_call(method_name, monotonic_time - start, :success)
-        result
-      rescue StandardError => e
-        record_call(method_name, monotonic_time - start, :error, e)
-        raise
-      ensure
-        Thread.current[key] = false
-      end
+    # Singleton classes stringify as "#<Class:Foo>"; render those as "Foo.bar"
+    # so traced class methods read the way they are called.
+    def qualified_name(method_name)
+      return "#{@target_class}##{method_name}" unless @target_class.singleton_class?
+
+      "#{singleton_owner}.#{method_name}"
     end
 
+    # Module#attached_object is Ruby 3.2+; fall back to unwrapping the string
+    # form on older versions.
+    def singleton_owner
+      return @target_class.attached_object if @target_class.respond_to?(:attached_object)
+
+      @target_class.to_s[/\A#<Class:(.+)>\z/, 1] || @target_class.to_s
+    end
+
+    # Name under which the original implementation is kept.
+    #
+    # The generated wrapper calls this alias directly rather than through
+    # `__send__`, which is faster but requires a name the parser accepts as an
+    # identifier. Predicate (`foo?`), bang (`foo!`), setter (`foo=`) and
+    # operator (`==`, `[]`, `<=>`) methods are not, so those are hex-encoded.
+    # Deterministic either way, so `untrace_method` reconstructs the same name.
+    def alias_for(method_name)
+      name = method_name.to_s
+      part = PLAIN_IDENTIFIER.match?(name) ? name : "op_#{name.unpack1("H*")}"
+      :"__ruby_method_tracer_original_#{part}__"
+    end
+
+    # Only used by tracers feeding themselves; the generated wrapper reads the
+    # clock inline so the call path carries no extra frames.
     def monotonic_time
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def output_call(call)
       time_str = colorize(format_time(call[:execution_time]), :yellow)
-      status_str = call[:status] == :error ? colorize("[ERROR]", :red) : colorize("[OK]", :green)
+      status_str = status_label(call[:status])
       method_name = colorize(call[:method_name], :cyan)
       if call[:status] == :error
         @logger.warn(
@@ -164,6 +250,14 @@ module RubyMethodTracer
       end
     end
 
+    def status_label(status)
+      case status
+      when :error then colorize("[ERROR]", :red)
+      when :incomplete then colorize("[INCOMPLETE]", :yellow)
+      else colorize("[OK]", :green)
+      end
+    end
+
     def format_time(seconds)
       @formatter.format_time(seconds)
     end
@@ -172,4 +266,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.5.0"
 end

data/lib/ruby_method_tracer/wrapper.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  # Wrapper generates the traced replacement for a method.
+  #
+  # Two things drive the design:
+  #
+  # 1. **Signature fidelity.** The replacement is built with `module_eval` from
+  #    the original method's `parameters`, not from a generic
+  #    `proc { |*args, **kwargs, &block| }`, so `Method#arity` and
+  #    `Method#parameters` survive tracing and reflection-driven callers
+  #    (dependency injection, serializers, argument validators, documentation
+  #    tooling) still see the real signature.
+  #
+  # 2. **Per-call cost.** The whole timing path is emitted inline: the
+  #    reentrancy guard, both clock reads and the `begin/rescue/ensure` live in
+  #    the generated method itself. It calls the tracer exactly once per
+  #    invocation (twice when tracking hierarchy), instead of threading a block
+  #    down through several tracer methods — each of those frames cost a call
+  #    plus a `Proc`. Everything knowable at trace time (the reentrancy key, the
+  #    method name, the display name) is baked in as a literal so no hash
+  #    lookups happen on the call path.
+  #
+  # Optional positional and optional keyword parameters are declared with
+  # OMITTED as their default. Omitted values are dropped before forwarding, so
+  # the original method still applies its own defaults — `parameters` does not
+  # expose default values, so they cannot be reproduced here.
+  #
+  # The one signature difference that remains: a block parameter is always
+  # declared, even when the original had none, because a method may still
+  # `yield`. Block parameters do not affect arity.
+  module Wrapper
+    # Sentinel marking "this optional argument was not supplied". Referenced by
+    # generated code, so it must stay a public constant.
+    OMITTED = Object.new
+
+    SENTINEL = "::RubyMethodTracer::Wrapper::OMITTED"
+    IDENTIFIER = /\A[a-z_][A-Za-z0-9_]*\z/
+    private_constant :SENTINEL, :IDENTIFIER
+
+    # What the generated wrapper should do, beyond forwarding the call.
+    #
+    # @!attribute key
+    #   @return [Symbol] Thread-local key for the reentrancy guard
+    # @!attribute close
+    #   @return [Symbol] Tracer method called with (name, duration, status, error)
+    # @!attribute open
+    #   @return [Symbol, nil] Tracer method called before the call, with the display name
+    # @!attribute display_name
+    #   @return [String, nil] Literal passed to the open hook
+    Plan = Struct.new(:key, :close, :open, :display_name, keyword_init: true)
+
+    # Build a signature description for a parameter list.
+    #
+    # Produces the parameter declaration, the setup that rebuilds the argument
+    # list at call time, and the forwarding call itself. Methods whose every
+    # parameter forwards unconditionally — no optional positionals, no keywords —
+    # skip the argument array entirely and forward straight through, which is
+    # the common case.
+    class Signature
+      # Parameter kind => the builder that emits its declaration and forwarding.
+      HANDLERS = {
+        req: :required,
+        opt: :optional,
+        rest: :splat,
+        keyreq: :keyword_required,
+        key: :keyword_optional,
+        keyrest: :keyword_splat,
+        nokey: :nokey,
+        block: :block_param
+      }.freeze
+      private_constant :HANDLERS
+
+      # Ruby 3.0 reports `def m(...)` as a bare rest plus a block and omits the
+      # keyword rest; 3.1+ includes [:keyrest, :**]. On 3.1+ no repair is
+      # needed, and guessing would be wrong there — `def m(*, &)` reports the
+      # same shape and genuinely takes no keywords.
+      FORWARDING_OMITS_KEYWORDS = RUBY_VERSION < "3.1"
+      FORWARD_REST = %i[rest *].freeze
+      FORWARD_BLOCK = %i[block &].freeze
+      FORWARD_KEYREST = %i[keyrest **].freeze
+      private_constant :FORWARDING_OMITS_KEYWORDS, :FORWARD_REST, :FORWARD_BLOCK, :FORWARD_KEYREST
+
+      # @param params [Array] Parameter list as reported by Method#parameters
+      # @param repair_forwarding [Boolean] Put back the keyword rest that this
+      #   Ruby omits when describing `...`. Injectable so the repair can be
+      #   exercised on any version.
+      def initialize(params, repair_forwarding: FORWARDING_OMITS_KEYWORDS)
+        params = with_forwarded_keywords(params) if repair_forwarding
+        @declaration = []
+        @positional = []
+        @keyword = []
+        @direct = []
+        @block_name = nil
+        @nokey = false
+        @dynamic = false
+        params.each_with_index { |(kind, name), index| add(kind, name, index) }
+        @declaration << "&#{block_name}"
+      end
+
+      def declaration
+        @declaration.join(", ")
+      end
+
+      # Rebuilds the outgoing argument list. Empty for the direct path.
+      def setup
+        return "" if direct?
+
+        lines = ["__rmt_args__ = []", *@positional]
+        lines += ["__rmt_kwargs__ = {}", *@keyword] unless keywordless?
+        lines.join("\n  ")
+      end
+
+      def forward(aliased)
+        return "#{aliased}(#{(@direct + ["&#{block_name}"]).join(", ")})" if direct?
+
+        plain = "#{aliased}(*__rmt_args__, &#{block_name})"
+        return plain if keywordless?
+
+        # The empty check keeps `**{}` off the call site, which is what broke
+        # keyword forwarding on Ruby 3.4 (see CHANGELOG 0.3.2 and 0.3.3).
+        # Parenthesised so the expression stays intact wherever it is spliced in.
+        "(__rmt_kwargs__.empty? ? #{plain} : " \
+          "#{aliased}(*__rmt_args__, **__rmt_kwargs__, &#{block_name}))"
+      end
+
+      private
+
+      # Every parameter forwards unconditionally and no keywords are involved,
+      # so the call can be written out literally.
+      def direct?
+        !@dynamic && @keyword.empty? && !@nokey
+      end
+
+      def keywordless?
+        @nokey || @keyword.empty?
+      end
+
+      def block_name
+        @block_name ||= "__rmt_block__"
+      end
+
+      def add(kind, name, index)
+        handler = HANDLERS[kind]
+        send(handler, local_name(name, index)) if handler
+      end
+
+      def required(name)
+        @declaration << name
+        @positional << "__rmt_args__ << #{name}"
+        @direct << name
+      end
+
+      def optional(name)
+        @declaration << "#{name} = #{SENTINEL}"
+        @positional << "__rmt_args__ << #{name} unless #{SENTINEL}.equal?(#{name})"
+        @dynamic = true
+      end
+
+      def splat(name)
+        @declaration << "*#{name}"
+        @positional << "__rmt_args__.concat(#{name})"
+        @direct << "*#{name}"
+      end
+
+      def keyword_required(name)
+        @declaration << "#{name}:"
+        @keyword << "__rmt_kwargs__[:#{name}] = #{name}"
+      end
+
+      def keyword_optional(name)
+        @declaration << "#{name}: #{SENTINEL}"
+        @keyword << "__rmt_kwargs__[:#{name}] = #{name} unless #{SENTINEL}.equal?(#{name})"
+      end
+
+      def keyword_splat(name)
+        @declaration << "**#{name}"
+        @keyword << "__rmt_kwargs__.update(#{name})"
+      end
+
+      def nokey(_name)
+        @declaration << "**nil"
+        @nokey = true
+      end
+
+      def block_param(name)
+        @block_name = name
+      end
+
+      # Ruby 3.0 omits the keyword rest when reporting `def m(...)`. Taken at
+      # face value the wrapper would declare only `*rest`, funnel any keywords
+      # into the positional array, and forward them as a trailing Hash — which
+      # raises ArgumentError at the original. Put the missing keyrest back so
+      # the generated wrapper matches what 3.1+ would have described.
+      def with_forwarded_keywords(params)
+        return params unless params.first == FORWARD_REST && params.include?(FORWARD_BLOCK)
+        return params if params.any? { |kind, _| kind == :keyrest }
+
+        block, rest = params.partition { |kind, _| kind == :block }
+        rest + [FORWARD_KEYREST] + block
+      end
+
+      # Anonymous parameters (`def m(*)`) and argument forwarding (`def m(...)`)
+      # report names that are unusable or absent; everything else keeps the
+      # original name so `parameters` still reports it.
+      def local_name(name, index)
+        return "__rmt_p#{index}__" if name.nil? || !IDENTIFIER.match?(name.to_s)
+
+        name.to_s
+      end
+    end
+
+    class << self
+      # Define the traced replacement for `method_name` on `target_class`.
+      #
+      # @param target_class [Module] Class the method lives on
+      # @param method_name [Symbol] Method being traced
+      # @param aliased [Symbol] Private alias holding the original body
+      # @param accessor [Symbol] Private method returning the owning tracer
+      # @param plan [Plan] What the wrapper should do around the call
+      # @return [Symbol] The defined method name
+      def install(target_class, method_name, aliased, accessor, plan)
+        signature = Signature.new(target_class.instance_method(aliased).parameters)
+        source = source(signature, method_name, aliased, accessor, plan)
+        target_class.module_eval(source, __FILE__, __LINE__)
+      end
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def source(signature, method_name, aliased, accessor, plan)
+        forward = signature.forward(aliased)
+        <<~RUBY
+          def #{method_name}(#{signature.declaration})
+            #{signature.setup}
+            __rmt_guard__ = (::Thread.current[#{plan.key.inspect}] ||= [false])
+            return #{forward} if __rmt_guard__[0]
+
+            __rmt_tracer__ = #{accessor}
+            __rmt_guard__[0] = true
+            #{open_hook(plan)}
+            __rmt_started__ = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            __rmt_status__ = :incomplete
+            __rmt_failure__ = nil
+            begin
+              __rmt_result__ = #{forward}
+              __rmt_status__ = :success
+              __rmt_result__
+            rescue ::StandardError => __rmt_caught__
+              __rmt_status__ = :error
+              __rmt_failure__ = __rmt_caught__
+              raise
+            ensure
+              __rmt_tracer__.#{plan.close}(
+                #{method_name.inspect},
+                ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - __rmt_started__,
+                __rmt_status__,
+                __rmt_failure__
+              )
+              __rmt_guard__[0] = false
+            end
+          end
+        RUBY
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def open_hook(plan)
+        return "" unless plan.open
+
+        "__rmt_tracer__.#{plan.open}(#{plan.display_name.inspect})"
+      end
+    end
+  end
+end

data/lib/ruby_method_tracer.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "ruby_method_tracer/version"
+require_relative "ruby_method_tracer/configuration"
+require_relative "ruby_method_tracer/wrapper"
 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 +30,41 @@ require_relative "ruby_method_tracer/formatters/tree_formatter"
 module RubyMethodTracer
   class Error < StandardError; end
 
+  @configuration = Configuration.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, before any threads are tracing.
+    #
+    #   RubyMethodTracer.configure do |config|
+    #     config.threshold = 0.005
+    #   end
+    #
+    # No lock is held across the block: a Mutex here bought no real safety
+    # (`configuration` hands out the same mutable object without one) while
+    # making a nested `configure` — easy to reach through a helper or an engine
+    # initializer — deadlock on recursive locking.
+    #
+    # @yieldparam config [RubyMethodTracer::Configuration]
+    # @return [RubyMethodTracer::Configuration]
+    def configure
+      yield(@configuration) if block_given?
+      @configuration
+    end
+
+    # Reset the global configuration back to built-in defaults.
+    #
+    # @return [RubyMethodTracer::Configuration]
+    def reset_configuration!
+      @configuration.reset!
+    end
+  end
+
   def self.included(base)
     base.extend(ClassMethods)
   end
@@ -43,11 +82,34 @@ module RubyMethodTracer
   #   end
   #   MyService.trace_methods(:call, threshold: 0.005, auto_output: true)
   module ClassMethods
+    # Trace instance methods on this class.
+    #
+    # The tracer is memoized per class, so repeated calls add methods to the
+    # same tracer rather than wrapping a method twice. Options are read on the
+    # first call; pass no names to fetch the existing tracer.
+    #
+    # @param method_names [Array<Symbol>] Methods to trace
+    # @param options [Hash] Options for SimpleTracer (first call only)
+    # @return [RubyMethodTracer::SimpleTracer] The tracer, so results can be read
     def trace_methods(*method_names, **options)
-      tracer = SimpleTracer.new(self, **options)
-      method_names.each do |method_name|
-        tracer.trace_method(method_name)
-      end
+      tracer = (@__ruby_method_tracer ||= SimpleTracer.new(self, **options))
+      method_names.each { |method_name| tracer.trace_method(method_name) }
+      tracer
+    end
+
+    # Trace class (singleton) methods on this class.
+    #
+    #   class Report
+    #     include RubyMethodTracer
+    #     def self.generate; end
+    #   end
+    #   tracer = Report.trace_class_methods(:generate)
+    #
+    # @return [RubyMethodTracer::SimpleTracer] The tracer, so results can be read
+    def trace_class_methods(*method_names, **options)
+      tracer = (@__ruby_method_tracer_class ||= SimpleTracer.new(singleton_class, **options))
+      method_names.each { |method_name| tracer.trace_method(method_name) }
+      tracer
     end
   end
 end