kit: Index | Files | Directories

package metrics

import ""

Package metrics provides a framework for application instrumentation. It's primarily designed to help you get started with good and robust instrumentation, and to help you migrate from a less-capable system like Graphite to a more-capable system like Prometheus. If your organization has already standardized on an instrumentation system like Prometheus, and has no plans to change, it may make sense to use that system's instrumentation library directly.

This package provides three core metric abstractions (Counter, Gauge, and Histogram) and implementations for almost all common instrumentation backends. Each metric has an observation method (Add, Set, or Observe, respectively) used to record values, and a With method to "scope" the observation by various parameters. For example, you might have a Histogram to record request durations, parameterized by the method that's being called.

var requestDuration metrics.Histogram
// ...
requestDuration.With("method", "MyMethod").Observe(time.Since(begin))

This allows a single high-level metrics object (requestDuration) to work with many code paths somewhat dynamically. The concept of With is fully supported in some backends like Prometheus, and not supported in other backends like Graphite. So, With may be a no-op, depending on the concrete implementation you choose. Please check the implementation to know for sure. For implementations that don't provide With, it's necessary to fully parameterize each metric in the metric name, e.g.

// Statsd
c := statsd.NewCounter("request_duration_MyMethod_200")

// Prometheus
c := prometheus.NewCounter(stdprometheus.CounterOpts{
    Name: "request_duration",
}, []string{"method", "status_code"})
c.With("method", "MyMethod", "status_code", strconv.Itoa(code)).Add(1)


Metrics are dependencies, and should be passed to the components that need them in the same way you'd construct and pass a database handle, or reference to another component. Metrics should *not* be created in the global scope. Instead, instantiate metrics in your func main, using whichever concrete implementation is appropriate for your organization.

latency := prometheus.NewSummaryFrom(stdprometheus.SummaryOpts{
    Namespace: "myteam",
    Subsystem: "foosvc",
    Name:      "request_latency_seconds",
    Help:      "Incoming request latency in seconds.",
}, []string{"method", "status_code"})

Write your components to take the metrics they will use as parameters to their constructors. Use the interface types, not the concrete types. That is,

// NewAPI takes metrics.Histogram, not *prometheus.Summary
func NewAPI(s Store, logger log.Logger, latency metrics.Histogram) *API {
    // ...

func (a *API) ServeFoo(w http.ResponseWriter, r *http.Request) {
    begin := time.Now()
    // ...

Finally, pass the metrics as dependencies when building your object graph. This should happen in func main, not in the global scope.

api := NewAPI(store, logger, latency)
http.ListenAndServe("/", api)

Note that metrics are "write-only" interfaces.

Implementation details

All metrics are safe for concurrent use. Considerable design influence has been taken from and

Each telemetry system has different semantics for label values, push vs. pull, support for histograms, etc. These properties influence the design of their respective packages. This table attempts to summarize the key points of distinction.

SYSTEM      DIM  COUNTERS               GAUGES                 HISTOGRAMS
dogstatsd   n    batch, push-aggregate  batch, push-aggregate  native, batch, push-each
statsd      1    batch, push-aggregate  batch, push-aggregate  native, batch, push-each
graphite    1    batch, push-aggregate  batch, push-aggregate  synthetic, batch, push-aggregate
expvar      1    atomic                 atomic                 synthetic, batch, in-place expose
influx      n    custom                 custom                 custom
prometheus  n    native                 native                 native
pcp         1    native                 native                 native
cloudwatch  n    batch push-aggregate   batch push-aggregate   synthetic, batch, push-aggregate


Package Files

doc.go metrics.go timer.go

type Counter Uses

type Counter interface {
    With(labelValues ...string) Counter
    Add(delta float64)

Counter describes a metric that accumulates values monotonically. An example of a counter is the number of received HTTP requests.

type Gauge Uses

type Gauge interface {
    With(labelValues ...string) Gauge
    Set(value float64)
    Add(delta float64)

Gauge describes a metric that takes specific values over time. An example of a gauge is the current depth of a job queue.

type Histogram Uses

type Histogram interface {
    With(labelValues ...string) Histogram
    Observe(value float64)

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. An example of a histogram is HTTP request latencies.

type Timer Uses

type Timer struct {
    // contains filtered or unexported fields

Timer acts as a stopwatch, sending observations to a wrapped histogram. It's a bit of helpful syntax sugar for h.Observe(time.Since(x)).

func NewTimer Uses

func NewTimer(h Histogram) *Timer

NewTimer wraps the given histogram and records the current time.

func (*Timer) ObserveDuration Uses

func (t *Timer) ObserveDuration()

ObserveDuration captures the number of seconds since the timer was constructed, and forwards that observation to the histogram.

func (*Timer) Unit Uses

func (t *Timer) Unit(u time.Duration)

Unit sets the unit of the float64 emitted by the timer. By default, the timer emits seconds.


cloudwatch2Package cloudwatch2 emits all data as a StatisticsSet (rather than a singular Value) to CloudWatch via the aws-sdk-go-v2 SDK.
discardPackage discard provides a no-op metrics backend.
dogstatsdPackage dogstatsd provides a DogStatsD backend for package metrics.
expvarPackage expvar provides expvar backends for metrics.
genericPackage generic implements generic versions of each of the metric types.
graphitePackage graphite provides a Graphite backend for metrics.
influxPackage influx provides an InfluxDB implementation for metrics.
influxstatsdPackage influxstatsd provides support for InfluxData's StatsD Telegraf plugin.
internal/convertPackage convert provides a way to use Counters, Histograms, or Gauges as one of the other types
internal/ratemapPackage ratemap implements a goroutine-safe map of string to float64.
multiPackage multi provides adapters that send observations to multiple metrics simultaneously.
prometheusPackage prometheus provides Prometheus implementations for metrics.
providerPackage provider provides a factory-like abstraction for metrics backends.
statsdPackage statsd provides a StatsD backend for package metrics.
teststatPackage teststat provides helpers for testing metrics backends.

Package metrics imports 1 packages (graph) and is imported by 1747 packages. Updated 2020-09-15. Refresh now. Tools for package owners.