Commits

Steve Losh committed 41f4d65

Polish up the docs, adding examples and more structure.

  • Participants
  • Parent commits ff65daf

Comments (0)

Files changed (7)

File docs/source/index.rst

    :maxdepth: 1
 
    installation
+   metrics/gauges
    metrics/counters
-   metrics/gauges
    metrics/meters
    metrics/histograms
    metrics/timers

File docs/source/metrics/counters.rst

 Counters
 ========
 
-Counters are values you can increment and decrement.
+Counters are integer values you can increment and decrement.
+
+They can be useful for tracking things that you don't have a particular list of,
+but you do control when they're added/removed/opened/closed.
+
+For example: it's not necessarily very easy to get a list of all the open HTTP
+connections for a web server, but it's often easy to wrap some "middleware" that
+increments the "open requests" counter when a request comes in and decrements it
+when the response goes out.
+
+They can also be useful for tracking simple "total" values like "total requests
+served in this app's entire lifetime".
+
+Examples of metrics you might want to track with a counter:
+
+* Number of http requests currently being processed.
+* Total number of requests/responses received/sent.
+
+**TODO:** More examples.
 
 Creating
 --------
 
     (def users-connected (counter "users-connected"))
 
-.. _defcounter:
+.. _counters/defcounter:
 
 You can also use the ``defcounter`` macro to create a counter and bind it to a var
 in one concise, easy step::
 Writing
 -------
 
-Now increment and decrement it::
+Once you have a counter you can increment it and decrement it.
 
-    (use '[metrics.counters :only (inc! dec!)])
+.. _counters/inc!:
+
+``inc!``
+~~~~~~~~
+
+Increment counters with ``inc!``.  You can pass a number to increment it by, or
+omit it to increment by 1::
+
+    (use '[metrics.counters :only (inc!)])
 
     (inc! users-connected)
     (inc! users-connected 2)
 
+.. _counters/dec!:
+
+``dec!``
+~~~~~~~~
+
+Decrement counters with ``dec!``.  You can pass a number to decrement it by, or
+omit it to decrement by 1::
+
+    (use '[metrics.counters :only (dec!)])
+
     (dec! users-connected)
     (dec! users-connected 2)
 
 
 There's only one way to get data from a counter.
 
+.. _counters/value:
+
 ``value``
 ~~~~~~~~~
 

File 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``
 ~~~~~~~~~
 

File 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``
 ~~~~~~~~~~
 

File 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``
 ~~~~~~~~~~~~~
 

File docs/source/metrics/timers.rst

 Timers
 ======
 
-Timers record the time it takes to do stuff.
+Timers record the time it takes to do things.  They're a bit like histograms
+where the value being recorded is time.
+
+Timers should be a fairly intuitive concept.  They can tell you things like:
+
+    75% of all searches took 0.5 seconds or less.  95% of all searches took 1.0
+    seconds or less.
+
+Timers also track the rate of the timed events, so it's like they have a meter
+metric built-in for convenience.
 
 Creating
 --------
 
     (def image-processing-time (timer "image-processing-time"))
 
-.. _deftimer:
+.. _timers/deftimer:
 
 You can also use the ``deftimer`` macro to create a timer and bind it to a var
 in one concise, easy step::
 Writing
 -------
 
-Now time something::
+Once you have a timer you can record times to it in two different ways.
+
+.. _timers/time!:
+
+``time!``
+~~~~~~~~~
+
+You can record the time it takes to evaluate one or more expressions with the ``time!`` macro::
 
     (use '[metrics.timers :only (time!)])
 
            (process-image-part-1 ...)
            (process-image-part-2 ...))
 
-``time!`` is a macro.  If you need a function instead, you can use ``time-fn!``,
-but you'll need to pass it a function instead of just a body::
+.. _timers/time-fn!:
+
+``time-fn!``
+~~~~~~~~~~~~
+
+``time!`` is a macro.  If you need a function instead (e.g.: for ``map``'ing
+over a list), you can use ``time-fn!``, but you'll need to pass it a function
+instead of a body::
 
     (use '[metrics.timers :only (time-fn!)])
 
 Reading
 -------
 
+.. _timers/percentiles:
+
 ``percentiles``
 ~~~~~~~~~~~~~~~
 
     => { 0.50 182.11
          0.75 232.00 }
 
+.. _timers/number-recorded:
+
 ``number-recorded``
 ~~~~~~~~~~~~~~~~~~~
 
     (number-recorded image-processing-time)
     => 12882
 
+.. _timers/smallest:
+
 ``smallest``
 ~~~~~~~~~~~~
 
     (smallest image-processing-time)
     => 80.66
 
+.. _timers/largest:
+
 ``largest``
 ~~~~~~~~~~~
 
     (largest image-processing-time)
     => 903.1
 
+.. _timers/mean:
+
 ``mean``
 ~~~~~~~~
 
     (mean image-processing-time)
     => 433.12
 
+.. _timers/std-dev:
+
 ``std-dev``
 ~~~~~~~~~~~
 
     (std-dev image-processing-time)
     => 300.51
 
+.. _timers/sample:
+
 ``sample``
 ~~~~~~~~~~
 

File docs/source/title-desugaring.rst

 Title Desugaring by the ``def[metric]`` Macros
 ==============================================
 
-All of the ``def[metric]`` macros (:ref:`defcounter <defcounter>`,
-:ref:`defgauge <defgauge>`, :ref:`defhistogram <defhistogram>`, :ref:`defmeter
-<defmeter>`, and :ref:`deftimer <deftimer>`) take a title as their first
-argument.
+All of the ``def[metric]`` macros (:ref:`defcounter <counters/defcounter>`,
+:ref:`defgauge <gauges/defgauge>`, :ref:`defhistogram
+<histograms/defhistogram>`, :ref:`defmeter <meters/defmeter>`, and
+:ref:`deftimer <timers/deftimer>`) take a title as their first argument.
 
 All of the macros will use this title as a symbol when binding it to a var, and
 will convert it to a string to use as the :ref:`name <metric-names>` of the