-Meters are metrics that let you "mark" when
something happens and tell you how
+Meters are metrics that let you "mark" when happens and tell you how
+Meters are used for events where the only thing you care about is "this event
+If you need to record a value along with this you probably want a histogram.
+For example: "a user performed a search" could be tracked with a meter, but "a
+user performed a search *and got N results*" would need a histogram.
+Meters can tell you things like:
+ Over the past five minutes, an average of 6,500 searches were performed each
+Examples of metrics you might want to track with a meter:
+* A POST request was received.
+**TODO:** More examples.
The second argument to ``meter`` is a string describing the "units" for the
meter. In this example it's "files", as in "18732 files".
You can also use the ``defmeter`` macro to create a meter and bind it to a var
in one concise, easy step::
-Mark the meter every time the event happens::
+Once you've got a meter you can mark occurrences of events.
+Mark the meter every time the event happens with ``mark!``::
(use '[metrics.meters :only (mark!)])
There are a few functions you can use to retrieve the rate at which the metered
last one minute period, 120 times per second in the last five minute period, and
76 times per second in the last fifteen minute period.