Diff from to

File docs/source/histograms.rst

Histograms
==========

+Histograms are used to record the distribution of a piece of data over time.
+
Creating
--------

(def search-results-returned-biased
(histogram "search-results-returned-biased" true))

--------
-
Writing
-------

(update! search-results-returned 10)

+-------
+
+The data of a histogram metrics can be retrived in a bunch of different ways.
+
+``percentiles``
+~~~~~~~~~~~~~~~
+
+The function you'll usually want to use to pull data from a histogram is
+``percentiles``::
+
+    (use '[metrics.histograms :only (percentiles)])
+
+    (percentiles search-results-returned)
+    => { 0.75   180
+         0.95   299
+         0.99   300
+         0.999  340
+         1.0   1345 }
+
+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
+value for that percentile.  In this example:
+
+* 75% of searches returned 180 or fewer results.
+* 95% of searches returned 299 or fewer results.
+* ... etc.
+
+If you want a different set of percentiles just pass them as a sequence::
+
+    (use '[metrics.histograms :only (percentiles)])
+
+    (percentiles search-results-returned [0.50 0.75])
+    => { 0.50 100
+         0.75 180 }
+
+``number-recorded``
+~~~~~~~~~~~~~~~~~~~
+
+To get the number of data points recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (number-recorded)])
+
+    (number-recorded search-results-returned)
+    => 12882
+
+``smallest``
+~~~~~~~~~~~~
+
+To get the smallest data point recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (smallest)])
+
+    (smallest search-results-returned)
+    => 4
+
+``largest``
+~~~~~~~~~~~
+
+To get the largest data point recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (largest)])
+
+    (largest search-results-returned)
+    => 1345
+
+``mean``
+~~~~~~~~
+
+To get the mean of the data points recorded over the entire lifetime of this
+histogram::
+
+    (use '[metrics.histograms :only (mean)])
+
+    (mean search-results-returned)
+    => 233.12
+
+``std-dev``
+~~~~~~~~~~~
+
+To get the standard deviation of the data points recorded over the entire
+
+    (use '[metrics.histograms :only (std-dev)])
+
+    (std-dev search-results-returned)
+    => 80.2
+
+``sample``
+~~~~~~~~~~
+
+You can get the current sample points the histogram is using with ``sample``,