1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
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
|
