1go-metrics
2==========
3
4
5
6Go port of Coda Hale's Metrics library: <https://github.com/dropwizard/metrics>.
7
8Documentation: <http://godoc.org/github.com/rcrowley/go-metrics>.
9
10Usage
11-----
12
13Create and update metrics:
14
15```go
16c := metrics.NewCounter()
17metrics.Register("foo", c)
18c.Inc(47)
19
20g := metrics.NewGauge()
21metrics.Register("bar", g)
22g.Update(47)
23
24r := NewRegistry()
25g := metrics.NewRegisteredFunctionalGauge("cache-evictions", r, func() int64 { return cache.getEvictionsCount() })
26
27s := metrics.NewExpDecaySample(1028, 0.015) // or metrics.NewUniformSample(1028)
28h := metrics.NewHistogram(s)
29metrics.Register("baz", h)
30h.Update(47)
31
32m := metrics.NewMeter()
33metrics.Register("quux", m)
34m.Mark(47)
35
36t := metrics.NewTimer()
37metrics.Register("bang", t)
38t.Time(func() {})
39t.Update(47)
40```
41
42Register() is not threadsafe. For threadsafe metric registration use
43GetOrRegister:
44
45```go
46t := metrics.GetOrRegisterTimer("account.create.latency", nil)
47t.Time(func() {})
48t.Update(47)
49```
50
51**NOTE:** Be sure to unregister short-lived meters and timers otherwise they will
52leak memory:
53
54```go
55// Will call Stop() on the Meter to allow for garbage collection
56metrics.Unregister("quux")
57// Or similarly for a Timer that embeds a Meter
58metrics.Unregister("bang")
59```
60
61Periodically log every metric in human-readable form to standard error:
62
63```go
64go metrics.Log(metrics.DefaultRegistry, 5 * time.Second, log.New(os.Stderr, "metrics: ", log.Lmicroseconds))
65```
66
67Periodically log every metric in slightly-more-parseable form to syslog:
68
69```go
70w, _ := syslog.Dial("unixgram", "/dev/log", syslog.LOG_INFO, "metrics")
71go metrics.Syslog(metrics.DefaultRegistry, 60e9, w)
72```
73
74Periodically emit every metric to Graphite using the [Graphite client](https://github.com/cyberdelia/go-metrics-graphite):
75
76```go
77
78import "github.com/cyberdelia/go-metrics-graphite"
79
80addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:2003")
81go graphite.Graphite(metrics.DefaultRegistry, 10e9, "metrics", addr)
82```
83
84Periodically emit every metric into InfluxDB:
85
86**NOTE:** this has been pulled out of the library due to constant fluctuations
87in the InfluxDB API. In fact, all client libraries are on their way out. see
88issues [#121](https://github.com/rcrowley/go-metrics/issues/121) and
89[#124](https://github.com/rcrowley/go-metrics/issues/124) for progress and details.
90
91```go
92import "github.com/vrischmann/go-metrics-influxdb"
93
94go influxdb.InfluxDB(metrics.DefaultRegistry,
95 10e9,
96 "127.0.0.1:8086",
97 "database-name",
98 "username",
99 "password"
100)
101```
102
103Periodically upload every metric to Librato using the [Librato client](https://github.com/mihasya/go-metrics-librato):
104
105**Note**: the client included with this repository under the `librato` package
106has been deprecated and moved to the repository linked above.
107
108```go
109import "github.com/mihasya/go-metrics-librato"
110
111go librato.Librato(metrics.DefaultRegistry,
112 10e9, // interval
113 "example@example.com", // account owner email address
114 "token", // Librato API token
115 "hostname", // source
116 []float64{0.95}, // percentiles to send
117 time.Millisecond, // time unit
118)
119```
120
121Periodically emit every metric to StatHat:
122
123```go
124import "github.com/rcrowley/go-metrics/stathat"
125
126go stathat.Stathat(metrics.DefaultRegistry, 10e9, "example@example.com")
127```
128
129Maintain all metrics along with expvars at `/debug/metrics`:
130
131This uses the same mechanism as [the official expvar](http://golang.org/pkg/expvar/)
132but exposed under `/debug/metrics`, which shows a json representation of all your usual expvars
133as well as all your go-metrics.
134
135
136```go
137import "github.com/rcrowley/go-metrics/exp"
138
139exp.Exp(metrics.DefaultRegistry)
140```
141
142Installation
143------------
144
145```sh
146go get github.com/rcrowley/go-metrics
147```
148
149StatHat support additionally requires their Go client:
150
151```sh
152go get github.com/stathat/go
153```
154
155Publishing Metrics
156------------------
157
158Clients are available for the following destinations:
159
160* AppOptics - https://github.com/ysamlan/go-metrics-appoptics
161* Librato - https://github.com/mihasya/go-metrics-librato
162* Graphite - https://github.com/cyberdelia/go-metrics-graphite
163* InfluxDB - https://github.com/vrischmann/go-metrics-influxdb
164* Ganglia - https://github.com/appscode/metlia
165* Prometheus - https://github.com/deathowl/go-metrics-prometheus
166* DataDog - https://github.com/syntaqx/go-metrics-datadog
167* SignalFX - https://github.com/pascallouisperez/go-metrics-signalfx
168* Honeycomb - https://github.com/getspine/go-metrics-honeycomb
169* Wavefront - https://github.com/wavefrontHQ/go-metrics-wavefront
170* Open-Falcon - https://github.com/g4zhuj/go-metrics-falcon
171* AWS CloudWatch - [https://github.com/savaki/cloudmetrics](https://github.com/savaki/cloudmetrics)
View as plain text