Source

metrics-clojure / docs / source / metrics / histograms.rst

Diff from to

docs/source/metrics/histograms.rst

 
 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
+    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
 --------
 
     (def search-results-returned-biased
       (histogram "search-results-returned-unbiased" false))
 
-.. _defhistogram:
+.. _histograms/defhistogram:
 
 You can also use the ``defhistogram`` macro to create a histogram and bind it to
 a var in one concise, easy step::
 Writing
 -------
 
-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
+as they occur.
+
+.. _histograms/update!:
+
+``update!``
+~~~~~~~~~~~
+
+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:
+
 ``percentiles``
 ~~~~~~~~~~~~~~~
 
     => { 0.50 100
          0.75 180 }
 
+.. _histograms/number-recorded:
+
 ``number-recorded``
 ~~~~~~~~~~~~~~~~~~~
 
     (number-recorded search-results-returned)
     => 12882
 
+.. _histograms/smallest:
+
 ``smallest``
 ~~~~~~~~~~~~
 
     (smallest search-results-returned)
     => 4
 
+.. _histograms/largest:
+
 ``largest``
 ~~~~~~~~~~~
 
     (largest search-results-returned)
     => 1345
 
+.. _histograms/mean:
+
 ``mean``
 ~~~~~~~~
 
     (mean search-results-returned)
     => 233.12
 
+.. _histograms/std-dev:
+
 ``std-dev``
 ~~~~~~~~~~~
 
     (std-dev search-results-returned)
     => 80.2
 
+.. _histograms/sample:
+
 ``sample``
 ~~~~~~~~~~