method_profiler 0.1.0 → 1.0.0

data/.gitignore

@@ -2,3 +2,6 @@
 .bundle
 Gemfile.lock
 pkg/*
+coverage/*
+.yardoc/*
+doc/*

data/README.md

@@ -1,19 +1,87 @@
 # MethodProfiler
 
-**MethodProfiler** collects performance information about the methods in your objects and creates reports to help you identify slow methods.
+**MethodProfiler** collects performance information about the methods in your objects and creates reports to help you identify slow methods. The collected data can be sorted in various ways, converted into an array, or pretty printed as a table.
+
+## Basic usage
+
+Create a new profiler by passing the object you want to profile to `MethodProfiler.observe`. All future class and instance methods called on your object will be recorded by the profiler. To see the results of the profiling as a table, simply print out the report returned by `#report` on the profiler object.
 
 ```ruby
-profiler = MethodProfiler.new(MyClass)
-MyClass.new.foo
+profiler = MethodProfiler.observe(MyClass)
+
+MyClass.nisi_inventore
+MyClass.nisi_inventore
+
+my_obj = MyClass.new
+
+my_obj.accusamus_est
+my_obj.accusamus_est
+my_obj.accusamus_est
+
 puts profiler.report
+```
 
-# MethodProfiler results for:
-# MyClass
-# +--------+--------------+-------------+
-# | Method | Average Time | Total Calls |
-# +--------+--------------+-------------+
-# | foo    | 91.037000 ms | 1           |
-# | bar    | 15.016000 ms | 2           |
-# | baz    | 23.005000 ms | 1           |
-# +--------+--------------+-------------+
+The resulting chart includes each method, the minimum time it took to run, the maximum time, the average across all calls, and the total number of times it was called. Class methods are prefixed by a `.` and instance methods are prefixed with a `#`.
+
+```
+MethodProfiler results for: MyClass
++------------------------+-----------+------------+--------------+-------------+
+| Method                 | Min Time  | Max Time   | Average Time | Total Calls |
++------------------------+-----------+------------+--------------+-------------+
+| #accusamus_est         | 32.086 ms | 324.140 ms | 160.252 ms   | 3           |
+| #autem_iste!           | 29.607 ms | 318.592 ms | 156.221 ms   | 3           |
+| #distinctio_eos        | 29.477 ms | 318.471 ms | 156.097 ms   | 3           |
+| #laborum_fugit         | 18.388 ms | 291.900 ms | 140.580 ms   | 3           |
+| #suscipit_architecto   | 12.036 ms | 272.279 ms | 130.247 ms   | 3           |
+| #et_fugit              | 2.794 ms  | 11.658 ms  | 6.185 ms     | 3           |
+| #porro_rerum           | 0.097 ms  | 12.096 ms  | 1.031 ms     | 43          |
+| #provident_molestiae   | 0.005 ms  | 3.997 ms   | 0.871 ms     | 6           |
+| .nisi_inventore        | 0.368 ms  | 1.329 ms   | 0.849 ms     | 2           |
+| #quis_temporibus       | 0.104 ms  | 6.696 ms   | 0.713 ms     | 24          |
+| #labore_voluptatum     | 0.004 ms  | 8.834 ms   | 0.447 ms     | 86          |
+| #quia_est              | 0.004 ms  | 3.667 ms   | 0.327 ms     | 24          |
+| #ut_reiciendis         | 0.004 ms  | 2.842 ms   | 0.250 ms     | 24          |
+| #sint_quasi            | 0.066 ms  | 1.836 ms   | 0.166 ms     | 24          |
+| #sed_at                | 0.067 ms  | 0.119 ms   | 0.078 ms     | 24          |
+| #repellendus_suscipit  | 0.054 ms  | 0.128 ms   | 0.067 ms     | 24          |
+| #quas_nesciunt         | 0.024 ms  | 0.026 ms   | 0.025 ms     | 3           |
+| #iure_quis             | 0.006 ms  | 0.232 ms   | 0.014 ms     | 48          |
+| #dicta_ipsam           | 0.005 ms  | 0.068 ms   | 0.013 ms     | 24          |
+| #perspiciatis_aut      | 0.006 ms  | 0.006 ms   | 0.006 ms     | 3           |
+| #aperiam_laborum       | 0.004 ms  | 0.009 ms   | 0.005 ms     | 34          |
++------------------------+-----------+------------+--------------+-------------+
 ```
+
+## Reporting
+
+`MethodProfiler::Profiler#report` actually returns a report object which can be used to sort and display the data in various ways. A report has chainable `#sort_by` and `#order` methods to control the sorting of the report when it is ultimately displayed. The report can be turned into an array by calling `#to_a` and the table shown above by calling `#to_s`.
+
+*Example of sorting by the number of total calls, ascending:*
+
+```ruby
+puts profiler.report.sort_by(:total_calls).order(:ascending)
+```
+
+`#sort_by` accepts a symbol or string with the name of any of the columns in the table: `:method`, `:min`, `:max`, `:average`, or `:total_calls`.
+
+`#order` accepts a symbol or string of `:ascending` or `:descending`. These can also be abbreviated with `:asc` and `:desc`.
+
+## Documentation
+
+The public API is fully documented using [YARD](http://yardoc.org/) and can be viewed on [RubyDoc.info](http://rubydoc.info/).
+
+## Tests
+
+All code is tested with [RSpec](https://github.com/rspec/rspec). To run the specs, clone the repository, install the dependencies with `bundle install`, and then run `rake`.
+
+## Issues
+
+If you have any problems or suggestions for the project, please open a GitHub issue.
+
+## License
+
+MethodProfiler is available under the included MIT license.
+
+## Acknowledgements
+
+Thank you to [Change.org](http://www.change.org/) for sponsoring the project and to my coworker [Alain Bloch](https://github.com/alainbloch) for the inspiration.

data/lib/method_profiler.rb

@@ -1,103 +1,17 @@
-require 'benchmark'
-require 'hirb'
-
-class MethodProfiler
-  attr_reader :observed_methods, :data
-
-  def initialize(obj)
-    @obj = obj
-    initialize_data
-    find_obj_methods
-    wrap_methods_with_profiling
-  end
-
-  def profile(method, &block)
-    result = nil
-    benchmark = Benchmark.measure { result = block.call }
-    elapsed_time = benchmark.to_s.match(/\(\s*([^\)]+)\)/)[1].to_f
-    @data[method.to_sym] << elapsed_time
-    result
-  end
-
-  def report
-    [
-      "MethodProfiler results for: #{@obj}",
-      Hirb::Helpers::Table.render(
-        final_data,
-        headers: {
-          method: "Method",
-          min: "Min Time",
-          max: "Max Time",
-          average: "Average Time",
-          total_calls: "Total Calls"
-        },
-        fields: [:method, :min, :max, :average, :total_calls],
-        description: false
-      )
-    ].join("\n")
-  end
-
-  def reset!
-    initialize_data
-    @final_data = nil
-  end
-
-  private
-
-  def initialize_data
-    @data = Hash.new { |h, k| h[k] = [] }
-  end
-
-  def find_obj_methods
-    @observed_methods ||= begin
-      methods = @obj.instance_methods
-      @obj.ancestors.each do |a|
-        next if a == @obj
-        methods -= a.instance_methods
-      end
-      methods
-    end
-  end
-
-  def wrap_methods_with_profiling
-    profiler = self
-    observed = observed_methods
-
-    @obj.module_eval do
-      observed.each do |method|
-        define_method("#{method}_with_profiling") do |*args|
-          profiler.profile(method) { send("#{method}_without_profiling", *args) }
-        end
-
-        alias_method "#{method}_without_profiling", method
-        alias_method method, "#{method}_with_profiling"
-      end
-    end
-  end
-
-  def final_data
-    @final_data ||= begin
-      final_data = []
-      data.each do |method, records|
-        total_calls = records.size
-        average = records.reduce(:+) / total_calls
-        final_data << {
-          method: method,
-          min: records.min,
-          max: records.max,
-          average: average,
-          total_calls: total_calls
-        }
-      end
-      final_data.sort! { |a, b| b[:average] <=> a[:average] }
-      final_data.each do |record|
-        [:min, :max, :average].each { |k| record[k] = to_ms(record[k]) }
-      end
-      final_data
-    end
-  end
-
-  def to_ms(seconds)
-    "%.3f ms" % (seconds * 1000)
+require 'method_profiler/profiler'
+
+# {MethodProfiler} collects performance information about the methods
+# in your objects and creates reports to help you identify slow methods.
+#
+module MethodProfiler
+  # Create a new {MethodProfiler::Profiler} which will observe all method calls
+  # on the given object. This is a convenience method and has the same effect
+  # as {MethodProfiler::Profiler#initialize}.
+  #
+  # @param [Object] obj The object to observe.
+  # @return [MethodProfiler::Profiler] A new profiler.
+  #
+  def self.observe(obj)
+    Profiler.new(obj)
   end
 end

data/lib/method_profiler/hirb.rb

@@ -0,0 +1,14 @@
+require 'hirb'
+
+# All methods in this module can be used as filters in Hirb.
+#
+module Hirb::Helpers::Table::Filters
+  # Converts seconds to milliseconds. Used to format times in
+  # the output of {MethodProfiler::Report}.
+  #
+  # @param [Float] seconds The duration to convert.
+  # @return [String] The duration in milliseconds with units displayed. Rounded to 3 decimal places.
+  def to_milliseconds(seconds)
+    "%.3f ms" % (seconds * 1000)
+  end
+end

data/lib/method_profiler/profiler.rb

@@ -0,0 +1,105 @@
+require 'method_profiler/report'
+
+require 'benchmark'
+
+module MethodProfiler
+  # Observes an object, keeping track of all its method calls and the wall clock
+  # time spent executing them.
+  #
+  class Profiler
+    # Initializes a new {Profiler}. Wraps all methods in the object and its singleton
+    # class with profiling code.
+    #
+    # @param [Object] obj The object to observe.
+    #
+    def initialize(obj)
+      @obj = obj
+      @data = Hash.new { |h, k| h[k] = [] }
+
+      wrap_methods_with_profiling
+    end
+
+    # Generates a report object with all the data collected so far bay the profiler. This report
+    # can be displayed in various ways. See {Report}.
+    #
+    # @return [Report] A new report with all the data the profiler has collected.
+    #
+    def report
+      Report.new(final_data)
+    end
+
+    private
+
+    def wrap_methods_with_profiling
+      profiler = self
+      singleton_methods_to_wrap = find_singleton_methods
+      instance_methods_to_wrap = find_instance_methods
+
+      @obj.singleton_class.module_eval do
+        singleton_methods_to_wrap.each do |method|
+          define_method("#{method}_with_profiling") do |*args|
+            profiler.send(:profile, method, true) { send("#{method}_without_profiling", *args) }
+          end
+
+          alias_method "#{method}_without_profiling", method
+          alias_method method, "#{method}_with_profiling"
+        end
+      end
+
+      @obj.module_eval do
+        instance_methods_to_wrap.each do |method|
+          define_method("#{method}_with_profiling") do |*args|
+            profiler.send(:profile, method) { send("#{method}_without_profiling", *args) }
+          end
+
+          alias_method "#{method}_without_profiling", method
+          alias_method method, "#{method}_with_profiling"
+        end
+      end
+    end
+
+    def find_singleton_methods
+      @obj.singleton_class.instance_methods - @obj.singleton_class.ancestors.map do |a|
+        a == @obj ? [] : a.instance_methods
+      end.flatten
+    end
+
+    def find_instance_methods
+      @obj.instance_methods - @obj.ancestors.map do |a|
+        a == @obj ? [] : a.instance_methods
+      end.flatten
+    end
+
+    def profile(method, singleton = false, &block)
+      method_name = singleton ? ".#{method}" : "##{method}"
+      result = nil
+      elapsed_time = benchmark(result, &block).to_s.match(/\(\s*([^\)]+)\)/)[1].to_f
+      @data[method_name] << elapsed_time
+      result
+    end
+
+    def final_data
+      results = []
+
+      @data.each do |method, records|
+        total_calls = records.size
+        average = records.reduce(:+) / total_calls
+        results << {
+          method: method,
+          min: records.min,
+          max: records.max,
+          average: average,
+          total_calls: total_calls
+        }
+      end
+
+      results
+    end
+
+    private
+
+    def benchmark(result, &block)
+      Benchmark.measure { result = block.call }
+    end
+  end
+end

data/lib/method_profiler/report.rb

@@ -0,0 +1,89 @@
+require 'hirb'
+require 'method_profiler/hirb'
+
+module MethodProfiler
+  # Sorts and displays data collected by a {Profiler}.
+  #
+  class Report
+    # Fields that can be passed to {#sort_by}.
+    FIELDS = [:method, :min, :max, :average, :total_calls]
+
+    # Directions that can be passed to {#order}.
+    DIRECTIONS = [:asc, :ascending, :desc, :descending]
+
+    # Initializes a new {Report}. Used to sort and display data collected by a {Profiler}.
+    #
+    # @param [Array] data Data collected by a {Profiler}.
+    #
+    def initialize(data)
+      @data = data
+      @sort_by = :average
+      @order = :descending
+    end
+
+    # Sorts the report by the given field. Defaults to `:average`. Chainable with {#order}.
+    #
+    # @param [Symbol, String] field Any field from {FIELDS} to sort by.
+    # @return [Report] The {Report} object, suitable for chaining or display.
+    #
+    def sort_by(field)
+      field = field.to_sym
+      field = :average unless FIELDS.include?(field)
+      @sort_by = field
+      self
+    end
+
+    # Changes the direction of the sort. Defaults to `:descending`. Chainable with {#sort_by}.
+    #
+    # @param [Symbol, String] direction Any direction from {DIRECTIONS} to direct the sort.
+    # @return [Report] The {Report} object, suitable for chaining or display.
+    #
+    def order(direction)
+      direction = direction.to_sym
+      direction = :descending unless DIRECTIONS.include?(direction)
+      direction = :descending if direction == :desc
+      direction = :ascending if direction == :asc
+      @order = direction
+      self
+    end
+
+    # Sorts the data by the currently set criteria and returns an array of profiling results.
+    #
+    # @return [Array] An array of profiling results.
+    #
+    def to_a
+      if @order == :ascending
+        @data.sort { |a, b| a[@sort_by] <=> b[@sort_by] }
+      else
+        @data.sort { |a, b| b[@sort_by] <=> a[@sort_by] }
+      end
+    end
+
+    # Sorts the data by the currently set criteria and returns a pretty printed table as a string.
+    #
+    # @return [String] A table of profiling results.
+    #
+    def to_s
+      [
+        "MethodProfiler results for: #{@obj}",
+        Hirb::Helpers::Table.render(
+          to_a,
+          headers: {
+            method: "Method",
+            min: "Min Time",
+            max: "Max Time",
+            average: "Average Time",
+            total_calls: "Total Calls"
+          },
+          fields: [:method, :min, :max, :average, :total_calls],
+          filters: {
+            min: :to_milliseconds,
+            max: :to_milliseconds,
+            average: :to_milliseconds
+          },
+          description: false
+        )
+      ].join("\n")
+    end
+  end
+end

data/method_profiler.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = "method_profiler"
-  s.version     = "0.1.0"
+  s.version     = "1.0.0"
   s.authors     = ["Jimmy Cuadra"]
   s.email       = ["jimmy@jimmycuadra.com"]
   s.homepage    = "https://github.com/change/method_profiler"
@@ -16,4 +16,5 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency "hirb", ">= 0.6.0"
   s.add_development_dependency "rspec"
+  s.add_development_dependency "simplecov"
 end

data/spec/method_profiler/profiler_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe MethodProfiler::Profiler do
+  let!(:profiler) { described_class.new(Petition) }
+  let(:petition) { Petition.new }
+
+  it "creates wrapper methods for the object's methods" do
+    petition.should respond_to(:foo)
+    petition.should respond_to(:foo_with_profiling)
+    petition.should respond_to(:foo_without_profiling)
+    petition.should_not respond_to(:foo_with_profiling_with_profiling)
+  end
+
+  describe "#report" do
+    it "returns a new Report object" do
+      profiler.report.should be_an_instance_of MethodProfiler::Report
+    end
+  end
+end

data/spec/method_profiler/report_spec.rb

@@ -0,0 +1,91 @@
+require 'spec_helper'
+
+describe MethodProfiler::Report do
+  before do
+    profiler = MethodProfiler::Profiler.new(Petition)
+
+    # Fake the timings for testing purposes
+    profiler.stub(:benchmark) do |result, block|
+      result = block.call
+      "(#{rand})"
+    end
+
+    petition = Petition.new
+
+    [:hay, :hay, :guys].each { |m| petition.class.send(m) }
+    [:foo, :bar, :baz].each { |m| petition.send(m) }
+
+    @report = profiler.report
+  end
+
+  describe "#to_a" do
+    it "returns an array of records" do
+      results = @report.to_a
+      results.should be_an Array
+      results.size.should == 5
+    end
+
+    it "sorts by average time (descending) by default" do
+      results = @report.to_a
+      average_times = results.map { |r| r[:average] }
+      average_times.should == average_times.sort.reverse
+    end
+
+    it "sorts by another type if it's been changed" do
+      results = @report.sort_by(:min).to_a
+      min_times = results.map { |r| r[:min] }
+      min_times.should == min_times.sort.reverse
+    end
+
+    it "sorts in a different direction if it's been changed" do
+      results = @report.order(:ascending).to_a
+      average_times = results.map { |r| r[:average] }
+      average_times.should == average_times.sort
+    end
+  end
+
+  describe "#sort_by" do
+    it "sets the sort type" do
+      @report.sort_by(:total_calls)
+      @report.instance_variable_get("@sort_by").should == :total_calls
+    end
+
+    it "defaults to average if an invalid sort type is passed" do
+      @report.sort_by(:foo)
+      @report.instance_variable_get("@sort_by").should == :average
+    end
+  end
+
+  describe "#order" do
+    it "sets the sort direction" do
+      @report.order(:ascending)
+      @report.instance_variable_get("@order").should == :ascending
+    end
+
+    it "defaults to descending if an invalid direction is passed" do
+      @report.order(:foo)
+      @report.instance_variable_get("@order").should == :descending
+    end
+
+    it "allows normalizes :asc and :desc aliases" do
+      @report.order(:asc)
+      @report.instance_variable_get("@order").should == :ascending
+
+      @report.order(:desc)
+      @report.instance_variable_get("@order").should == :descending
+    end
+  end
+
+  describe "#to_s" do
+    it "outputs one line for each method that was called" do
+      output = @report.to_s
+
+      output.should be_a String
+      output.scan(/\.hay/).size.should == 1
+      output.scan(/\.guys/).size.should == 1
+      output.scan(/#foo/).size.should == 1
+      output.scan(/#bar/).size.should == 1
+      output.scan(/#baz/).size.should == 1
+    end
+  end
+end

data/spec/method_profiler_spec.rb

@@ -1,60 +1,9 @@
 require 'spec_helper'
 
-profiler = MethodProfiler.new(Petition)
-
 describe MethodProfiler do
-  before { @petition = Petition.new }
-  after { profiler.reset! }
-
-  it "can be instantiated with an object to observe" do
-    profiler.should be_true
-  end
-
-  it "finds all the object's instance methods" do
-    profiler.observed_methods.sort.should == [:foo, :bar, :baz].sort
-  end
-
-  it "creates wrapper methods for each method in the object" do
-    @petition.should respond_to(:foo)
-    @petition.should respond_to(:foo_with_profiling)
-    @petition.should respond_to(:foo_without_profiling)
-    @petition.should_not respond_to(:foo_with_profiling_with_profiling)
-  end
-
-  describe "#profile" do
-    it "adds a new record for the method call" do
-      @petition.foo
-      profiler.data[:foo].size.should == 1
-    end
-
-    it "calls the real method" do
-      @petition.should_receive(:foo_without_profiling)
-      @petition.foo
-    end
-
-    it "returns the value of the real method" do
-      @petition.baz.should == "blah"
-    end
-  end
-
-  describe "#report" do
-    it "outputs a string of report data" do
-      profiler.report.should be_an_instance_of(String)
-    end
-
-    it "outputs one line for each method that was called" do
-      @petition.foo
-      @petition.bar
-      @petition.baz
-      profiler.report.scan(/foo/).size.should == 1
-      profiler.report.scan(/bar/).size.should == 1
-      profiler.report.scan(/baz/).size.should == 1
-    end
-
-    it "combines multiple calls to the same method into one line" do
-      @petition.foo
-      @petition.foo
-      profiler.report.scan(/foo/).size.should == 1
+  describe ".observe" do
+    it "returns a new Profiler instance" do
+      described_class.observe(Petition).should be_an_instance_of described_class::Profiler
     end
   end
 end

data/spec/spec_helper.rb

@@ -1,8 +1,13 @@
+require "simplecov"
+SimpleCov.start
+
 $:.unshift(File.expand_path("../../lib", __FILE__))
 require "method_profiler"
 
-class Petition
-  def foo; end
-  def bar; end
-  def baz; "blah"; end
+RSpec.configure do |config|
+  config.around do |example|
+    load File.expand_path("../support/petition.rb", __FILE__)
+    example.call
+    Object.send(:remove_const, :Petition)
+  end
 end

data/spec/support/petition.rb

@@ -0,0 +1,18 @@
+class Petition
+  def self.hay
+  end
+
+  def self.guys
+    "sup"
+  end
+
+  def foo
+  end
+
+  def bar
+  end
+
+  def baz
+    "blah"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: method_profiler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-02 00:00:00.000000000 Z
+date: 2012-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb
-  requirement: &70179117063300 !ruby/object:Gem::Requirement
+  requirement: &70181816945620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 0.6.0
   type: :runtime
   prerelease: false
-  version_requirements: *70179117063300
+  version_requirements: *70181816945620
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70179117084460 !ruby/object:Gem::Requirement
+  requirement: &70181816945220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70179117084460
+  version_requirements: *70181816945220
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &70181816944760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70181816944760
 description: MethodProfiler observes your code and generates reports about the methods
   that were run and how long they took.
 email:
@@ -47,9 +58,15 @@ files:
 - README.md
 - Rakefile
 - lib/method_profiler.rb
+- lib/method_profiler/hirb.rb
+- lib/method_profiler/profiler.rb
+- lib/method_profiler/report.rb
 - method_profiler.gemspec
+- spec/method_profiler/profiler_spec.rb
+- spec/method_profiler/report_spec.rb
 - spec/method_profiler_spec.rb
 - spec/spec_helper.rb
+- spec/support/petition.rb
 homepage: https://github.com/change/method_profiler
 licenses: []
 post_install_message: 
@@ -75,5 +92,9 @@ signing_key:
 specification_version: 3
 summary: Find slow methods in your program.
 test_files:
+- spec/method_profiler/profiler_spec.rb
+- spec/method_profiler/report_spec.rb
 - spec/method_profiler_spec.rb
 - spec/spec_helper.rb
+- spec/support/petition.rb
+has_rdoc: