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

Diff from to

docs/source/metrics/meters.rst

 Meters
 ======
 
-Meters are metrics that let you "mark" when something happens and tell you how
+Meters are metrics that let you "mark" when an event happens and tell you how
 often it occurs.
 
+Meters are used for events where the only thing you care about is "this event
+happened".
+
+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
+    second.
+
+Examples of metrics you might want to track with a meter:
+
+* A user logged in.
+* A POST request was received.
+
+**TODO:** More examples.
+
 Creating
 --------
 
 The second argument to ``meter`` is a string describing the "units" for the
 meter.  In this example it's "files", as in "18732 files".
 
-.. _defmeter:
+.. _meters/defmeter:
 
 You can also use the ``defmeter`` macro to create a meter and bind it to a var
 in one concise, easy step::
 Writing
 -------
 
-Mark the meter every time the event happens::
+Once you've got a meter you can mark occurrences of events.
+
+.. _meters/mark!:
+
+``mark!``
+~~~~~~~~~
+
+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
 events occur.
 
+.. _meters/rates:
+
 ``rates``
 ~~~~~~~~~
 
 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.
 
+.. _meters/rate-one:
+
 ``rate-one``
 ~~~~~~~~~~~~
 
     (rate-one files-served)
     => 100.0
 
+.. _meters/rate-five:
+
 ``rate-five``
 ~~~~~~~~~~~~~
 
     (rate-five files-served)
     => 120.0
 
+.. _meters/rate-fifteen:
+
 ``rate-fifteen``
 ~~~~~~~~~~~~~~~~
 
     (rate-fifteen files-served)
     => 76.0
 
+.. _meters/rate-mean:
+
 ``rate-mean``
 ~~~~~~~~~~~~~
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.