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.
(histogram "search-results-returned-unbiased" false))
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.