A Golang library for exporting performance and runtime metrics to external metrics systems (i.e. statsite, statsd)
Switch branches/tags
Nothing to show
Clone or download
banks Merge pull request #84 from uepoch/slash-prom
Add forward-slash as illegal character in prometheus
Latest commit f0300d1 Sep 17, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
circonus Adds support for labeled metrics and metrics filtering. Aug 7, 2017
datadog Adds support for labeled metrics and metrics filtering. Aug 7, 2017
prometheus Add forward-slash as illegal character in prometheus Sep 12, 2018
.gitignore fix permissions of files Jun 1, 2017
LICENSE Fixing permissions on files Jan 6, 2015
README.md Added more information about usage of AllowedLabels/BlockedLabels Jun 20, 2018
const_unix.go Use SIGBREAK for windows Jan 30, 2014
const_windows.go Use SIGBREAK for windows Jan 30, 2014
inmem.go allocate maps for current interval copy Nov 23, 2017
inmem_endpoint.go Change label display for inmem endpoint back to map Aug 8, 2017
inmem_endpoint_test.go count rate of the value, but not of the count Sep 19, 2017
inmem_signal.go Fix issue with label flattening Aug 9, 2017
inmem_signal_test.go Fix issue with label flattening Aug 9, 2017
inmem_test.go count rate of the value, but not of the count Sep 19, 2017
metrics.go Fixed comment, use bool instead of int for set semantics for global l… Jun 4, 2018
metrics_test.go Make it work properly + unit tests May 2, 2018
sink.go Adds support for labeled metrics and metrics filtering. Aug 7, 2017
sink_test.go Adds support for labeled metrics and metrics filtering. Aug 7, 2017
start.go Added more information about usage of AllowedLabels/BlockedLabels Jun 20, 2018
start_test.go Make it work properly + unit tests May 2, 2018
statsd.go Fix issue with label flattening Aug 9, 2017
statsd_test.go Adds support for labeled metrics and metrics filtering. Aug 7, 2017
statsite.go Adds support for labeled metrics and metrics filtering. Aug 7, 2017
statsite_test.go Adds support for labeled metrics and metrics filtering. Aug 7, 2017

README.md

go-metrics

This library provides a metrics package which can be used to instrument code, expose application metrics, and profile runtime performance in a flexible manner.

Current API: GoDoc

Sinks

The metrics package makes use of a MetricSink interface to support delivery to any type of backend. Currently the following sinks are provided:

  • StatsiteSink : Sinks to a statsite instance (TCP)
  • StatsdSink: Sinks to a StatsD / statsite instance (UDP)
  • PrometheusSink: Sinks to a Prometheus metrics endpoint (exposed via HTTP for scrapes)
  • InmemSink : Provides in-memory aggregation, can be used to export stats
  • FanoutSink : Sinks to multiple sinks. Enables writing to multiple statsite instances for example.
  • BlackholeSink : Sinks to nowhere

In addition to the sinks, the InmemSignal can be used to catch a signal, and dump a formatted output of recent metrics. For example, when a process gets a SIGUSR1, it can dump to stderr recent performance metrics for debugging.

Labels

Most metrics do have an equivalent ending with WithLabels, such methods allow to push metrics with labels and use some features of underlying Sinks (ex: translated into Prometheus labels).

Since some of these labels may increase greatly cardinality of metrics, the library allow to filter labels using a blacklist/whitelist filtering system which is global to all metrics.

  • 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.
  • If Config.BlockedLabels is not nil, any label specified in this value will not be sent to underlying Sinks.

By default, both Config.AllowedLabels and Config.BlockedLabels are nil, meaning that no tags are filetered at all, but it allow to a user to globally block some tags with high cardinality at application level.

Examples

Here is an example of using the package:

func SlowMethod() {
    // Profiling the runtime of a method
    defer metrics.MeasureSince([]string{"SlowMethod"}, time.Now())
}

// Configure a statsite sink as the global metrics sink
sink, _ := metrics.NewStatsiteSink("statsite:8125")
metrics.NewGlobal(metrics.DefaultConfig("service-name"), sink)

// Emit a Key/Value pair
metrics.EmitKey([]string{"questions", "meaning of life"}, 42)

Here is an example of setting up a signal handler:

// Setup the inmem sink and signal handler
inm := metrics.NewInmemSink(10*time.Second, time.Minute)
sig := metrics.DefaultInmemSignal(inm)
metrics.NewGlobal(metrics.DefaultConfig("service-name"), inm)

// Run some code
inm.SetGauge([]string{"foo"}, 42)
inm.EmitKey([]string{"bar"}, 30)

inm.IncrCounter([]string{"baz"}, 42)
inm.IncrCounter([]string{"baz"}, 1)
inm.IncrCounter([]string{"baz"}, 80)

inm.AddSample([]string{"method", "wow"}, 42)
inm.AddSample([]string{"method", "wow"}, 100)
inm.AddSample([]string{"method", "wow"}, 22)

....

When a signal comes in, output like the following will be dumped to stderr:

[2014-01-28 14:57:33.04 -0800 PST][G] 'foo': 42.000
[2014-01-28 14:57:33.04 -0800 PST][P] 'bar': 30.000
[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
[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