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 meaingful. 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

+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.

(def search-results-returned-biased

(histogram "search-results-returned-unbiased" false))

+.. _histograms/defhistogram:

You can also use the ``defhistogram`` macro to create a histogram and bind it to

a var in one concise, easy step::

-Update the histogram when you have a new value to record::

+Once you've got a histogram you can update it with the numeric values of events

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

(use '[metrics.histograms :only (update!)])

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

+.. _histograms/percentiles:

+.. _histograms/number-recorded:

(number-recorded search-results-returned)

+.. _histograms/smallest:

(smallest search-results-returned)

(largest search-results-returned)

(mean search-results-returned)

(std-dev search-results-returned)