Metrics Library for Go

A library that provides an interface for sending metrics from your script, application, or service. Metrics consist of a name, value, and optionally some tags that are made up of key/value pairs.

Multiple implementations are provided to allow for production, local development, and testing use cases. The following clients are available:

Client	Description
LoggerClient	Writes metrics into a log stream. Useful when running locally.
DataDogClient	Writes metrics into DataDog. Useful for production.
NullClient	Acts like a mock that does nothing. Useful for testing.
RecorderClient	Writes metrics into memory and provides a query interface. Useful for testing.

Example Usage

Generally you will instantiate one of the above clients and then write metrics to it. First, install the library:

# If using dep, glide, godep, etc then use that tool. For example:
dep ensure github.com/istreamlabs/go-metrics

# Otherwise, just go get it:
go get github.com/istreamlabs/go-metrics/metrics

Then you can use it:

import "github.com/istreamlabs/go-metrics/metrics"

var client metrics.Client
if os.Getenv("env") == "prod" {
  client = metrics.NewDataDogClient("127.0.0.1:8125", "myprefix")
} else {
  // Log to standard out instead of sending production metrics.
  client = metrics.NewLoggerClient(nil)
}
defer client.Close()

// Simple incrementing counter
client.Incr("requests.count")

// Tagging with counters
client.WithTags(map[string]string{
  "tag": "value"
}).Incr("requests.count")

The above code would result in myprefix.requests.count with a value of 1 showing up in DataDog if you have dogstatsd running locally and an environment variable env set to prod, otherwise it will print metrics to standard out. See the Client interface for a list of available metrics methods.

Sometimes you wouldn't want to send a metric every single time a piece of code is executed. This is supported by setting a sample rate:

// Sample rate for high-throughput applications
client.WithRate(0.01).Incr("requests.count")

Sample rates apply to metrics but not events. Any count-type metric (Incr, Decr, Count, and timing/histogram counts) will get multiplied to the full value, while gauges are sent unmodified. For example, when emitting a 10% sampled timing metric that takes an average of 200ms to DataDog, you would see 1 call * (1/0.1 sample rate) = 10 calls added to the histogram count while the average value remains 200ms in the DataDog UI.

Also provided are useful clients for testing. For example, the following asserts that a metric with the given name, value, and tag was emitted during a test:

func TestFoo(t *testing.T)
  client := metrics.NewRecorderClient().WithTest(t)

  client.WithTags(map[string]string{
    "tag": "value",
  }).Count("requests.count", 1)

  // Now, assert that the metric was emitted.
  client.
    Expect("requests.count").
    Value(1).
    Tag("tag", "value")
}

For more information and examples, see the godocs.

License

Copyright © 2017 iStreamPlanet Co., LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.