Histograms
==========

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

They're used when you have a type of data for which the following are true:

* There are distinct "events" for this type of data, such as "user performs
  a search and we return N results".
* Each event has a numeric value (the "N results" in our example).
* Comparisons of these numeric values are meaningful.

For example: HTTP status codes do *not* fit this because comparisons between the
numeric values are not meaningful.  The fact that 404 happens to be less than 500
doesn't tell you anything.

Contrast this with something like "search results returned": one value being
less than the other tells you something meaningful about the data.

Histograms can tell you things like:

    75% of all searches returned 100 or fewer results, while 95% got 200 or
    fewer.

If the numeric value you're recording is the amount of time taken to do
something, you probably want a timer instead of a histogram.

Examples of metrics you might want to track with a histogram:

* Search results returned ("99% of searches returned 300 or fewer results").
* Response body size ("75% of responses were 30kb or smaller").

**TODO:** More examples.

Creating
--------

Create your histogram::

    (require '[metrics.core :refer [new-registry]])
    (require '[metrics.histograms :refer (histogram)])

    (def reg (new-registry))

    (def search-results-returned
      (histogram reg "search-results-returned"))

The ``histogram`` function is idempotent, which means that you don't
need to keep a local reference to the histogram. Once a histogram has been
registered, a call to ``(histogram reg "search-results-returned")`` will return
the existing histogram.

.. _histograms/defhistogram:

You can also use the ``defhistogram`` macro to create a histogram and bind it to
a var in one concise, easy step::

    (require '[metrics.histograms :refer [defhistogram]])

    (defhistogram reg search-results-returned)

All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
title to make it easier to define.

Writing
-------

Once you've got a histogram you can update it with the numeric values of events
as they occur.

.. _histograms/update!:

``update!``
~~~~~~~~~~~

Update the histogram when you have a new value to record with ``update!``::

    (require '[metrics.histograms :refer [update!]])

    (update! search-results-returned 10)

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (update! (histogram reg "search-results-returned") 10)

Reading
-------

The data of a histogram metrics can be retrived in a bunch of different ways.

.. _histograms/percentiles:

``percentiles``
~~~~~~~~~~~~~~~

The function you'll usually want to use to pull data from a histogram is
``percentiles``::

    (require '[metrics.histograms :refer [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.

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (percentiles (histogram reg "search-results-returned"))
    => { 0.75   180
         0.95   299
         0.99   300
         0.999  340
         1.0   1345 }

If you want a different set of percentiles just pass them as a sequence::

    (require '[metrics.histograms :refer [percentiles]])

    (percentiles search-results-returned [0.50 0.75])
    => { 0.50 100
         0.75 180 }

.. _histograms/number-recorded:

``number-recorded``
~~~~~~~~~~~~~~~~~~~

To get the number of data points recorded over the entire lifetime of this
histogram::

    (require '[metrics.histograms :refer [number-recorded]])

    (number-recorded search-results-returned)
    => 12882

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (number-recorded (histogram reg "search-results-returned"))
    => 12882

.. _histograms/smallest:

``smallest``
~~~~~~~~~~~~

To get the smallest data point recorded over the entire lifetime of this
histogram::

    (require '[metrics.histograms :refer [smallest]])

    (smallest search-results-returned)
    => 4

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (smallest (histogram reg "search-results-returned"))
    => 4

.. _histograms/largest:

``largest``
~~~~~~~~~~~

To get the largest data point recorded over the entire lifetime of this
histogram::

    (require '[metrics.histograms :refer [largest]])

    (largest search-results-returned)
    => 1345

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (largest (histogram reg "search-results-returned"))
    => 1345

.. _histograms/mean:

``mean``
~~~~~~~~

To get the mean of the data points recorded over the entire lifetime of this
histogram::

    (require '[metrics.histograms :refer [mean]])

    (mean search-results-returned)
    => 233.12

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (mean (histogram reg "search-results-returned"))
    => 233.12

.. _histograms/std-dev:

``std-dev``
~~~~~~~~~~~

To get the standard deviation of the data points recorded over the entire
lifetime of this histogram::

    (require '[metrics.histograms :refer [std-dev]])

    (std-dev search-results-returned)
    => 80.2

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (std-dev (histogram reg "search-results-returned"))
    => 80.2

.. _histograms/sample:

``sample``
~~~~~~~~~~

You can get the current sample points the histogram 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.

::

    (require '[metrics.histograms :refer [sample]])

    (sample search-results-returned)
    => [12 2232 234 122]

Or if you haven't held a reference to ``search-results-returned``, you can do the following::

    (sample (histogram reg "search-results-returned"))
    => [12 2232 234 122]