Source

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

Diff from to

docs/source/metrics/gauges.rst

 
 Gauges are used to measure the instantaneous value of something.
 
+They're often useful for things that aren't events, like "users currently in the
+database".  If you can perform a query of some kind at any time to get a value,
+it's probably something suitable for a gauge.
+
+Examples of metrics you might want to track with a gauge:
+
+* Number of users in your database.
+
+**TODO:** More examples.
+
 Creating
 --------
 
       (gauge-fn "files-open"
              #(return-number-of-files-open ...)))
 
-.. _defgauge:
+.. _gauges/defgauge:
 
 You can also use the ``defgauge`` macro to create a gauge and bind it to a var
 in one concise, easy step::
 Writing
 -------
 
-There is no writing.  Gauges execute the form(s) (or function) you passed when
-creating them every time they're read.  You don't need to do anything else.
+With gauges there is no writing.  Gauges execute the form(s) (or function) you
+passed when creating them every time they're read.  You don't need to do
+anything else.
 
 Reading
 -------
 
 There's only one way to get data from a gauge.
 
+.. _gauges/value:
+
 ``value``
 ~~~~~~~~~