time_up 0.0.3 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b040cfa422a59cc1c7f2157e8f7261ed1bdc7c470da76fead75b026159f02c8
-  data.tar.gz: 4b817578713714392dd0ab8f2694bce78c6ddf93e9b5eea16f302a5d4549c559
+  metadata.gz: c18c0412768d6e182c94ef02f66e630508f5c959f433d1d1ecf322ce16107c3a
+  data.tar.gz: c18ce6ae92e02cd52ddad357d8f542185869d8e6fa5cebf090ee3bc4b576a44c
 SHA512:
-  metadata.gz: 3b4fe6bff25861a0b9b76b95684e25eed9056886091556f22b70820251ea3f41b08879b2628dd8b8bee74e03720b0f39d7af87af5664c0bcaa152f7e8b88d329
-  data.tar.gz: e0b0953129fc39ed079d3b6addebf579d8defbebcda484649a9826ff0a3e3b2383360d7d8269572746b5f5469cb076d4e6fa770ed36735f1c2fe55f319c91c5b
+  metadata.gz: 8a73b80a2193a5df7ce3bae010b109c3e5c34de5329ca34c75cc6d7b296aae395c81ed1488a64e932069c7da8a496ea175d81f6ae4defe214445760c98a01551
+  data.tar.gz: 610cc5554be65e278b2187c56e0d2ebc382b5c916a2e666c39ba84da9ede77bc618ff3c4d58d2df22030bf9a8ad049cbd3eb45827bd0a7c7419e46d8166035f4

data/.standard.yml

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

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# 0.0.6
+
+- Add `TimeUp.all_timers`. It's weird that it's not a thing.
+
+# 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

data/Gemfile.lock

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

data/README.md

@@ -11,6 +11,9 @@ 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
 
 Just run `gem install time_up` or add time_up to your Gemfile:
@@ -107,7 +110,7 @@ TimeUp.print_summary
 Which will output something like:
 
 ```
-TimeUp timers summary
+TimeUp summary
 ========================
 :roast   	0.07267s
 :veggies 	0.03760s
@@ -117,10 +120,27 @@ 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
 
@@ -128,51 +148,60 @@ straightforward, so I'd encourage you to [read the code](/lib/time_up.rb).
 if it doesn't exist)
 
 `TimeUp.start(name, [&blk])` - Starts (or restarts) a named
-[Timer](#timeuptimer-class). If passed with a block, will return whatever the
-block evaluates to. If passed without a block, it will return the timer object
+[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. Raises if the timer isn't defined.
+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.timings(name)` - Returns an array of each recorded start-to-stop
-duration of the timer (including the current one, if active)
+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.count(name)` - The number of times the timer has been started and
-stopped (including the current timing, if active)
+`TimeUp.max(name)` - The longest recording by the timer
 
-`TimeUp.min(name)` - The shortest recording of the timer (including the current
-one, if active)
+`TimeUp.mean(name)` - The arithmetic mean of all recordings by the timer
 
-`TimeUp.max(name)` - The longest recording of the timer (including the current
-one, if active)
+`TimeUp.median(name)` - The median of all recordings by the timer
 
-`TimeUp.mean(name)` - The arithmetic mean of all recorded durations of the timer
+`TimeUp.percentile(name, percent)` - The timing for the given
+[percentile](https://en.wikipedia.org/wiki/Percentile) of all recordings by the
+timer
 
-`TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` for all the
-timers you've created
+`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 snapshot of the state of things at a
-particular point in time without stopping all your timers
+`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 time, number of recordings, min, max,
-and mean)
+`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 counting the same time in
-multiple places simultaneously
+`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 to standard output (or the provided
+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
 
 `TimeUp.reset_all` - Resets all timers
@@ -188,20 +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 active)
+`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 (including
-the current timing, if active)
+`count` - The number of times the timer has been started and stopped
 
-`min` - The shortest recording of the timer (including the current one, if
-active)
+`min` - The shortest recording of the timer
 
-`max` - The longest recording of the timer (including the current one, if
-active)
+`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

@@ -22,7 +22,8 @@ module TimeUp
     :count,
     :min,
     :max,
-    :mean
+    :mean,
+    :median
   ].each do |method_name|
     define_singleton_method method_name do |name|
       __ensure_timer(name)
@@ -30,6 +31,11 @@ module TimeUp
     end
   end
 
+  def self.percentile(name, percentage)
+    __ensure_timer(name)
+    __timers[name].percentile(percentage)
+  end
+
   # Interrogative methods
   def self.total_elapsed
     __timers.values.sum(&:elapsed)
@@ -41,6 +47,10 @@ module TimeUp
     }.to_h
   end
 
+  def self.all_timers
+    __timers.values
+  end
+
   def self.all_stats
     __timers.values.map { |timer|
       [timer.name, {
@@ -48,7 +58,9 @@ module TimeUp
         count: timer.count,
         min: timer.min,
         max: timer.max,
-        mean: timer.mean
+        mean: timer.mean,
+        median: timer.median,
+        "95th": timer.percentile(95)
       }]
     }.to_h
   end
@@ -65,7 +77,7 @@ module TimeUp
     }
     io.puts <<~SUMMARY
 
-      TimeUp timers summary
+      TimeUp summary
       ========================
       #{summaries.join("\n")}
 
@@ -73,6 +85,56 @@ module TimeUp
     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)
@@ -89,7 +151,7 @@ module TimeUp
 
   # Internal methods
   def self.__timers
-    Thread.current[:time_up_timers]
+    Thread.current[:time_up_timers] ||= {}
   end
 
   def self.__ensure_timer(name)
@@ -165,6 +227,25 @@ module TimeUp
       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]

data/lib/time_up/version.rb

@@ -1,3 +1,3 @@
 module TimeUp
-  VERSION = "0.0.3"
+  VERSION = "0.0.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_up
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.7
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-17 00:00:00.000000000 Z
+date: 2021-07-24 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