README.md
1go-metrics
2==========
3
4This library provides a `metrics` package which can be used to instrument code,
5expose application metrics, and profile runtime performance in a flexible manner.
6
7Current API: [](https://godoc.org/github.com/armon/go-metrics)
8
9Sinks
10-----
11
12The `metrics` package makes use of a `MetricSink` interface to support delivery
13to any type of backend. Currently the following sinks are provided:
14
15* StatsiteSink : Sinks to a [statsite](https://github.com/armon/statsite/) instance (TCP)
16* StatsdSink: Sinks to a [StatsD](https://github.com/etsy/statsd/) / statsite instance (UDP)
17* PrometheusSink: Sinks to a [Prometheus](http://prometheus.io/) metrics endpoint (exposed via HTTP for scrapes)
18* InmemSink : Provides in-memory aggregation, can be used to export stats
19* FanoutSink : Sinks to multiple sinks. Enables writing to multiple statsite instances for example.
20* BlackholeSink : Sinks to nowhere
21
22In addition to the sinks, the `InmemSignal` can be used to catch a signal,
23and dump a formatted output of recent metrics. For example, when a process gets
24a SIGUSR1, it can dump to stderr recent performance metrics for debugging.
25
26Labels
27------
28
29Most metrics do have an equivalent ending with `WithLabels`, such methods
30allow to push metrics with labels and use some features of underlying Sinks
31(ex: translated into Prometheus labels).
32
33Since some of these labels may increase greatly cardinality of metrics, the
34library allow to filter labels using a blacklist/whitelist filtering system
35which is global to all metrics.
36
37* If `Config.AllowedLabels` is not nil, then only labels specified in this value will be sent to underlying Sink, otherwise, all labels are sent by default.
38* If `Config.BlockedLabels` is not nil, any label specified in this value will not be sent to underlying Sinks.
39
40By default, both `Config.AllowedLabels` and `Config.BlockedLabels` are nil, meaning that
41no tags are filetered at all, but it allow to a user to globally block some tags with high
42cardinality at application level.
43
44Examples
45--------
46
47Here is an example of using the package:
48
49```go
50func SlowMethod() {
51 // Profiling the runtime of a method
52 defer metrics.MeasureSince([]string{"SlowMethod"}, time.Now())
53}
54
55// Configure a statsite sink as the global metrics sink
56sink, _ := metrics.NewStatsiteSink("statsite:8125")
57metrics.NewGlobal(metrics.DefaultConfig("service-name"), sink)
58
59// Emit a Key/Value pair
60metrics.EmitKey([]string{"questions", "meaning of life"}, 42)
61```
62
63Here is an example of setting up a signal handler:
64
65```go
66// Setup the inmem sink and signal handler
67inm := metrics.NewInmemSink(10*time.Second, time.Minute)
68sig := metrics.DefaultInmemSignal(inm)
69metrics.NewGlobal(metrics.DefaultConfig("service-name"), inm)
70
71// Run some code
72inm.SetGauge([]string{"foo"}, 42)
73inm.EmitKey([]string{"bar"}, 30)
74
75inm.IncrCounter([]string{"baz"}, 42)
76inm.IncrCounter([]string{"baz"}, 1)
77inm.IncrCounter([]string{"baz"}, 80)
78
79inm.AddSample([]string{"method", "wow"}, 42)
80inm.AddSample([]string{"method", "wow"}, 100)
81inm.AddSample([]string{"method", "wow"}, 22)
82
83....
84```
85
86When a signal comes in, output like the following will be dumped to stderr:
87
88 [2014-01-28 14:57:33.04 -0800 PST][G] 'foo': 42.000
89 [2014-01-28 14:57:33.04 -0800 PST][P] 'bar': 30.000
90 [2014-01-28 14:57:33.04 -0800 PST][C] 'baz': Count: 3 Min: 1.000 Mean: 41.000 Max: 80.000 Stddev: 39.509
91 [2014-01-28 14:57:33.04 -0800 PST][S] 'method.wow': Count: 3 Min: 22.000 Mean: 54.667 Max: 100.000 Stddev: 40.513
){kind=link}