1 // Package dogstatsd provides a DogStatsD backend for package metrics. It's very
2 // similar to StatsD, but supports arbitrary tags per-metric, which map to Go
3 // kit's label values. So, while label values are no-ops in StatsD, they are
4 // supported here. For more details, see the documentation at
5 // http://docs.datadoghq.com/guides/dogstatsd/.
7 // This package batches observations and emits them on some schedule to the
8 // remote server. This is useful even if you connect to your DogStatsD server
9 // over UDP. Emitting one network packet per observation can quickly overwhelm
10 // even the fastest internal network.
21 "github.com/go-kit/kit/log"
22 "github.com/go-kit/kit/metrics"
23 "github.com/go-kit/kit/metrics/generic"
24 "github.com/go-kit/kit/metrics/internal/lv"
25 "github.com/go-kit/kit/metrics/internal/ratemap"
26 "github.com/go-kit/kit/util/conn"
29 // Dogstatsd receives metrics observations and forwards them to a DogStatsD
30 // server. Create a Dogstatsd object, use it to create metrics, and pass those
31 // metrics as dependencies to the components that will use them.
33 // All metrics are buffered until WriteTo is called. Counters and gauges are
34 // aggregated into a single observation per timeseries per write. Timings and
35 // histograms are buffered but not aggregated.
37 // To regularly report metrics to an io.Writer, use the WriteLoop helper method.
38 // To send to a DogStatsD server, use the SendLoop helper method.
39 type Dogstatsd struct {
42 rates *ratemap.RateMap
44 gauges map[string]*gaugeNode
51 // New returns a Dogstatsd object that may be used to create metrics. Prefix is
52 // applied to all created metrics. Callers must ensure that regular calls to
53 // WriteTo are performed, either manually or with one of the helper methods.
54 func New(prefix string, logger log.Logger, lvs ...string) *Dogstatsd {
56 panic("odd number of LabelValues; programmer error!")
61 counters: lv.NewSpace(),
62 gauges: map[string]*gaugeNode{},
63 timings: lv.NewSpace(),
64 histograms: lv.NewSpace(),
70 // NewCounter returns a counter, sending observations to this Dogstatsd object.
71 func (d *Dogstatsd) NewCounter(name string, sampleRate float64) *Counter {
72 d.rates.Set(name, sampleRate)
75 obs: d.counters.Observe,
79 // NewGauge returns a gauge, sending observations to this Dogstatsd object.
80 func (d *Dogstatsd) NewGauge(name string) *Gauge {
82 n, ok := d.gauges[name]
84 n = &gaugeNode{gauge: &Gauge{g: generic.NewGauge(name), ddog: d}}
91 // NewTiming returns a histogram whose observations are interpreted as
92 // millisecond durations, and are forwarded to this Dogstatsd object.
93 func (d *Dogstatsd) NewTiming(name string, sampleRate float64) *Timing {
94 d.rates.Set(name, sampleRate)
97 obs: d.timings.Observe,
101 // NewHistogram returns a histogram whose observations are of an unspecified
102 // unit, and are forwarded to this Dogstatsd object.
103 func (d *Dogstatsd) NewHistogram(name string, sampleRate float64) *Histogram {
104 d.rates.Set(name, sampleRate)
107 obs: d.histograms.Observe,
111 // WriteLoop is a helper method that invokes WriteTo to the passed writer every
112 // time the passed channel fires. This method blocks until the channel is
113 // closed, so clients probably want to run it in its own goroutine. For typical
114 // usage, create a time.Ticker and pass its C channel to this method.
115 func (d *Dogstatsd) WriteLoop(c <-chan time.Time, w io.Writer) {
117 if _, err := d.WriteTo(w); err != nil {
118 d.logger.Log("during", "WriteTo", "err", err)
123 // SendLoop is a helper method that wraps WriteLoop, passing a managed
124 // connection to the network and address. Like WriteLoop, this method blocks
125 // until the channel is closed, so clients probably want to start it in its own
126 // goroutine. For typical usage, create a time.Ticker and pass its C channel to
128 func (d *Dogstatsd) SendLoop(c <-chan time.Time, network, address string) {
129 d.WriteLoop(c, conn.NewDefaultManager(network, address, d.logger))
132 // WriteTo flushes the buffered content of the metrics to the writer, in
133 // DogStatsD format. WriteTo abides best-effort semantics, so observations are
134 // lost if there is a problem with the write. Clients should be sure to call
135 // WriteTo regularly, ideally through the WriteLoop or SendLoop helper methods.
136 func (d *Dogstatsd) WriteTo(w io.Writer) (count int64, err error) {
139 d.counters.Reset().Walk(func(name string, lvs lv.LabelValues, values []float64) bool {
140 n, err = fmt.Fprintf(w, "%s%s:%f|c%s%s\n", d.prefix, name, sum(values), sampling(d.rates.Get(name)), d.tagValues(lvs))
152 for _, root := range d.gauges {
153 root.walk(func(name string, lvs lv.LabelValues, value float64) bool {
154 n, err = fmt.Fprintf(w, "%s%s:%f|g%s\n", d.prefix, name, value, d.tagValues(lvs))
164 d.timings.Reset().Walk(func(name string, lvs lv.LabelValues, values []float64) bool {
165 sampleRate := d.rates.Get(name)
166 for _, value := range values {
167 n, err = fmt.Fprintf(w, "%s%s:%f|ms%s%s\n", d.prefix, name, value, sampling(sampleRate), d.tagValues(lvs))
179 d.histograms.Reset().Walk(func(name string, lvs lv.LabelValues, values []float64) bool {
180 sampleRate := d.rates.Get(name)
181 for _, value := range values {
182 n, err = fmt.Fprintf(w, "%s%s:%f|h%s%s\n", d.prefix, name, value, sampling(sampleRate), d.tagValues(lvs))
197 func sum(a []float64) float64 {
199 for _, f := range a {
205 func last(a []float64) float64 {
209 func sampling(r float64) string {
212 sv = fmt.Sprintf("|@%f", r)
217 func (d *Dogstatsd) tagValues(labelValues []string) string {
218 if len(labelValues) == 0 && len(d.lvs) == 0 {
221 if len(labelValues)%2 != 0 {
222 panic("tagValues received a labelValues with an odd number of strings")
224 pairs := make([]string, 0, (len(d.lvs)+len(labelValues))/2)
225 for i := 0; i < len(d.lvs); i += 2 {
226 pairs = append(pairs, d.lvs[i]+":"+d.lvs[i+1])
228 for i := 0; i < len(labelValues); i += 2 {
229 pairs = append(pairs, labelValues[i]+":"+labelValues[i+1])
231 return "|#" + strings.Join(pairs, ",")
234 type observeFunc func(name string, lvs lv.LabelValues, value float64)
236 // Counter is a DogStatsD counter. Observations are forwarded to a Dogstatsd
237 // object, and aggregated (summed) per timeseries.
238 type Counter struct {
244 // With implements metrics.Counter.
245 func (c *Counter) With(labelValues ...string) metrics.Counter {
248 lvs: c.lvs.With(labelValues...),
253 // Add implements metrics.Counter.
254 func (c *Counter) Add(delta float64) {
255 c.obs(c.name, c.lvs, delta)
258 // Gauge is a DogStatsD gauge. Observations are forwarded to a Dogstatsd
259 // object, and aggregated (the last observation selected) per timeseries.
266 // With implements metrics.Gauge.
267 func (g *Gauge) With(labelValues ...string) metrics.Gauge {
269 node := g.ddog.gauges[g.g.Name]
272 ga := &Gauge{g: g.g.With(labelValues...).(*generic.Gauge), ddog: g.ddog}
273 return node.addGauge(ga, ga.g.LabelValues())
276 // Set implements metrics.Gauge.
277 func (g *Gauge) Set(value float64) {
282 // Add implements metrics.Gauge.
283 func (g *Gauge) Add(delta float64) {
288 // Timing is a DogStatsD timing, or metrics.Histogram. Observations are
289 // forwarded to a Dogstatsd object, and collected (but not aggregated) per
297 // With implements metrics.Timing.
298 func (t *Timing) With(labelValues ...string) metrics.Histogram {
301 lvs: t.lvs.With(labelValues...),
306 // Observe implements metrics.Histogram. Value is interpreted as milliseconds.
307 func (t *Timing) Observe(value float64) {
308 t.obs(t.name, t.lvs, value)
311 // Histogram is a DogStatsD histrogram. Observations are forwarded to a
312 // Dogstatsd object, and collected (but not aggregated) per timeseries.
313 type Histogram struct {
319 // With implements metrics.Histogram.
320 func (h *Histogram) With(labelValues ...string) metrics.Histogram {
323 lvs: h.lvs.With(labelValues...),
328 // Observe implements metrics.Histogram.
329 func (h *Histogram) Observe(value float64) {
330 h.obs(h.name, h.lvs, value)
333 type pair struct{ label, value string }
335 type gaugeNode struct {
338 children map[pair]*gaugeNode
341 func (n *gaugeNode) addGauge(g *Gauge, lvs lv.LabelValues) *Gauge {
351 panic("too few LabelValues; programmer error!")
353 head, tail := pair{lvs[0], lvs[1]}, lvs[2:]
354 if n.children == nil {
355 n.children = map[pair]*gaugeNode{}
357 child, ok := n.children[head]
360 n.children[head] = child
362 return child.addGauge(g, tail)
365 func (n *gaugeNode) walk(fn func(string, lv.LabelValues, float64) bool) bool {
367 defer n.mtx.RUnlock()
369 value, ok := n.gauge.read()
370 if ok && !fn(n.gauge.g.Name, n.gauge.g.LabelValues(), value) {
374 for _, child := range n.children {
382 func (g *Gauge) touch() {
383 atomic.StoreInt32(&(g.set), 1)
386 func (g *Gauge) read() (float64, bool) {
387 set := atomic.SwapInt32(&(g.set), 0)
388 return g.g.Value(), set != 0