Meters
======

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
--------

Create your meter::

    (require '[metrics.core :refer [new-registry]])
    (require '[metrics.meters :refer [meter]])

    (def reg (new-registry))
    (def files-served (meter reg "files-served"))

The ``meter`` function is idempotent, which means that you don't
need to keep a local reference to the meter. Once a meter has been
registered, a call to ``(meter reg "files-served")`` will return
the existing meter.

.. _meters/defmeter:

You can also use the ``defmeter`` macro to create a meter and bind it to a var
in one concise, easy step::

    (require '[metrics.meters :refer (defmeter)])

    (defmeter reg files-served)

All the ``def[metric]`` macros do some :ref:`magic <desugaring>` to the metric
title to make it easier to define.

Writing
-------

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!``::

    (require '[metrics.meters :refer [mark!]])

    (mark! files-served)

Or if you haven't held a reference to ``files-served``, you can do the following::

    (mark! (meter reg "files-served"))

Reading
-------

There are a few functions you can use to retrieve the rate at which the metered
events occur.

.. _meters/rates:

``rates``
~~~~~~~~~

You can get a map containing the mean rates of the event considering the last
one, five, and fifteen minute periods with ``rates``::

    (require '[metrics.meters :refer (rates)])

    (rates files-served)
    => { 1 100.0,
         5 120.0,
        15 76.0}

In this example the event happened approximately 100 times per second during the
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``
~~~~~~~~~~~~

If you only care about the rate of events during the last minute you can use
``rate-one``::

    (require '[metrics.meters :refer [rate-one]])

    (rate-one files-served)
    => 100.0

Or if you haven't held a reference to ``files-served``, you can do the following::

    (rate-one (meter reg "files-served"))
    => 100.0

.. _meters/rate-five:

``rate-five``
~~~~~~~~~~~~~

If you only care about the rate of events during the last five minutes you can
use ``rate-five``::

    (require '[metrics.meters :refer [rate-five]])

    (rate-five files-served)
    => 120.0

Or if you haven't held a reference to ``files-served``, you can do the following::

    (rate-five (meter reg "files-served"))
    => 120.0

.. _meters/rate-fifteen:

``rate-fifteen``
~~~~~~~~~~~~~~~~

If you only care about the rate of events during the last fifteen minutes you
can use ``rate-fifteen``::

    (require '[metrics.meters :refer [rate-fifteen]])

    (rate-fifteen files-served)
    => 76.0

Or if you haven't held a reference to ``files-served``, you can do the following::

    (rate-fifteen (meter reg "files-served"))
    => 76.0

.. _meters/rate-mean:

``rate-mean``
~~~~~~~~~~~~~

If you really want the mean rate of events over the lifetime of the meter (hint:
you probably don't) you can use ``rate-mean``::

    (require '[metrics.meters :refer [rate-mean]])

    (rate-mean files-served)
    => 204.123

Or if you haven't held a reference to ``files-served``, you can do the following::

    (rate-mean (meter reg "files-served"))
    => 204.123