time_up
Ever need to measure the elapsed wall-time for one or more bits of Ruby code,
but don't necessarily want to reach for
Benchmark or roll your own ad hoc measurement code?
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 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 and a great example of when it can be useful.
Install
Just run gem install time_up
or add time_up to your Gemfile:
gem "time_up"
Usage
Starting a timer is easy! Just call TimeUp.start
:
# Pass a block and time_up will only count the time while the block executes:
TimeUp.start(:factories) do
# … create some factories
end
# Without a block, a started timer will run until you stop it:
TimeUp.start(:truncation)
# … truncate some stuff
TimeUp.stop(:truncation)
To get the total time that's elapsed while the timer has been running, call
elapsed
:
slow_time = TimeUp.elapsed(:slow_code_path)
Which will return a Float
representing the number of seconds that have elapsed
while the timer is running.
Timers aggregate total elapsed time running, just like a digital stopwatch. That means if you start a timer after it's been stopped, the additional time will be added to the previous elapsed time:
TimeUp.start :eggs
sleep 1
puts TimeUp.stop :eggs # => ~1.0
TimeUp.start :eggs
sleep 1
# To get the elapsed time without necessarily stopping the timer, call `elapsed`
puts TimeUp.elapsed :eggs # => ~2.0
# To reset a timer to 0, call `reset` (if it's running, it'll keep running!)
TimeUp.reset :eggs
sleep 5
puts TimeUp.stop :eggs # => ~5.0
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:
egg_timer = TimeUp.start :eggs
sleep 1
puts egg_timer.stop # => ~1.0
egg_timer.start
sleep 1
# To get the elapsed time without necessarily stopping the timer, call `elapsed`
puts egg_timer.elapsed # => ~2.0
# To reset a timer to 0, call `reset` (if it's running, it'll keep running!)
egg_timer.reset
sleep 5
puts egg_timer.stop # => ~5.0
Finally, if you're juggling a bunch of timers, you can get a summary report of them printed for you, like so:
TimeUp.start :roast
sleep 0.03
TimeUp.start :veggies
sleep 0.02
TimeUp.start :pasta
sleep 0.01
TimeUp.stop_all
TimeUp.start :souffle
TimeUp.print_summary
Which will output something like:
TimeUp summary
========================
:roast 0.07267s
:veggies 0.03760s
:pasta 0.01257s
:souffle* 0.00003s
* 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 when in doubt, I'd encourage you to read the code.
TimeUp
module
TimeUp.timer(name)
- Returns the Timer
instance named name
(creating it,
if it doesn't exist)
TimeUp.start(name, [&blk])
- Starts (or restarts) a named
Timer. 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
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
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.mean(name)
- The arithmetic mean of all recordings by the timer
TimeUp.median(name)
- The median of all recordings by the timer
TimeUp.percentile(name, percent)
- The timing for the given
percentile of all recordings by the
timer
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)
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)
TimeUp.stop_all
- Stops all timers
TimeUp.reset_all
- Resets all timers
TimeUp.delete_all
- Stops and resets all timers and deletes any internal
reference to them
TimeUp::Timer
class
start
- Starts the timer
stop
- Stops the timer
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 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
true, will also stop the timer if it's running
Code of Conduct
This project follows Test Double's code of conduct for all community interactions, including (but not limited to) one-on-one communications, public posts/comments, code reviews, pull requests, and GitHub issues. If violations occur, Test Double will take any action they deem appropriate for the infraction, up to and including blocking a user from the organization's repositories.