Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 157 lines (118 sloc) 5.336 kb
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
1 Metrics
2 =======
3
4 * A node.js port of codahale's metrics library: https://github.com/codahale/metrics
5
5620e41e » Mike Ihbe
2012-02-07 Tidy up the readme a bit
6 Metrics provides an instrumentation toolkit to measure the behavior of your critical systems while they're running in production.
7
046782ab » Mike Ihbe
2012-02-07 and again
8 Instruments
9 ----------
10
11 **Counters**
12
13 Counters count things.
d1af4ff7 »
2012-02-07 Update README.md
14
046782ab » Mike Ihbe
2012-02-07 and again
15 They implement: inc, dec, clear
d1af4ff7 »
2012-02-07 Update README.md
16
046782ab » Mike Ihbe
2012-02-07 and again
17 They expose: count
18
19 ```javascript
20 var counter = new metrics.Counter
21 counter.inc(1)
22 counter.inc(3)
23 counter.dec(2)
24 counter.count // 2
25 counter.clear()
26 counter.count // 0
27 ```
28
29 **Histograms**
d1af4ff7 »
2012-02-07 Update README.md
30
046782ab » Mike Ihbe
2012-02-07 and again
31 Histograms sample a dataset to get a sense of its distribution. These are particularly useful for breaking down the quantiles of how longs things take (requests, method calls, etc). Metrics supports uniform distributions and exponentially decaying samples. Sample sizes and parameters of the distribution are all highly configurable, but the defaults will probably suit your needs. Exponential decay histograms favor more recent data, which is typically what you want
d1af4ff7 »
2012-02-07 Update README.md
32
046782ab » Mike Ihbe
2012-02-07 and again
33 They implement: update, mean, stdDev, percentiles, clear
d1af4ff7 »
2012-02-07 Update README.md
34
046782ab » Mike Ihbe
2012-02-07 and again
35 They expose: count, min, max, sum
36
37 ```javascript
82ce1825 » wavded
2012-08-07 fixed; histogram example
38 var hist1 = new metrics.Histogram.createExponentialDecayHistogram()
39 , hist2 = new metrics.Histogram.createUniformHistogram();
b7513891 »
2012-02-08 Update README.md
40 hist2.update(1);
41 hist2.update(3);
42 hist2.mean(); // 2
046782ab » Mike Ihbe
2012-02-07 and again
43 ```
44
45 **Meter**
46
47 A meter tracks how often things happen. It exposes a 1 minute rate, a 5 minute rate, and a 15 minute rate using exponentially weighted moving averages (the same strategy that unix load average takes).
d1af4ff7 »
2012-02-07 Update README.md
48
046782ab » Mike Ihbe
2012-02-07 and again
49 They implement: mark, oneMinuteRate, fiveMinuteRate, fifteenMinuteRate, meanRate
50
51 ```javascript
52 var meter = new metrics.Meter
b7513891 »
2012-02-08 Update README.md
53 meter.mark();
54 meter.mark();
55 meter.mark();
56 meter.meanRate(); // depends on how fast you called mark()
046782ab » Mike Ihbe
2012-02-07 and again
57 ```
58
59 **Timer**
60
61 A Timer is a combination of a meter and a histogram. It samples timing data and rate the data is coming in. Everything you could possibly want!
d1af4ff7 »
2012-02-07 Update README.md
62
046782ab » Mike Ihbe
2012-02-07 and again
63 They implement: update, mark, clear, count, min, max, mean, stdDev, percentiles, oneMinuteRate, fiveMinuteRate, fifteenMinuteRate, meanRate
64
65 ```javascript
66 var timer = new metrics.Timer;
b7513891 »
2012-02-08 Update README.md
67 timer.update(1);
046782ab » Mike Ihbe
2012-02-07 and again
68 ```
69
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
70 How to Use
71 ----------
72
73 **Import Metrics**
74
75 ```javascript
b7513891 »
2012-02-08 Update README.md
76 metrics = require('metrics');
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
77 ```
78
79 **Start a metrics Server**
80
81 ```javascript
5620e41e » Mike Ihbe
2012-02-07 Tidy up the readme a bit
82 var metricsServer = new metrics.Server(config.metricsPort || 9091);
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
83 ```
84
5620e41e » Mike Ihbe
2012-02-07 Tidy up the readme a bit
85 Servers are only one way to report your metrics. It's actually a thin layer on top of metrics.Report, which you could use to build other reporting mechanisms.
86
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
87 **Add the metrics to the server**
88
89 ```javascript
046782ab » Mike Ihbe
2012-02-07 and again
90 metricsServer.addMetric('com.co.thingA', counter);
91 metricsServer.addMetric('com.co.thingB', hist1);
92 metricsServer.addMetric('com.co.thingC', hist2);
93 metricsServer.addMetric('com.co.thingD', meter);
94 metricsServer.addMetric('com.co.thingE', timer);
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
95 ```
96
97
98 Advanced Usage
99 --------------
100 Typical production deployments have multiple node processes per server. Rather than each process exposing metrics on different ports, it makes more sense to expose the metrics from the "master" process. Writing a thin wrapper around this api to perform the process communication is trivial, with a message passing setup, the client processes could look something like this:
101
102 ```javascript
103 var Metric = exports = module.exports = function Metrics(messagePasser, eventType) {
104 this.messagePasser = messagePasser;
105 this.eventType = eventType;
106 }
107
108 Metric.prototype.newMetric = function(type, eventType) {
109 this.messagePasser.sendMessage({
110 method: 'createMetric'
111 , type: type
112 , eventType: eventType
b3c0ca1d » Mike Ihbe
2011-05-09 Added advanced usage to readme
113 });
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
114 }
b3c0ca1d » Mike Ihbe
2011-05-09 Added advanced usage to readme
115 Metric.prototype.forwardMessage = function(method, args) {
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
116 this.messagePasser.sendMessage({
117 method: 'updateMetric'
118 , metricMethod: method
119 , metricArgs: args
120 , eventType: this.eventType
121 });
122 }
123
124 Metric.prototype.update = function(val) { return this.forwardMessage('update', [val]); }
125 Metric.prototype.mark = function(n) { return this.forwardMessage('mark', [n]); }
126 Metric.prototype.inc = function(n) { return this.forwardMessage('inc', [n]); }
127 Metric.prototype.dec = function(n) { return this.forwardMessage('dec', [n]); }
128 Metric.prototype.clear = function() { return this.forwardMessage('clear'); }
129 ```
130
b3c0ca1d » Mike Ihbe
2011-05-09 Added advanced usage to readme
131 And the server side that receives the createMetric and updateMetric rpcs could look something like this:
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
132
133 ```javascript
134 {
135 createMetric: function(msg) {
136 if (metricsServer) {
137 msg.type = msg.type[0].toUpperCase() + msg.type.substring(1)
138 metricsServer.addMetric(msg.eventType, new metrics[msg.type]);
139 }
140 }
141 updateMetric: function(msg) {
142 if (metricsServer) {
143 var namespaces = msg.eventType.split('.')
144 , event = namespaces.pop()
145 , namespace = namespaces.join('.');
146 var metric = metricsServer.trackedMetrics[namespace][event];
147 metric[msg.metricMethod].apply(metric, msg.metricArgs);
148 }
149 }
150 ```
151
b3c0ca1d » Mike Ihbe
2011-05-09 Added advanced usage to readme
152 For multiple server deployments, you have more options, but the best approach will be highly application dependent. Best of luck, and always be tracking!
153
84568879 » Mike Ihbe
2011-05-09 Add a readme due to growing popularity
154 How to Collect
155 --------------
156
5620e41e » Mike Ihbe
2012-02-07 Tidy up the readme a bit
157 Using the metrics server you can hit the server on your configured port and you'll get a json representation of your metrics. You should collect these periodically to generate timeseries to monitor the longterm health of your application. The metrics.Reporting object would let you write to a log periodically or however else you'd like to expose your metrics.
Something went wrong with that request. Please try again.