Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 193 lines (110 sloc) 7.756 kB
14323fd name switch from emetrics to folsom
joewilliams authored
1 ### folsom
eef9c04 readme
joewilliams authored
2
675270c @derwolfe Link to correct metrics library
derwolfe authored
3 Folsom is an Erlang based metrics system inspired by Coda Hale's metrics (https://github.com/dropwizard/metrics). The metrics API's purpose is to collect realtime metrics from your Erlang applications and publish them via Erlang APIs and output plugins. folsom is *not* a persistent store. There are 6 types of metrics: counters, gauges, histograms (and timers), histories, meter_readers and meters. Metrics can be created, read and updated via the `folsom_metrics` module.
eef9c04 readme
joewilliams authored
4
a47831a readme update
joewilliams authored
5 #### Building and running
6
8faa239 readme update
joewilliams authored
7 First, regarding using folsom and folsom_webmachine together. To make sure you have compatible versions of each, make sure you use code from the same version tags, ie 0.5 of folsom is known to work with 0.5 folsom_webmachine. HEAD on each repo may have broken API compatibility.
8
a47831a readme update
joewilliams authored
9 You need a (preferably recent) version of Erlang installed but that should be it.
10
4355aec @etrepum make folsom an application, have folsom:start/0 use it
etrepum authored
11 ./rebar get-deps compile
a47831a readme update
joewilliams authored
12
13 folsom can be run standalone or embedded in an Erlang application.
14
4355aec @etrepum make folsom an application, have folsom:start/0 use it
etrepum authored
15 $ erl -pa ebin deps/*/ebin
a47831a readme update
joewilliams authored
16
4355aec @etrepum make folsom an application, have folsom:start/0 use it
etrepum authored
17 > folsom:start(). % this creates the needed ETS tables and starts a gen_server
18
19 You can also start it as an application:
20
21 $ erl -pa ebin deps/*/ebin
22 > application:start(folsom).
23
24 $ erl -pa ebin deps/*/ebin -s folsom
25
26 The application can be configured to create individual or lists of metrics at
27 startup on the command line or in an application config file:
28
29 $ erl -pa ebin deps/*/ebin -s folsom \
30 -folsom history '[hist1,hist2]' \
31 -folsom gauge gauge1
32
33 $ echo '[{folsom, [{history, [hist1, hist2]}, {gauge, gauge1}]}].' \
34 > myapp.config
35 $ erl -pa ebin deps/*/ebin -config myapp.config -s folsom
a47831a readme update
joewilliams authored
36
7618450 update
joewilliams authored
37 #### Metrics API
eef9c04 readme
joewilliams authored
38
1417378 updated readme
joewilliams authored
39 folsom_metrics.erl is the API module you will need to use most of the time.
40
b00c26e @Erkan-Yilmaz typos
Erkan-Yilmaz authored
41 Retrieve a list of current installed metrics:
1417378 updated readme
joewilliams authored
42
7618450 update
joewilliams authored
43 > folsom_metrics:get_metrics().
1417378 updated readme
joewilliams authored
44
45 Query a specific metric:
46
7618450 update
joewilliams authored
47 > folsom_metrics:get_metric_value(Name).
48
8faa239 readme update
joewilliams authored
49 Generally names of metrics are atoms or binaries.
50
7618450 update
joewilliams authored
51 ##### Counters
52
53 Counter metrics provide increment and decrement capabilities for a single scalar value.
54
55 > folsom_metrics:new_counter(Name).
56 > folsom_metrics:notify({Name, {inc, Value}}).
57 > folsom_metrics:notify({Name, {dec, Value}}).
58
59 ##### Gauges
60
0e8a27e readme update
joewilliams authored
61 Gauges are point-in-time single value metrics.
7618450 update
joewilliams authored
62
63 > folsom_metrics:new_gauge(Name).
64 > folsom_metrics:notify({Name, Value}).
65
66 ##### Histograms (and Timers)
1417378 updated readme
joewilliams authored
67
b00c26e @Erkan-Yilmaz typos
Erkan-Yilmaz authored
68 Histograms are collections of values that have statistical analysis done to them, such as mean, min, max, kurtosis and percentile. They can be used like "timers" as well with the timed update functions.
1417378 updated readme
joewilliams authored
69
7618450 update
joewilliams authored
70 > folsom_metrics:new_histogram(Name).
71 > folsom_metrics:histogram_timed_update(Name, Mod, Fun, Args).
72 > folsom_metrics:histogram_timed_update(Name, Fun, Args).
1b611da add anon functions without args to histogram timed updates
joewilliams authored
73 > folsom_metrics:histogram_timed_update(Name, Fun).
7618450 update
joewilliams authored
74 > folsom_metrics:notify({Name, Value}).
1417378 updated readme
joewilliams authored
75
2a71194 @russelldb Add new metric and sample types to README
russelldb authored
76 ###### Histogram sample types
77
78 Each histogram draws its values from a `reservoir` of readings. You can select a `sample type` for a histogram by passing the name of the sample type as an atom when you create a new histogram.
79 Some sample types have further arguments. The purpose of a sample type is to control the size and charecteristics of the reservoir of readings the histogram performs analysis upon.
80
81 Folsom currently provides the following sample types:
82
83 ###### `uniform`
84
85 This is a random uniform sample over the stream of readings. This is the default sample type, bounded in size to 1028 readings. When `size` readings have been taken, new readings replace older readings
86 in the reservoir at random. You can set the sample size at creation time:
87
88 > folsom_metrics:new_histogram(Name, uniform, Size::integer()).
89
90 Be sure you understand _why_ before you do this.
91
92 ###### `exdec`
93
94 This is a sample that exponentially decays less significant readings over time so as to give greater significance to newer readings. Read more here -
95 [Forward Decay...](http://www.research.att.com/people/Cormode_Graham/library/publications/CormodeShkapenyukSrivastavaXu09.pdf).
96 Again you can change defaults at creation time, if you think you need to:
97
98 > folsom_metrics:new_histogram(Name, exdec, Size::integer(), Alpha::float()).
99
100 ###### `slide`
101
102 This is a sliding window in time over a stream of readings. The default window size is 60 seconds. Every reading that occurs in a sliding sixty second window is stored,
103 with older readings being discarded. If you have a lot of readings per
104 minute the `reservoir` may get pretty big and so it will take more time to calculate statistics. You can set the `window` size by providing a number of seconds.
105
106 > folsom_metrics:new_histogram(Name, slide, Seconds::integer()).
107
108 ###### `slide_uniform`
109
110 This is a sliding window in time over a stream of readings with a random uniform sample per second, to bound the size of the total number of readings. The maximum size of the reservoir will be
111 `window size * sample size`. Default is a window of 60 seconds and a sample size of 1028. Again, you can change these at creation time:
112
113 > folsom_metrics:new_histogram(Name, slide_uniform, {Secs::interger(), Size::integer()).
114
7618450 update
joewilliams authored
115 ##### Histories
1417378 updated readme
joewilliams authored
116
7618450 update
joewilliams authored
117 Histories are a collection of past events, such as errors or log messages.
1417378 updated readme
joewilliams authored
118
7618450 update
joewilliams authored
119 > folsom_metrics:new_history(Name).
120 > folsom_metrics:get_history_values(Name, Count). % get more than the default number of history items back
121 > folsom_metrics:notify({Name, Value}).
1417378 updated readme
joewilliams authored
122
7618450 update
joewilliams authored
123 ##### Meters
1417378 updated readme
joewilliams authored
124
0e8a27e readme update
joewilliams authored
125 Meters are increment only counters with mean rates and exponentially weighted moving averages applied to them, similar to a unix load average.
1417378 updated readme
joewilliams authored
126
7618450 update
joewilliams authored
127 > folsom_metrics:new_meter(Name).
128 > folsom_metrics:notify({Name, Value}).
1417378 updated readme
joewilliams authored
129
2a71194 @russelldb Add new metric and sample types to README
russelldb authored
130 ###### `Spiral` meter
131
132 A `spiral` is a type of meter that has a one minute sliding window count. The meter tracks an increment only counter and a total for the last minute. This is a sliding count with older readings dropping off per second.
133
134 > folsom_metrics:new_spiral(Name).
135 > folsom_metrics:notify({Name, Count}).
136
889b333 @joewilliams readme update for meter reader
joewilliams authored
137 ##### Meter Reader
138
139 Meter readers are like a meter except that the values passed to it are monotonically increasing, e.g., reading from a water or gas meter, CPU jiffies, or I/O operation count.
140
141 > folsom_metrics:new_meter_reader(Name).
142 > folsom_metrics:notify({Name, Value}).
143
81f523a @AlexandreBeaulne Added grouped/tagged metrics feature
AlexandreBeaulne authored
144 ##### Metrics groups/tags
145
146 Certain users might want to group and query metrics monitoring a common task. In order to do so, they can
147 tag metrics:
148
149 > folsom_metrics:tag_metric(Name, Tag).
150
edcb9b9 @AlexandreBeaulne Added untag_metric/2 API call, updated unit tests accordingly, small …
AlexandreBeaulne authored
151 and untag metrics:
152
153 > folsom_metrics:untag_metric(Name, Tag).
154
155 Users can query a list of tuples `[{Name, Value}]` of all metrics with a given tag:
81f523a @AlexandreBeaulne Added grouped/tagged metrics feature
AlexandreBeaulne authored
156
157 > folsom_metrics:get_metrics_value(Tag).
158
159 If only a certain type of metrics from a given group is desired, one can specify so:
160
161 > folsom_metrics:get_metrics_value(Tag, Type).
162
163 where Type is one of `counter`, `gauge`, `histogram`, `history`, `meter`, `meter_reader`, `duration` or `spiral`.
164
7618450 update
joewilliams authored
165 ##### Erlang VM
85db943 fleshed out _events erlang and rest api
joewilliams authored
166
7618450 update
joewilliams authored
167 folsom also produces Erlang VM statistics.
eef9c04 readme
joewilliams authored
168
ca7accb readme fix attempt 4
joewilliams authored
169 The result of `erlang:memory/0`:
9a0ba4c readme fix attempt 3
joewilliams authored
170
14323fd name switch from emetrics to folsom
joewilliams authored
171 > folsom_vm_metrics:get_memory().
43529b9 readme fix attempt
joewilliams authored
172
ca7accb readme fix attempt 4
joewilliams authored
173 The result of `erlang:system_info/1`:
9a0ba4c readme fix attempt 3
joewilliams authored
174
14323fd name switch from emetrics to folsom
joewilliams authored
175 > folsom_vm_metrics:get_system_info().
43529b9 readme fix attempt
joewilliams authored
176
ca7accb readme fix attempt 4
joewilliams authored
177 The result of `erlang:statistics/1`:
9a0ba4c readme fix attempt 3
joewilliams authored
178
14323fd name switch from emetrics to folsom
joewilliams authored
179 > folsom_vm_metrics:get_statistics().
40acd48 readme update
joewilliams authored
180
181 The result of `erlang:process_info/1`:
182
183 > folsom_vm_metrics:get_process_info(). %% use with caution
184
185 The result of `inet:getstat/1`, `prim_inet:getstatus/1`, `erlang:port_info/1`, `prim_inet:gettype/1`, `inet:getopts/1`, `inet:sockname/1`:
186
187 > folsom_vm_metrics:get_port_info(). %% use with caution
9dfbb66 @joewilliams readme update
joewilliams authored
188
189 The result from `ets:info/1` and `dets:info/1` across all tables
190
191 > folsom_vm_metrics:get_ets_info().
192 > folsom_vm_metrics:get_dets_info().
Something went wrong with that request. Please try again.