Source

metrics-clojure / docs / source / timers.rst

Diff from to

File docs/source/timers.rst

 Timers
 ======
 
+Timers record the time it takes to do stuff.
+
 Creating
 --------
 
 
     (def image-processing-time (timer "image-processing-time"))
 
-Reading
--------
-
 Writing
 -------
 
                 (process-image-part-1 ...)
                 (process-image-part-2 ...)))
 
+Reading
+-------
+
+``percentiles``
+~~~~~~~~~~~~~~~
+
+You can use ``percentiles`` to find the percentage of actions that take less
+than or equal to a certain amount of time::
+
+    (use '[metrics.timers :only (percentiles)])
+
+    (percentiles image-processing-time)
+    => { 0.75  232.00
+         0.95  240.23
+         0.99  280.01
+         0.999 400.232
+         1.0   903.1 }
+
+This returns a map of the percentiles you probably care about.  The keys are the
+percentiles (doubles between 0 and 1 inclusive) and the values are the maximum
+time taken for that percentile.  In this example:
+
+* 75% of images were processed in 232.00 milliseconds or less.
+* 95% of images were processed in 240.23 milliseconds or less.
+* ... etc.
+
+If you want a different set of percentiles just pass them as a sequence::
+
+    (use '[metrics.timers :only (percentiles)])
+
+    (percentiles image-processing-time [0.50 0.75])
+    => { 0.50 182.11
+         0.75 232.00 }
+
+``number-recorded``
+~~~~~~~~~~~~~~~~~~~
+
+To get the number of data points recorded over the entire lifetime of this
+timers::
+
+    (use '[metrics.timers :only (number-recorded)])
+
+    (number-recorded image-processing-time)
+    => 12882
+
+``smallest``
+~~~~~~~~~~~~
+
+To get the smallest data point recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (smallest)])
+
+    (smallest image-processing-time)
+    => 80.66
+
+``largest``
+~~~~~~~~~~~
+
+To get the largest data point recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (largest)])
+
+    (largest image-processing-time)
+    => 903.1
+
+``mean``
+~~~~~~~~
+
+To get the mean of the data points recorded over the entire lifetime of this
+timer::
+
+    (use '[metrics.timers :only (mean)])
+
+    (mean image-processing-time)
+    => 433.12
+
+``std-dev``
+~~~~~~~~~~~
+
+To get the standard deviation of the data points recorded over the entire
+lifetime of this timer::
+
+    (use '[metrics.histograms :only (std-dev)])
+
+    (std-dev image-processing-time)
+    => 300.51
+
+``sample``
+~~~~~~~~~~
+
+You can get the current sample points the timer is using with ``sample``, but
+you almost *certainly* don't care about this.  If you use it make sure you know
+what you're doing.
+
+::
+
+    (use '[metrics.timers :only (sample)])
+
+    (sample image-processing-time)
+    => [803.234 102.223 ...]
+
+
+TODO: Rates
+~~~~~~~~~~~