profile-tools 0.1.0 → 0.2.0

data/lib/profile_tools/collector.rb

@@ -1,97 +1,72 @@
 # frozen_string_literal: true
 
-require 'concurrent'
-
-class ProfileTools
-  # Collects stats around method calls
+module ProfileTools
+  # Measures calls and adds them up per method for one profiling run (a request, a job, a block).
+  #
+  # Allocations are read from GC.stat(:total_allocated_objects), which only goes up, so the
+  # counts stay exact when garbage collection runs mid-call. The counter is process-wide:
+  # objects allocated by other threads at the same time are counted too.
+  #
+  # Nothing is allocated between the start and end readings, so a profiled method nested
+  # inside another doesn't add to the outer method's count.
   class Collector
-    attr_reader :methods,
-                :total_collection_calls
+    # @return [Hash{String => MethodStats}] stats for every method seen by this collector
+    attr_reader :stats
 
-    def initialize
-      @methods = {}
-      @total_collection_calls = 0
+    # Creates the stats for the given methods up front. A method seen for the first time
+    # inside another method's call allocates its {MethodStats}, which that outer call counts.
+    #
+    # @param method_names [Array<String>] display names of the profiled methods
+    def initialize(method_names = [])
+      @stats = {}
       @sort_order = 0
+      method_names.each { |method| stats_for(method) }
     end
 
-    def init_method(method)
-      @methods[method] = {
-        method: method,
-        duration: 0.0,
-        calls: 0,
-        count_objects: Hash.new(0),
-        num_collection_calls: 0,
-        sort_order: nil
-      }
+    # Runs the block and adds its time, allocations and garbage collection to the method's totals.
+    # A call made while the same method is already running is counted but not measured again.
+    #
+    # @param method [String] display name of the method
+    # @yield the code to measure
+    # @return [Object] the block's result
+    def instrument(method, &)
+      stats = stats_for(method)
+      recursive = stats.running?
+      stats.enter(@sort_order += 1)
+      begin
+        recursive ? yield : measure(stats, &)
+      ensure
+        stats.leave
+      end
     end
 
+    # @return [Array<MethodStats>] the methods that were called, in the order they were first called
     def called_methods
-      @methods
-        .values
-        .reject { |info| info[:calls].zero? }
-        .sort { |a, b| a[:sort_order] <=> b[:sort_order] }
-    end
-
-    def instrument(method)
-      current_collection_calls = @total_collection_calls
-      result = nil
-      duration = nil
-      @methods[method][:sort_order] ||= (@sort_order += 1)
-      count_objects = count_objects_around do
-        started_at = now
-        result = yield
-        duration = now - started_at
-      end
-      add(
-        method,
-        duration * 1000.0,
-        count_objects,
-        @total_collection_calls - current_collection_calls
-      )
-      result
+      @stats.values.select(&:called?).sort_by(&:sort_order)
     end
 
     private
 
-    def add(method, duration, count_object_changes, num_collection_calls)
-      @total_collection_calls += 1
-      @methods[method][:calls] += 1
-      @methods[method][:duration] += duration
-      @methods[method][:num_collection_calls] = num_collection_calls
-      add_object_changes(@methods[method][:count_objects], count_object_changes)
-      adjust_count_objects(@methods[method][:count_objects], num_collection_calls)
-    end
-
-    def add_object_changes(current_objects, new_objects)
-      new_objects.each do |name, cnt|
-        current_objects[name] += cnt
-      end
-      current_objects
+    def stats_for(method)
+      @stats[method] ||= MethodStats.new(method)
     end
 
-    def adjust_count_objects(count_objects, num_collection_calls)
-      return if num_collection_calls.zero?
-
-      count_objects[:T_STRING] -= (1 * num_collection_calls)
-      count_objects[:T_ARRAY] -= (1 * num_collection_calls)
-      count_objects[:T_HASH] -= (2 * num_collection_calls)
+    def measure(stats)
+      started_at = now
+      allocations = allocated_objects
+      gc_count = GC.count
+      gc_time = GC.stat(:time)
+      yield
+    ensure
+      stats.add(now - started_at, allocated_objects - allocations, GC.count - gc_count, GC.stat(:time) - gc_time)
     end
 
     def now
-      Concurrent.monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
     end
 
-    def count_objects_changes(starting_objects, new_objects)
-      new_objects.each do |name, _|
-        new_objects[name] -= starting_objects[name]
-        new_objects[name] -= 1 if name == :T_HASH
-      end
-    end
-
-    def count_objects_around
-      starting_objects = ObjectSpace.count_objects
-      yield
-      count_objects_changes(starting_objects, ObjectSpace.count_objects)
+    def allocated_objects
+      GC.stat(:total_allocated_objects)
     end
   end
 end

data/lib/profile_tools/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Base class for errors raised by ProfileTools
+  class Error < StandardError; end
+end

data/lib/profile_tools/log_subscriber.rb

@@ -1,22 +1,36 @@
 # frozen_string_literal: true
 
-class ProfileTools
-  # Logs the collector stats
+require 'active_support'
+require 'active_support/log_subscriber'
+
+module ProfileTools
+  # Writes one log line per called method when a profiling run finishes.
+  #
+  #   ProfileTools::LogSubscriber.attach_to :profile_tools
+  #
+  # The {Railtie} attaches it for you. Lines are logged at info level to
+  # ActiveSupport::LogSubscriber.logger (Rails.logger in a Rails app).
   class LogSubscriber < ActiveSupport::LogSubscriber
+    # Logs the stats of every method called during the run.
+    #
+    # @param event [ActiveSupport::Notifications::Event] carries the run's collector in its payload
+    # @return [void]
     def profile(event)
-      event.payload[:collector].called_methods.each do |info|
-        duration = info[:duration].round(5)
-        count_objects = display_count_objects(info[:count_objects])
-        logger.info "method #{info[:method]} took #{duration}ms, called #{info[:calls]}, objects: #{count_objects}"
+      event.payload[:collector].called_methods.each do |stats|
+        info { format_stats(stats) }
       end
     end
+    subscribe_log_level :profile, :info
 
     private
 
-    def display_count_objects(count_objects)
-      count_objects.reject! { |_, cnt| cnt.zero? }
-      count_objects.delete(:FREE)
-      count_objects.to_a.map { |k, v| "#{k}: #{v}" }.join(', ')
+    def format_stats(stats)
+      "[ProfileTools] #{stats.method}: #{pluralize(stats.calls, 'call')}, #{stats.duration.round(3)}ms, " \
+        "#{pluralize(stats.allocations, 'allocation')}, #{pluralize(stats.gc_count, 'GC run')} (#{stats.gc_time}ms)"
+    end
+
+    def pluralize(count, word)
+      "#{count} #{count == 1 ? word : "#{word}s"}"
     end
   end
 end

data/lib/profile_tools/method_name.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # A method to profile, named the way Ruby docs name methods:
+  # "User#save" for an instance method, "User.find" for a class method.
+  class MethodName
+    # Splits "Class#method" or "Class.method". The class part may be namespaced ("Admin::User").
+    PATTERN = /\A(?<class_name>[A-Z]\w*(?:::[A-Z]\w*)*)(?<separator>[#.])(?<method_name>.+)\z/
+
+    # @return [String] the full name, such as "User#save"
+    attr_reader :name
+
+    # @return [String] the class or module name, such as "User"
+    attr_reader :class_name
+
+    # @return [Symbol] the method name, such as :save
+    attr_reader :method_name
+
+    # @param name [String, Symbol] "Class#method" or "Class.method"
+    # @raise [Error] if the name isn't in either form
+    def initialize(name)
+      match = PATTERN.match(name.to_s)
+      raise Error, "#{name.inspect} is not a method name, expected Class#method or Class.method" unless match
+
+      @name = name.to_s.freeze
+      @class_name = match[:class_name]
+      @method_name = match[:method_name].to_sym
+      @class_method = match[:separator] == '.'
+    end
+
+    # @return [Boolean] true for a class method ("User.find")
+    def class_method?
+      @class_method
+    end
+
+    # The class or module the method is defined on: the singleton class for a class method.
+    # Looking it up loads the constant, so this autoloads app classes.
+    #
+    # @return [Module]
+    # @raise [NameError] if the class doesn't exist
+    def owner
+      constant = Object.const_get(class_name)
+      class_method? ? constant.singleton_class : constant
+    end
+
+    # @return [String] the full name
+    def to_s
+      name
+    end
+  end
+end

data/lib/profile_tools/method_stats.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Totals for one profiled method within a single {Collector}.
+  #
+  # Duration, allocations and GC numbers include everything the method calls.
+  # Recursive calls are counted in {#calls}, but only the outermost call is
+  # measured, so a recursive method isn't counted twice.
+  class MethodStats
+    # @return [String] the method's display name, such as "User#save" or "User.find"
+    attr_reader :method
+
+    # @return [Integer] how many times the method was called
+    attr_reader :calls
+
+    # @return [Float] total time spent in the method, in milliseconds
+    attr_reader :duration
+
+    # @return [Integer] objects allocated while the method ran
+    attr_reader :allocations
+
+    # @return [Integer] garbage collections that ran while the method ran
+    attr_reader :gc_count
+
+    # @return [Integer] time spent in garbage collection while the method ran, in milliseconds
+    attr_reader :gc_time
+
+    # @return [Integer, nil] order in which the method was first called, nil until it is called
+    attr_reader :sort_order
+
+    # @param method [String] display name of the method
+    def initialize(method)
+      @method = method
+      @calls = 0
+      @duration = 0.0
+      @allocations = 0
+      @gc_count = 0
+      @gc_time = 0
+      @sort_order = nil
+      @depth = 0
+    end
+
+    # @return [Boolean] true once the method has been called
+    def called?
+      @calls.positive?
+    end
+
+    # @return [Boolean] true while a call to the method is in progress, so a nested call is recursion
+    def running?
+      @depth.positive?
+    end
+
+    # Records the start of a call.
+    #
+    # @api private
+    # @param sort_order [Integer] position to use if this is the method's first call
+    # @return [void]
+    def enter(sort_order)
+      @sort_order ||= sort_order
+      @calls += 1
+      @depth += 1
+    end
+
+    # Records the end of a call.
+    #
+    # @api private
+    # @return [void]
+    def leave
+      @depth -= 1
+    end
+
+    # Adds one measured call to the totals.
+    #
+    # @api private
+    # @param duration [Float] milliseconds
+    # @param allocations [Integer] objects allocated
+    # @param gc_count [Integer] garbage collections
+    # @param gc_time [Integer] milliseconds spent in garbage collection
+    # @return [void]
+    def add(duration, allocations, gc_count, gc_time)
+      @duration += duration
+      @allocations += allocations
+      @gc_count += gc_count
+      @gc_time += gc_time
+    end
+
+    # @return [Hash] the totals as a hash
+    def to_h
+      {
+        method: method,
+        calls: calls,
+        duration: duration,
+        allocations: allocations,
+        gc_count: gc_count,
+        gc_time: gc_time
+      }
+    end
+  end
+end

data/lib/profile_tools/method_wrapper.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Adds and removes the profiling wrapper around a method.
+  #
+  # Wrappers live in a module prepended to the method's class (one per class, reused),
+  # so the original method is never renamed. Each wrapper forwards its arguments with
+  # `...` and calls `super`, which keeps positional, keyword and block arguments intact
+  # and allocates nothing per call.
+  class MethodWrapper
+    # Method names that can't be written as `def name(...)`, wrapped with define_method instead.
+    DEF_NAME = %r{\A(?:[A-Za-z_]\w*[?!=]?|\[\]=?|[-+]@|[-+*/%<>!~^&|`]|\*\*|<=>|===?|=~|!=|!~|<<|>>|<=|>=)\z}
+
+    # Marks the modules this class prepends, so they're found again and shown clearly in ancestors.
+    class WrapperModule < Module
+      # @return [String]
+      def inspect
+        'ProfileTools::MethodWrapper::WrapperModule'
+      end
+      alias to_s inspect
+    end
+
+    # @param method_name [MethodName] the method to wrap
+    def initialize(method_name)
+      @method_name = method_name
+      @owner = method_name.owner
+    end
+
+    # Wraps the method. Its visibility (public, protected or private) is kept.
+    #
+    # @return [void]
+    # @raise [UnknownMethodError] if the class doesn't define the method
+    def wrap
+      visibility = method_visibility
+      raise UnknownMethodError, "#{@method_name} is not defined" unless visibility
+
+      define_wrapper(wrapper_module)
+      wrapper_module.send(visibility, name)
+    end
+
+    # Removes the wrapper added by {#wrap}. The original method is untouched, so calls go
+    # straight to it again.
+    #
+    # @return [void]
+    def unwrap
+      existing_wrapper_module.send(:remove_method, name)
+    end
+
+    private
+
+    def name
+      @method_name.method_name
+    end
+
+    def method_visibility
+      if @owner.public_method_defined?(name) then :public
+      elsif @owner.protected_method_defined?(name) then :protected
+      elsif @owner.private_method_defined?(name) then :private
+      end
+    end
+
+    def wrapper_module
+      existing_wrapper_module || WrapperModule.new.tap { |module_| @owner.prepend(module_) }
+    end
+
+    # Only modules prepended directly to the owner come before it in its ancestors.
+    def existing_wrapper_module
+      @owner.ancestors.take_while { |ancestor| ancestor != @owner }.grep(WrapperModule).first
+    end
+
+    def define_wrapper(module_)
+      if DEF_NAME.match?(name.to_s)
+        module_.module_eval(def_source, __FILE__, __LINE__)
+      else
+        define_method_wrapper(module_)
+      end
+    end
+
+    # `"...".freeze` compiles to a single frozen string, so passing the display name allocates nothing.
+    def def_source
+      <<~RUBY
+        def #{name}(...)
+          ::ProfileTools.profiler.instrument(#{@method_name.name.dump}.freeze) { super(...) }
+        end
+      RUBY
+    end
+
+    def define_method_wrapper(module_)
+      display_name = @method_name.name
+      module_.send(:define_method, name) do |*args, **kwargs, &block|
+        ::ProfileTools.profiler.instrument(display_name) { super(*args, **kwargs, &block) }
+      end
+    end
+  end
+end

data/lib/profile_tools/middleware.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Rack middleware that makes each request one profiling run, so the profiled methods it calls
+  # are reported together, under a "GET /path" line for the whole request.
+  #
+  # The {Railtie} adds it when a config file is present. Without it, every outermost call to a
+  # profiled method is reported on its own.
+  class Middleware
+    # @param app [#call] the next Rack app
+    def initialize(app)
+      @app = app
+    end
+
+    # @param env [Hash] the Rack environment
+    # @return [Array] the Rack response
+    def call(env)
+      ProfileTools.instrument("#{env['REQUEST_METHOD']} #{env['PATH_INFO']}") { @app.call(env) }
+    end
+  end
+end

data/lib/profile_tools/profiler.rb

@@ -1,59 +1,52 @@
 # frozen_string_literal: true
 
-class ProfileTools
-  # Aggregates profile stats into the collector
+require 'active_support'
+require 'active_support/notifications'
+
+module ProfileTools
+  # Tracks the profiling run on the current thread (fiber-local, through Thread.current).
+  #
+  # The outermost {#instrument} call starts a run: it creates a {Collector} and publishes it in
+  # a "profile.profile_tools" ActiveSupport notification once the block finishes. Calls made
+  # during the run add to that collector.
   class Profiler
+    # Name used by {ProfileTools.instrument} when none is given
+    DEFAULT_NAME = 'ProfileTools.instrument'
+
+    # @return [Collector, nil] the collector of the current run, or of the last finished run
     attr_reader :collector
 
     def initialize
-      @call_depth = 0
-    end
-
-    def instrument(class_and_method_name = 'ProfileTools::Profiler#instrument')
-      result = nil
-      if increment_call_depth == 1
-        @collector = new_collector
-        @collector.init_method(class_and_method_name)
-        instrument_with_notifications(class_and_method_name) do
-          result = yield
-        end
-      else
-        instrument_with_collector(class_and_method_name) do
-          result = yield
-        end
-      end
-      decrement_call_depth
-      result
+      @collector = nil
+      @running = false
     end
 
-    private
+    # Measures the block as the named method. Starts a new run if none is in progress.
+    #
+    # @param name [String] display name to record the block under
+    # @yield the code to measure
+    # @return [Object] the block's result
+    def instrument(name = DEFAULT_NAME, &)
+      return @collector.instrument(name, &) if running?
 
-    def instrument_with_notifications(class_and_method_name)
-      ActiveSupport::Notifications.instrument(EVENT, collector: @collector) do
-        instrument_with_collector(class_and_method_name) do
-          yield
-        end
-      end
+      run(name, &)
     end
 
-    def instrument_with_collector(class_and_method_name)
-      @collector.instrument(class_and_method_name) do
-        yield
-      end
-    end
-
-    def increment_call_depth
-      @call_depth += 1
+    # @return [Boolean] true while a run is in progress
+    def running?
+      @running
     end
 
-    def decrement_call_depth
-      @call_depth -= 1
-    end
+    private
 
-    def new_collector
-      ::ProfileTools::Collector.new.tap do |collector|
-        ::ProfileTools.profiled_methods.each { |display_name| collector.init_method(display_name) }
+    def run(name, &)
+      @running = true
+      @collector = Collector.new(ProfileTools.profiled_methods)
+      ActiveSupport::Notifications.instrument(EVENT, name: name, collector: @collector) do
+        @collector.instrument(name, &)
       end
+    ensure
+      @running = false
     end
   end
 end

data/lib/profile_tools/railtie.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module ProfileTools
+  # Turns profiling on in a Rails app when a config file is present, with no code changes:
+  # put the file in place, restart, read the log, remove the file, restart.
+  #
+  # The file is config/profile_tools.yml, or the path in the PROFILE_TOOLS_CONFIG environment
+  # variable. When it exists, the Railtie adds {Middleware} after Rails::Rack::Logger (so log
+  # lines keep the request's tags), attaches {LogSubscriber}, and once the app has booted
+  # (and eager loaded) wraps the methods the file lists.
+  class Railtie < Rails::Railtie
+    initializer('profile_tools.middleware') { |app| ProfileTools::Railtie.setup(app) }
+    config.after_initialize { |app| ProfileTools::Railtie.profile(app) }
+
+    class << self
+      # @param app [Rails::Application]
+      # @return [Pathname] where the config file is looked for
+      def config_path(app)
+        Pathname.new(ENV.fetch('PROFILE_TOOLS_CONFIG') { app.root.join('config/profile_tools.yml') })
+      end
+
+      # Adds the middleware and log subscriber if the config file exists.
+      #
+      # @api private
+      # @param app [Rails::Application]
+      # @return [void]
+      def setup(app)
+        return unless config_path(app).exist?
+
+        app.config.middleware.insert_after Rails::Rack::Logger, ProfileTools::Middleware
+        ProfileTools::LogSubscriber.attach_to :profile_tools
+      end
+
+      # Profiles the methods in the config file if it exists.
+      #
+      # @api private
+      # @param app [Rails::Application]
+      # @return [void]
+      def profile(app)
+        path = config_path(app)
+        ProfileTools.load(path) if path.exist?
+      end
+    end
+  end
+end

data/lib/profile_tools/unknown_method_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Raised when asked to profile a method the class doesn't define
+  class UnknownMethodError < Error; end
+end

data/lib/profile_tools/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ProfileTools
+  # Gem version, bumped by release-please
+  VERSION = '0.2.0'
+end