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

Code instrumentation is absolutely essential to achieve observability into a distributed system. Metrics and instrumentation tools have coalesced around a few well-defined idioms. package metrics provides a common, minimal interface those idioms for service authors.

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 {
		panic(err)
	}

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

Documentation

Overview

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

Index

• func PrintDistribution(w io.Writer, h Histogram)
• type Bucket
• type Counter
  • func NewMultiCounter(name string, counters ...Counter) Counter
• type Field
• type Gauge
  • func NewMultiGauge(name string, gauges ...Gauge) Gauge
• type Histogram
  • func NewMultiHistogram(name string, histograms ...Histogram) Histogram
  • func NewScaledHistogram(h Histogram, scale int64) Histogram
• type Quantile
• type TimeHistogram
  • func NewTimeHistogram(unit time.Duration, h Histogram) TimeHistogram

Functions

func PrintDistribution

func PrintDistribution(w io.Writer, h Histogram)

PrintDistribution writes a human-readable graph of the distribution to the passed writer.

Types

type Bucket

type Bucket struct {
	From  int64
	To    int64
	Count int64
}

Bucket is a range in a histogram which aggregates observations.

type Counter

type Counter interface {
	Name() string
	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(name string, 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 {
	Name() string
	With(Field) Gauge
	Set(value float64)
	Add(delta float64)
	Get() float64
}

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

func NewMultiGauge

func NewMultiGauge(name string, gauges ...Gauge) Gauge

NewMultiGauge returns a wrapper around multiple Gauges.

type Histogram

type Histogram interface {
	Name() string
	With(Field) Histogram
	Observe(value int64)
	Distribution() ([]Bucket, []Quantile)
}

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(name string, 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 Quantile

type Quantile struct {
	Quantile int // 0..100
	Value    int64
}

Quantile is a pair of quantile (0..100) and its observed maximum value.

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.