metrics

Documentation

Overview

Package metrics contains interfaces for generic metrics primitives, to facilitate mocking metrics in unit tests.

Most packages will want to use the types in this package, leaving the choice of metric implementation (e.g., Prometheus) to the application main function.

The types closely follow the Prometheus Go client library interfaces, for easy plugging of Prometheus metrics.

Index

• func CounterAdd(c Counter, delta float64)
• func CounterInc(c Counter)
• func CounterValue(c Counter) float64
• func GaugeAdd(g Gauge, delta float64)
• func GaugeInc(g Gauge)
• func GaugeSet(g Gauge, value float64)
• func GaugeSetCurrentTime(g Gauge)
• func GaugeSetTimestamp(g Gauge, ts time.Time)
• func GaugeValue(g Gauge) float64
• func HistogramObserve(h Histogram, value float64)
• type Counter
• type Gauge
• type Histogram
• type TestCounter
  • func NewTestCounter() *TestCounter
  • func (c *TestCounter) Add(delta float64)
• type TestGauge
  • func NewTestGauge() *TestGauge
  • func (g *TestGauge) Add(delta float64)
  • func (g *TestGauge) Set(v float64)

Examples

• Counter (Implementation)
• TestCounter (Labels)
• TestCounter (Simple)
• TestGauge (Labels)
• TestGauge (Simple)

Functions

func CounterAdd

func CounterAdd(c Counter, delta float64)

CounterAdd increases the passed in counter by the amount specified. This is a no-op if c is nil.

func CounterInc

func CounterInc(c Counter)

CounterInc increases the passed in counter by 1. This is a no-op if c is nil.

func CounterValue

func CounterValue(c Counter) float64

CounterValue extracts the value out of a TestCounter. If the argument is not a *TestCounter, CounterValue will panic.

func GaugeAdd

func GaugeAdd(g Gauge, delta float64)

GaugeAdd increases the passed in gauge by the amount specified. This is a no-op if g is nil.

func GaugeInc

func GaugeInc(g Gauge)

GaugeInc increases the passed in gauge by 1. This is a no-op if g is nil.

func GaugeSet

func GaugeSet(g Gauge, value float64)

GaugeSet sets the passed in gauge to the value specified. This is a no-op if g is nil.

func GaugeSetCurrentTime

func GaugeSetCurrentTime(g Gauge)

GaugeSetCurrentTime sets the passed gauge to the current time. This is a no-op if g is nil.

func GaugeSetTimestamp

func GaugeSetTimestamp(g Gauge, ts time.Time)

GaugeSetTimestamp sets the passed gauge to the specified time stamp. This is a no-op if g is nil.

func GaugeValue

func GaugeValue(g Gauge) float64

GaugeValue extracts the value out of a TestGauge. If the argument is not a *TestGauge, GaugeValue will panic.

func HistogramObserve

func HistogramObserve(h Histogram, value float64)

HistogramObserve adds an observation to the histogram. This is a no-op if h is nil.

Types

type Counter

type Counter interface {
	Add(delta float64)
}

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

Example (Implementation)

// LITERALINCLUDE ExampleCounter_Implementation START
type Giant struct {
	MagicBeansEaten metrics.Counter
	RedPillsEaten   metrics.Counter
	BluePillsEaten  metrics.Counter
}

counter := prometheus.NewCounter(prometheus.CounterOpts{
	Name: "magic_beans_eaten_total",
	Help: "Number of magic beans eaten.",
})
pillCounter := prometheus.NewCounterVec(prometheus.CounterOpts{
	Name: "pills_eaten_total",
	Help: "Number of pills eaten.",
}, []string{"color"})

giant := Giant{
	MagicBeansEaten: counter,
	RedPillsEaten:   pillCounter.WithLabelValues("red"),
	BluePillsEaten: pillCounter.With(prometheus.Labels{
		"color": "blue",
	}),
}
giant.MagicBeansEaten.Add(4)
giant.RedPillsEaten.Add(2)
giant.BluePillsEaten.Add(1)
// LITERALINCLUDE ExampleCounter_Implementation END

type Gauge

type Gauge interface {
	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

type Histogram interface {
	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 TestCounter

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

TestCounter implements a counter for use in tests.

Example (Labels)

// This example shows how to write a test with labels using a TestCounter.
type Server struct {
	RequestsHandledNormal metrics.Counter
	RequestsHandledError  metrics.Counter
	RequestsHandledAuth   metrics.Counter
}

Run := func(s *Server) {
	// server logic
	s.RequestsHandledNormal.Add(1)
	s.RequestsHandledNormal.Add(1)
	s.RequestsHandledAuth.Add(1)
}

s := &Server{
	RequestsHandledNormal: metrics.NewTestCounter(),
	RequestsHandledError:  metrics.NewTestCounter(),
	RequestsHandledAuth:   metrics.NewTestCounter(),
}
Run(s)

// Check metrics
fmt.Println(metrics.CounterValue(s.RequestsHandledNormal) == 2)
fmt.Println(metrics.CounterValue(s.RequestsHandledAuth) == 1)
fmt.Println(metrics.CounterValue(s.RequestsHandledError) == 0)

Output:

true
true
true

Example (Simple)

// This example shows how to write a simple test using a TestCounter.
type Server struct {
	RequestsHandled metrics.Counter
}

Run := func(s *Server) {
	// server logic
	s.RequestsHandled.Add(1)
	s.RequestsHandled.Add(1)
}

c := metrics.NewTestCounter()

s := &Server{
	RequestsHandled: c,
}
Run(s)

// Check metrics
fmt.Println(metrics.CounterValue(c) == 2)

Output:

true

func NewTestCounter

func NewTestCounter() *TestCounter

NewTestCounter creates a new counter for use in tests. See the examples for more information on how to use this.

func (*TestCounter) Add

func (c *TestCounter) Add(delta float64)

Add increases the internal value of the counter by the specified delta. Value can be negative.

type TestGauge

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

TestGauge implements a gauge for use in tests.

Example (Labels)

// For actual metrics initialization, labels would be fixed on construction.
var (
	httpGauge  = metrics.NewTestGauge()
	httpsGauge = metrics.NewTestGauge()
	otherGauge = metrics.NewTestGauge()
)
// This example shows how to write a test with labels using a TestGauge.
type Server struct {
	RunningWorkers func(typ string) metrics.Gauge
}

Run := func(s *Server) {
	// server logic
	s.RunningWorkers("http").Set(8)
	s.RunningWorkers("https").Set(5)
}

s := &Server{
	RunningWorkers: func(typ string) metrics.Gauge {
		switch typ {
		case "http":
			return httpGauge
		case "https":
			return httpsGauge
		default:
			return otherGauge
		}
	},
}
Run(s)

// Check metrics
fmt.Println(metrics.GaugeValue(httpGauge) == 8)
fmt.Println(metrics.GaugeValue(httpsGauge) == 5)
fmt.Println(metrics.GaugeValue(otherGauge) == 0)

Output:

true
true
true

Example (Simple)

// This example shows how to write a simple test using a TestGauge.
type Server struct {
	RequestsHandled metrics.Gauge
}

Run := func(s *Server) {
	// server logic
	s.RequestsHandled.Set(6)
}

g := metrics.NewTestGauge()

s := &Server{
	RequestsHandled: g,
}
Run(s)

// Check metrics
fmt.Println(metrics.GaugeValue(g) == 6)

Output:

true

func NewTestGauge

func NewTestGauge() *TestGauge

NewTestGauge creates a new gauge for use in tests. See the examples for more information on how to use this.

func (*TestGauge) Add

func (g *TestGauge) Add(delta float64)

Add increases the internal value of the gauge by the specified delta. The delta must be positive.

func (*TestGauge) Set

func (g *TestGauge) Set(v float64)

Set sets the internal value of the gauge to the specified value.