Diff from to

# 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`
`+~~~~~~~~~~~`