metrics

README

metrics

A Go library which provides light-weight instrumentation for your application.

For documentation, check godoc.

Documentation

Overview

Package metrics provides minimalist instrumentation for your applications in the form of counters and gauges.

Counters

A counter is a monotonically-increasing, unsigned, 64-bit integer used to represent 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.

Gauges

A gauge returns instantaneous measurements of something using signed, 64-bit integers. This value does not need to be monotonic.

Histograms

A histogram tracks the distribution of a stream of values (e.g. the number of milliseconds it takes to handle requests), adding gauges for the values at meaningful quantiles: 50th, 75th, 90th, 95th, 99th, 99.9th.

Reporting

Measurements from counters and gauges are available as expvars. Your service should return its expvars from an HTTP endpoint (i.e., /debug/vars) as a JSON object.

Index

• func Reset()
• func Snapshot() (c map[string]uint64, g map[string]int64)
• type Counter
  • func (c Counter) Add()
  • func (c Counter) AddN(delta uint64)
  • func (c Counter) Remove()
  • func (c Counter) SetBatchFunc(key interface{}, init func(), f func() uint64)
  • func (c Counter) SetFunc(f func() uint64)
• type Error
  • func (e Error) Error() string
• type Gauge
  • func (g Gauge) Remove()
  • func (g Gauge) Set(value int64)
  • func (g Gauge) SetBatchFunc(key interface{}, init func(), f func() int64)
  • func (g Gauge) SetFunc(f func() int64)
• type Histogram
  • func NewHistogram(name string, minValue, maxValue int64, sigfigs int) *Histogram
  • func (h *Histogram) Name() string
  • func (h *Histogram) RecordValue(v int64) error
  • func (h *Histogram) Remove()

Functions

func Reset

func Reset()

Reset removes all existing counters and gauges.

func Snapshot

func Snapshot() (c map[string]uint64, g map[string]int64)

Snapshot returns a copy of the values of all registered counters and gauges.

Types

type Counter

type Counter string

A Counter is a monotonically increasing unsigned integer.

Use a counter to derive rates (e.g., record total number of requests, derive requests per second).

func (Counter) Add

func (c Counter) Add()

Add increments the counter by one.

func (Counter) AddN

func (c Counter) AddN(delta uint64)

AddN increments the counter by N.

func (Counter) Remove

func (c Counter) Remove()

Remove removes the given counter.

func (Counter) SetBatchFunc

func (c Counter) SetBatchFunc(key interface{}, init func(), f func() uint64)

SetBatchFunc sets the counter's value to the lazily-called return value of the given function, with an additional initializer function for a related batch of counters, all of which are keyed by an arbitrary value.

func (Counter) SetFunc

func (c Counter) SetFunc(f func() uint64)

SetFunc sets the counter's value to the lazily-called return value of the given function.

type Error

type Error struct {
	Metric string
	Err    error
}

Error describes an error and the name of the metric where it occurred.

func (Error) Error

func (e Error) Error() string

type Gauge

type Gauge string

A Gauge is an instantaneous measurement of a value.

Use a gauge to track metrics which increase and decrease (e.g., amount of free memory).

func (Gauge) Remove

func (g Gauge) Remove()

Remove removes the given gauge.

func (Gauge) Set

func (g Gauge) Set(value int64)

Set the gauge's value to the given value.

func (Gauge) SetBatchFunc

func (g Gauge) SetBatchFunc(key interface{}, init func(), f func() int64)

SetBatchFunc sets the gauge's value to the lazily-called return value of the given function, with an additional initializer function for a related batch of gauges, all of which are keyed by an arbitrary value.

func (Gauge) SetFunc

func (g Gauge) SetFunc(f func() int64)

SetFunc sets the gauge's value to the lazily-called return value of the given function.

type Histogram

type Histogram struct {
	// contains filtered or unexported fields
}

A Histogram measures the distribution of a stream of values.

func NewHistogram

func NewHistogram(name string, minValue, maxValue int64, sigfigs int) *Histogram

NewHistogram returns a windowed HDR histogram which drops data older than five minutes. The returned histogram is safe to use from multiple goroutines.

Use a histogram to track the distribution of a stream of values (e.g., the latency associated with HTTP requests).

func (*Histogram) Name

func (h *Histogram) Name() string

Name returns the name of the histogram

func (*Histogram) RecordValue

func (h *Histogram) RecordValue(v int64) error

RecordValue records the given value, or returns an error if the value is out of range. Returned error values are of type Error.

func (*Histogram) Remove

func (h *Histogram) Remove()

Remove removes the given histogram.