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.
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 magic to the metric
title to make it easier to define.
Writing¶
Once you’ve got a meter you can mark occurrences of events.
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.
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.
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
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
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
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