time_up 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2814efda7871308dcafe0196407a3bbea424770069d9b998c8728f974a641413
-  data.tar.gz: 791e65a388e0d62ece0166a747a20cd41f37259d6283e197ff020a05b6eb3e70
+  metadata.gz: f6241f3e0e1e66bc75c67a7e7cfc76424ae4e711c5a535b87da3bdf4fa78c153
+  data.tar.gz: 33c77eb409cb4d4d4142207ff93a938a1124b87768047f29be0d51057c4eb5fb
 SHA512:
-  metadata.gz: a697b5da2199813b882d8a1b3994670dde64c8ce5adb95b321a8bef3c8892cda9110e778c505e0fd4c327f1956f474be07db9f5fc008926093af9c60c4a8accf
-  data.tar.gz: 1b7089abf119e10a4cff97f880d9a05536a960b112ba59a57f6c6d8642771e566b697db88f6d7c7e2fdca73ff0549803864314de7601d0643e0c018cfbc3731e
+  metadata.gz: df9e90669ceef219dcea0bf8b21548252b97abe40b950b922f6c9ee17987494d145fdd130b5c4735a6e57daffaf5ba2d915057044f424ba68656d9b55b5f7820
+  data.tar.gz: ad014a9ec0471bfbc3f315b673988d7d5b5115ad29d0cc664ad63eaa81547086bff539de50e311078261c99a9616a0e683c75f9e552bf0a254d26e14d0ef702d

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 2.4

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.0.5
+
+- Add `median` and `percentile` timer statistics, and added them to
+  `print_detailed_summary`
+
+# 0.0.4
+
+- Add `TimeUp.print_detailed_summary`
+
+# 0.0.3
+
+- Change the return value of TimeUp.start when passed a block to be the
+  evaluated value of the block (for easier insertion into existing code without
+  adding a bunch of new assignment and returns)
+- Allow timer instances' `start` method to be called with a block
+- Add `timings`, `count`, `min`, `max`, and `mean` methods for basic stats
+  tracking
+- Add `TimeUp.all_stats` to roll up all these
+
+# 0.0.2
+
+- Switch from a module method to Thread.current variable
+
 # 0.0.1
 
 - Make the gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    time_up (0.0.1)
+    time_up (0.0.5)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,10 +6,13 @@ but don't necessarily want to reach for
 Try `time_up`!
 
 This gem is especially useful for long-running processes (like test suites) that
-have several time-intensive operations that are repeated over time and that you
-want to measure and aggregate. (For example, to see how much time your
-test suite spends creating factories, truncating the database, or invoking a
-critical code path.)
+have several time-intensive operations that are repeated over the life of the
+process and that you want to measure in aggregate. (For example, to see how
+much time your test suite spends creating factories, truncating the database, or
+invoking a critical code path.)
+
+Here's a [blog post about time_up](https://blog.testdouble.com/posts/2021-07-19-benchmarking-your-ruby-with-time_up/) and 
+a [great example of when it can be useful](https://gist.github.com/searls/feee0b0eac7c329b390fed90c4714afb).
 
 ## Install
 
@@ -65,10 +68,10 @@ sleep 5
 puts TimeUp.stop :eggs # => ~5.0
 ```
 
-`TimeUp.start` also returns an instance of the named timer, which has its own
-`start`, `stop`, `elaped`, and `reset` methods. If you want to find that
-instance later, you can also call `TimeUp.timer(:some_name)`. So the above
-example could be rewritten as:
+When passes without a block, `TimeUp.start` returns an instance of the timer,
+which has its own `start`, `stop`, `elaped`, and `reset` methods. If you want to
+find that instance later, you can also call `TimeUp.timer(:some_name)`. So the
+above example could be rewritten as:
 
 ```ruby
 egg_timer = TimeUp.start :eggs
@@ -107,7 +110,7 @@ TimeUp.print_summary
 Which will output something like:
 
 ```
-TimeUp timers summary
+TimeUp summary
 ========================
 :roast   	0.07267s
 :veggies 	0.03760s
@@ -117,39 +120,87 @@ TimeUp timers summary
 * Denotes that the timer is still active
 ```
 
+And if you're calling the timers multiple times and want to see some basic
+statistics in the print-out, you can call `TimeUp.print_detailed_summary`, which
+will produce this:
+
+```
+=============================================================================
+  Name    | Elapsed | Count |   Min   |   Max   |  Mean   | Median  | 95th %
+-----------------------------------------------------------------------------
+:roast    | 0.08454 | 3     | 0.00128 | 0.07280 | 0.02818 | 0.01046 | 0.06657
+:veggies  | 0.03779 | 1     | 0.03779 | 0.03779 | 0.03779 | 0.03779 | 0.03779
+:pasta    | 0.01260 | 11    | 0.00000 | 0.01258 | 0.00115 | 0.00000 | 0.00630
+:souffle* | 0.00024 | 1     | 0.00024 | 0.00025 | 0.00025 | 0.00025 | 0.00026
+
+* Denotes that the timer is still active
+```
+
 ## API
 
 This gem defines a bunch of public methods but they're all pretty short and
-straightforward, so I'd encourage you to [read the code](/lib/time_up.rb).
+straightforward, so when in doubt, I'd encourage you to [read the
+code](/lib/time_up.rb).
 
 ### `TimeUp` module
 
-`TimeUp.start(name, [&blk])` - Starts (or restarts) and returns a named `Timer`
+`TimeUp.timer(name)` - Returns the `Timer` instance named `name` (creating it,
+if it doesn't exist)
 
-`TimeUp.timer(name)` - Returns any a `Timer` instance named `name` or `nil`
+`TimeUp.start(name, [&blk])` - Starts (or restarts) a named
+[Timer](#timeuptimer-class). If passed a block, will return whatever the block
+evaluates to. If called without a block, it will return the timer object
 
-`TimeUp.stop(name)` - Stops the named timer or raises if it's not defined
+`TimeUp.stop(name)` - Stops the named timer
+
+`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
+restarting it if it's currently running
 
 `TimeUp.elapsed(name)` - Returns a `Float` of the total elapsed seconds that the
-named timer has been running (and raises if no timer is defined with the given
-`name`)
+named timer has been running
 
-`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
-restarting it if it's currently running. Raises if the timer isn't defined.
+`TimeUp.timings(name)` - Returns an array of each recorded start-to-stop
+duration (including the current one, if the timer is running) of the named timer
+
+`TimeUp.count(name)` - The number of times the timer has been started (including
+the current timing, if the timer is running)
+
+`TimeUp.min(name)` - The shortest recording by the timer
+
+`TimeUp.max(name)` - The longest recording by the timer
 
-`TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` for all the
-timers you've created
+`TimeUp.mean(name)` - The arithmetic mean of all recordings by the timer
 
-`TimeUp.all_elapsed` - Returns a hash of timer name keys mapped to their
-`elapsed` values. Handy for grabbing a snapshot of the state of things at a
-particular point in time without stopping all your timers
+`TimeUp.median(name)` - The median of all recordings by the timer
 
-`TimeUp.active_timers` - Returns an array of all timers that are currently
-running. Useful for detecting cases where you might be counting the same time in
-multiple places simultaneously
+`TimeUp.percentile(name, percent)` - The timing for the given
+[percentile](https://en.wikipedia.org/wiki/Percentile) of all recordings by the
+timer
 
-`TimeUp.print_summary([IO])` - Pretty-prints a multi-line summary of all your
-timers to STDOUT (or the provided IO)
+`TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` across all
+the timers you've created (note that because you can easily run multiple logical
+timers simultaneously, this figure may exceed the total time spent by the
+computer)
+
+`TimeUp.all_elapsed` - Returns a Hash of timer name keys mapped to their
+`elapsed` values. Handy for grabbing a reference to a snapshot of the state of
+things without requiring you to stop your timers
+
+`TimeUp.all_stats` - Returns a Hash of timer name keys mapped to another
+hash of their basic statistics (`elapsed`, `count`, `min`, `max`,
+and `mean`)
+
+`TimeUp.active_timers` - Returns an Array of all timers that are currently
+running. Useful for detecting cases where you might be keeping time in multiple
+places simultaneously
+
+`TimeUp.print_summary([io])` - Pretty-prints a multi-line summary of all your
+timers' total elapsed times to standard output (or the provided
+[IO](https://ruby-doc.org/core-3.0.1/IO.html))
+
+`TimeUp.print_detailed_summary([io])` - Pretty-prints a multi-line summary of
+all your timers' elapsed times and basic statistics to standard output (or the
+provided [IO](https://ruby-doc.org/core-3.0.1/IO.html))
 
 `TimeUp.stop_all` - Stops all timers
 
@@ -166,6 +217,23 @@ reference to them
 
 `elapsed` - A `Float` of the total elapsed seconds the timer has been running
 
+`timings` - Returns an Array of each recorded start-to-stop duration of the
+timer (including the current one, if the timer is running)
+
+`count` - The number of times the timer has been started and stopped
+
+`min` - The shortest recording of the timer
+
+`max` - The longest recording of the timer
+
+`mean` - The arithmetic mean of all recorded durations of the timer
+
+`median(name)` - The median of all recordings by the timer
+
+`percentile(name, percent)` - The timing for the given
+[percentile](https://en.wikipedia.org/wiki/Percentile) of all recordings by the
+timer
+
 `active?` - Returns `true` if the timer is running
 
 `reset(force: false)` - Resets the timer to 0 elapsed seconds. If `force` is

data/lib/time_up.rb

@@ -3,132 +3,265 @@ require_relative "time_up/version"
 module TimeUp
   class Error < StandardError; end
 
-  @timers = {}
-  def self.start(name, &blk)
-    raise Error.new("Timer name must be a String or Symbol") unless name.is_a?(Symbol) || name.is_a?(String)
-    timer = @timers[name] ||= Timer.new(name)
-    timer.start
-    if blk
-      blk.call
-      timer.stop
-    end
-    timer
-  end
+  Thread.current[:time_up_timers] = {}
 
-  # Delegate methods
   def self.timer(name)
-    @timers[name]
+    __timers[name] ||= Timer.new(name)
   end
 
-  def self.stop(name)
-    __ensure_timer(name)
-    @timers[name].stop
+  # Delegate methods
+  def self.start(name, &blk)
+    timer(name).start(&blk)
   end
 
-  def self.elapsed(name)
-    __ensure_timer(name)
-    @timers[name].elapsed
+  [
+    :stop,
+    :reset,
+    :elapsed,
+    :timings,
+    :count,
+    :min,
+    :max,
+    :mean,
+    :median
+  ].each do |method_name|
+    define_singleton_method method_name do |name|
+      __ensure_timer(name)
+      __timers[name].send(method_name)
+    end
   end
 
-  def self.reset(name)
+  def self.percentile(name, percentage)
     __ensure_timer(name)
-    @timers[name].reset
+    __timers[name].percentile(percentage)
   end
 
   # Interrogative methods
   def self.total_elapsed
-    @timers.values.sum(&:elapsed)
+    __timers.values.sum(&:elapsed)
   end
 
   def self.all_elapsed
-    @timers.values.map { |timer|
+    __timers.values.map { |timer|
       [timer.name, timer.elapsed]
     }.to_h
   end
 
+  def self.all_stats
+    __timers.values.map { |timer|
+      [timer.name, {
+        elapsed: timer.elapsed,
+        count: timer.count,
+        min: timer.min,
+        max: timer.max,
+        mean: timer.mean,
+        median: timer.median,
+        "95th": timer.percentile(95)
+      }]
+    }.to_h
+  end
+
   def self.active_timers
-    @timers.values.select(&:active?)
+    __timers.values.select(&:active?)
   end
 
   def self.print_summary(io = $stdout)
-    longest_name_length = @timers.values.map { |t| t.name.inspect.size }.max
-    summaries = @timers.values.map { |timer|
+    longest_name_length = __timers.values.map { |t| t.name.inspect.size }.max
+    summaries = __timers.values.map { |timer|
       name = "#{timer.name.inspect}#{"*" if timer.active?}".ljust(longest_name_length + 1)
       "#{name}\t#{"%.5f" % timer.elapsed}s"
     }
     io.puts <<~SUMMARY
 
-      TimeUp timers summary
+      TimeUp summary
       ========================
       #{summaries.join("\n")}
 
-      #{"* Denotes that the timer is still active\n" if @timers.values.any?(&:active?)}
+      #{"* Denotes that the timer is still active\n" if __timers.values.any?(&:active?)}
+    SUMMARY
+  end
+
+  def self.print_detailed_summary(io = $stdout)
+    cols = {
+      names: ["Name"],
+      elapsed: ["Elapsed"],
+      count: ["Count"],
+      min: ["Min"],
+      max: ["Max"],
+      mean: ["Mean"],
+      median: ["Median"],
+      "95th": ["95th %"]
+    }
+    __timers.values.each { |timer|
+      cols[:names] << "#{timer.name.inspect}#{"*" if timer.active?}"
+      cols[:elapsed] << "%.5f" % timer.elapsed
+      cols[:count] << timer.count.to_s
+      cols[:min] << "%.5f" % timer.min
+      cols[:max] << "%.5f" % timer.max
+      cols[:mean] << "%.5f" % timer.mean
+      cols[:median] << "%.5f" % timer.median
+      cols[:"95th"] << "%.5f" % timer.percentile(95)
+    }
+
+    widths = cols.map { |name, vals|
+      [name, vals.map(&:length).max]
+    }.to_h
+
+    rows = cols[:names].size.times.map { |i|
+      if i == 0
+        cols.keys.map { |name|
+          cols[name][i].center(widths[name])
+        }
+      else
+        cols.keys.map { |name|
+          cols[name][i].ljust(widths[name])
+        }
+      end
+    }
+
+    full_width = widths.values.sum + (rows[0].size - 1) * 3
+    io.puts <<~SUMMARY
+
+      #{"=" * full_width}
+      #{rows[0].join(" | ")}
+      #{"-" * full_width}
+      #{rows[1..-1].map { |row| row.join(" | ") }.join("\n")}
+
+      #{"* Denotes that the timer is still active\n" if __timers.values.any?(&:active?)}
     SUMMARY
   end
 
   # Iterative methods
   def self.stop_all
-    @timers.values.each(&:stop)
+    __timers.values.each(&:stop)
   end
 
   def self.reset_all
-    @timers.values.each(&:reset)
+    __timers.values.each(&:reset)
   end
 
   def self.delete_all
-    @timers.values.each { |t| t.reset(force: true) }
-    @timers = {}
+    __timers.values.each { |t| t.reset(force: true) }
+    Thread.current[:time_up_timers] = {}
   end
 
   # Internal methods
+  def self.__timers
+    Thread.current[:time_up_timers]
+  end
+
   def self.__ensure_timer(name)
-    raise Error.new("No timer named #{name.inspect}") unless @timers[name]
+    raise Error.new("No timer named #{name.inspect}") unless __timers[name]
   end
 
   class Timer
     attr_reader :name
 
     def initialize(name)
+      validate!(name)
       @name = name
       @start_time = nil
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
     end
 
-    def start
+    def start(&blk)
       @start_time ||= now
+      if blk
+        blk.call.tap do
+          stop
+        end
+      else
+        self
+      end
     end
 
     def stop
       if @start_time
-        @elapsed += now - @start_time
+        duration = now - @start_time
+        @past_timings.push(duration)
+        @total_elapsed += duration
+
         @start_time = nil
       end
-      @elapsed
+      @total_elapsed
     end
 
     def elapsed
       if active?
-        @elapsed + (now - @start_time)
+        @total_elapsed + (now - @start_time)
       else
-        @elapsed
+        @total_elapsed
       end
     end
 
-    def active?
-      !!@start_time
-    end
-
     def reset(force: false)
       if force
         @start_time = nil
       elsif !@start_time.nil?
         @start_time = now
       end
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
+    end
+
+    def count
+      timings.size
+    end
+
+    def min
+      timings.min
+    end
+
+    def max
+      timings.max
+    end
+
+    def mean
+      times = timings
+      return if times.empty?
+      times.sum / times.size
+    end
+
+    def median
+      times = timings.sort
+      return if times.empty?
+      (times[(times.size - 1) / 2] + times[times.size / 2]) / 2.0
+    end
+
+    def percentile(percent)
+      times = timings.sort
+      return if times.empty?
+      return 0 if percent <= 0
+      return max if percent >= 100
+      return times.first if times.size == 1
+      position = (percent / 100.0) * (times.size - 1)
+
+      partial_ratio = position - position.floor
+      whole, partial = times[position.floor, 2]
+      whole + (partial - whole) * partial_ratio
+    end
+
+    def timings
+      if active?
+        @past_timings + [now - @start_time]
+      else
+        @past_timings
+      end
+    end
+
+    def active?
+      !!@start_time
     end
 
     private
 
+    def validate!(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise Error.new("Timer name must be a String or Symbol")
+      end
+    end
+
     def now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/time_up/version.rb

@@ -1,3 +1,3 @@
 module TimeUp
-  VERSION = "0.0.1"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_up
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.5
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-15 00:00:00.000000000 Z
+date: 2021-07-20 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
+- ".standard.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock