Debian Codegraph @

README.md

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