# 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"
"github.com/go-kit/kit/metrics/expvar"
)
func main() {
var myCount metrics.Counter
myCount = expvar.NewCounter("my_count")
myCount.Add(1)
}
A histogram for request duration, exported via a Prometheus summary with dynamically-computed quantiles.
import (
"time"
stdprometheus "github.com/prometheus/client_golang/prometheus"
"github.com/go-kit/kit/metrics"
"github.com/go-kit/kit/metrics/prometheus"
)
func main() {
var dur metrics.Histogram = prometheus.NewSummaryFrom(stdprometheus.SummaryOpts{
Namespace: "myservice",
Subsystem: "api",
Name: "request_duration_seconds",
Help: "Total time spent serving requests.",
}, []string{})
// ...
}
func handleRequest(dur metrics.Histogram) {
defer func(begin time.Time) { dur.Observe(time.Since(begin).Seconds()) }(time.Now())
// handle request
}
A gauge for the number of goroutines currently running, exported via StatsD.
import (
"context"
"net"
"os"
"runtime"
"time"
"github.com/go-kit/kit/metrics"
"github.com/go-kit/kit/metrics/statsd"
)
func main() {
statsd := statsd.New("foo_svc.", log.NewNopLogger())
report := time.NewTicker(5 * time.Second)
defer report.Stop()
go statsd.SendLoop(context.Background(), report.C, "tcp", "statsd.internal:8125")
goroutines := statsd.NewGauge("goroutine_count")
go exportGoroutines(goroutines)
// ...
}
func exportGoroutines(g metrics.Gauge) {
for range time.Tick(time.Second) {
g.Set(float64(runtime.NumGoroutine()))
}
}
For more information, see the package documentation.
# Packages
Package cloudwatch2 emits all data as a StatisticsSet (rather than a singular Value) to CloudWatch via the aws-sdk-go-v2 SDK.
Package discard provides a no-op metrics backend.
Package dogstatsd provides a DogStatsD backend for package metrics.
Package expvar provides expvar backends for metrics.
Package generic implements generic versions of each of the metric types.
Package graphite provides a Graphite backend for metrics.
Package influx provides an InfluxDB implementation for metrics.
Package influxstatsd provides support for InfluxData's StatsD Telegraf plugin.
Package multi provides adapters that send observations to multiple metrics simultaneously.
Package prometheus provides Prometheus implementations for metrics.
Package provider provides a factory-like abstraction for metrics backends.
Package statsd provides a StatsD backend for package metrics.
Package teststat provides helpers for testing metrics backends.
# Functions
NewTimer wraps the given histogram and records the current time.
# Interfaces
Counter describes a metric that accumulates values monotonically.
Gauge describes a metric that takes specific values over time.
Histogram describes a metric that takes repeated observations of the same kind of thing, and produces a statistical summary of those observations, typically expressed as quantiles or buckets.