metrics

README

package metrics

package metrics provides a set of uniform interfaces for service instrumentation. It has counters, gauges, and histograms, and provides adapters to popular metrics packages, like expvar, statsd, and Prometheus.

Rationale

TODO

Usage

A simple counter, exported via expvar.

import "github.com/go-kit/kit/metrics/expvar"

func main() {
	myCount := expvar.NewCounter("my_count")
	myCount.Add(1)
}

A histogram for request duration, exported via a Prometheus summary with dynamically-computed quantiles.

import (
	stdprometheus "github.com/prometheus/client_golang/prometheus"

	"github.com/go-kit/kit/metrics"
	"github.com/go-kit/kit/metrics/prometheus"
)

var requestDuration = prometheus.NewSummary(stdprometheus.SummaryOpts{
	Namespace: "myservice",
	Subsystem: "api",
	Name:      "request_duration_nanoseconds_count",
	Help:      "Total time spent serving requests.",
}, []string{})

func handleRequest() {
	defer func(begin time.Time) { requestDuration.Observe(time.Since(begin)) }(time.Now())
	// handle request
}

A gauge for the number of goroutines currently running, exported via statsd.

import (
	"net"
	"os"
	"runtime"
	"time"

	"github.com/go-kit/kit/metrics/statsd"
)

func main() {
	statsdWriter, err := net.Dial("udp", "127.0.0.1:8126")
	if err != nil {
		os.Exit(1)
	}

	reportingDuration := 5 * time.Second
	goroutines := statsd.NewGauge(statsdWriter, "total_goroutines", reportingDuration)
	for range time.Tick(reportingDuration) {
		goroutines.Set(float64(runtime.NumGoroutine()))
	}
}

Documentation

Overview

Package metrics provides an extensible framework to instrument your application. All metrics are safe for concurrent use. Considerable design influence has been taken from https://github.com/codahale/metrics and https://prometheus.io.

Index

• type Counter
  • func NewMultiCounter(counters ...Counter) Counter
• type Field
• type Gauge
  • func NewMultiGauge(gauges ...Gauge) Gauge
• type Histogram
  • func NewMultiHistogram(histograms ...Histogram) Histogram
  • func NewScaledHistogram(h Histogram, scale int64) Histogram
• type TimeHistogram
  • func NewTimeHistogram(unit time.Duration, h Histogram) TimeHistogram

Types

type Counter

type Counter interface {
	With(Field) Counter
	Add(delta uint64)
}

Counter is a monotonically-increasing, unsigned, 64-bit integer used to capture the number of times an event has occurred. By tracking the deltas between measurements of a counter over intervals of time, an aggregation layer can derive rates, acceleration, etc.

func NewMultiCounter

func NewMultiCounter(counters ...Counter) Counter

NewMultiCounter returns a wrapper around multiple Counters.

type Field

type Field struct {
	Key   string
	Value string
}

Field is a key/value pair associated with an observation for a specific metric. Fields may be ignored by implementations.

type Gauge

type Gauge interface {
	With(Field) Gauge
	Set(value float64)
	Add(delta float64)
}

Gauge captures instantaneous measurements of something using signed, 64-bit floats. The value does not need to be monotonic.

func NewMultiGauge

func NewMultiGauge(gauges ...Gauge) Gauge

NewMultiGauge returns a wrapper around multiple Gauges.

type Histogram

type Histogram interface {
	With(Field) Histogram
	Observe(value int64)
}

Histogram tracks the distribution of a stream of values (e.g. the number of milliseconds it takes to handle requests). Implementations may choose to add gauges for values at meaningful quantiles.

func NewMultiHistogram

func NewMultiHistogram(histograms ...Histogram) Histogram

NewMultiHistogram returns a wrapper around multiple Histograms.

func NewScaledHistogram

func NewScaledHistogram(h Histogram, scale int64) Histogram

NewScaledHistogram returns a Histogram whose observed values are downscaled (divided) by scale.

type TimeHistogram

type TimeHistogram interface {
	With(Field) TimeHistogram
	Observe(time.Duration)
}

TimeHistogram is a convenience wrapper for a Histogram of time.Durations.

func NewTimeHistogram

func NewTimeHistogram(unit time.Duration, h Histogram) TimeHistogram

NewTimeHistogram returns a TimeHistogram wrapper around the passed Histogram, in units of unit.