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 are taken from the metrics interfaces in the go-kit/kit project (see https://github.com/go-kit/kit). See https://godoc.org/github.com/go-kit/kit/metrics for more information about the reasoning behind the types, and examples of how they can be used. See this source file for the full license attribution.

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)
• func Timestamp(ts time.Time) float64
• type Counter
  • func CounterWith(c Counter, labelValues ...string) Counter
  • func NewPromCounter(cv *prometheus.CounterVec) Counter
  • func NewPromCounterFrom(opts prometheus.CounterOpts, labelNames []string) Counter
• type Gauge
  • func GaugeWith(g Gauge, labelValues ...string) Gauge
  • func NewPromGauge(gv *prometheus.GaugeVec) Gauge
• type Histogram
  • func HistogramWith(h Histogram, labelValues ...string) Histogram
  • func NewPromHistogram(hv *prometheus.HistogramVec) Histogram
  • func NewPromHistogramFrom(opts prometheus.HistogramOpts, labelNames []string) Histogram
• type TestCounter
  • func NewTestCounter() *TestCounter
  • func (c *TestCounter) Add(delta float64)
  • func (c *TestCounter) With(labels ...string) Counter
• type TestGauge
  • func NewTestGauge() *TestGauge
  • func (g *TestGauge) Add(delta float64)
  • func (g *TestGauge) Set(v float64)
  • func (g *TestGauge) With(labels ...string) Gauge

Examples

• Counter (Implementation)
• Counter (Interface)
• 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.

func Timestamp

func Timestamp(ts time.Time) float64

Timestamp expresses a timestamp in seconds since UNIX epoch.

Types

type Counter

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.

Example (Implementation)

package main

import (
	stdprometheus "github.com/prometheus/client_golang/prometheus"

	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// LITERALINCLUDE ExampleCounter_Implementation START
	type Giant struct {
		MagicBeansEaten metrics.Counter
	}

	counter := metrics.NewPromCounterFrom(stdprometheus.CounterOpts{
		Name: "magic_beans_eaten_total",
		Help: "Number of magic beans eaten.",
	}, nil)

	giant := Giant{
		MagicBeansEaten: counter,
	}
	giant.MagicBeansEaten.Add(4)
	// LITERALINCLUDE ExampleCounter_Implementation END
}

Example (Interface)

package main

import (
	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// LITERALINCLUDE ExampleCounter_Interface START
	type Giant struct {
		MagicBeansEaten metrics.Counter
	}

	type BeanLabels struct {
		Color string // can be "blue" or "orange"
	}

	// Use a func for this to be displayed properly in the godoc, but this should be a method.
	Expand := func(labels BeanLabels) []string {
		// converts labels to a slice of strings
		return []string{"color", labels.Color}
	}

	giant := Giant{}
	labels := BeanLabels{Color: "orange"}
	counter := giant.MagicBeansEaten.With(Expand(labels)...)
	counter.Add(4)
	// LITERALINCLUDE ExampleCounter_Interface END
}

func CounterWith

func CounterWith(c Counter, labelValues ...string) Counter

CounterWith returns a Counter with the labels provided. Returns nil if c is nil.

func NewPromCounter

func NewPromCounter(cv *prometheus.CounterVec) Counter

NewPromCounter wraps a prometheus counter vector as a counter. Returns nil if cv is nil.

func NewPromCounterFrom

func NewPromCounterFrom(opts prometheus.CounterOpts, labelNames []string) Counter

NewPromCounterFrom creates a wrapped prometheus counter.

type Gauge

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.

func GaugeWith

func GaugeWith(g Gauge, labelValues ...string) Gauge

GaugeWith returns a Gauge with the labels provided. Returns nil if g is nil.

func NewPromGauge

func NewPromGauge(gv *prometheus.GaugeVec) Gauge

NewPromGauge wraps a prometheus gauge vector as a gauge. Returns nil, if gv is nil.

type Histogram

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.

func HistogramWith

func HistogramWith(h Histogram, labelValues ...string) Histogram

HistogramWith returns a Histogram with the labels provided. Returns nil if h is nil.

func NewPromHistogram

func NewPromHistogram(hv *prometheus.HistogramVec) Histogram

NewPromHistogram wraps a prometheus histogram vector as a histogram. Returns nil if hv is nil.

func NewPromHistogramFrom

func NewPromHistogramFrom(opts prometheus.HistogramOpts, labelNames []string) Histogram

NewPromHistogramFrom creates a wrapped prometheus histogram.

type TestCounter

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

TestCounter implements a counter for use in tests.

Each newly created TestCounter is a stand-alone label namespace. That means time-series behave as expected, e.g., creating two counters with the same labels by calling With will yield counters that represent the same time-series. The examples illustrate how this can be used to write a simple test.

Example (Labels)

package main

import (
	"fmt"

	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// This example shows how to write a test with labels using a TestCounter.
	type Server struct {
		RequestsHandled metrics.Counter
	}

	Run := func(s *Server) {
		// server logic
		s.RequestsHandled.With("type", "normal").Add(1)
		s.RequestsHandled.With("type", "normal").Add(1)
		s.RequestsHandled.With("type", "authenticated").Add(1)
	}

	c := metrics.NewTestCounter()

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

	// Check metrics
	fmt.Println(metrics.CounterValue(c.With("type", "normal")) == 2)
	fmt.Println(metrics.CounterValue(c.With("type", "authenticated")) == 1)
	fmt.Println(metrics.CounterValue(c.With("type", "error")) == 0)
}

Output:

true
true
true

Example (Simple)

package main

import (
	"fmt"

	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// 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.

func (*TestCounter) With

func (c *TestCounter) With(labels ...string) Counter

With creates a new counter that includes the specified labels in addition to any labels the parent counter might have.

type TestGauge

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

TestGauge implements a gauge for use in tests.

Each newly created TestGauge is a stand-alone label namespace. That means time-series behave as expected, e.g., creating two gauges with the same labels by calling With will yield gauges that represent the same time-series. The examples illustrate how this can be used to write a simple test.

Example (Labels)

package main

import (
	"fmt"

	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// This example shows how to write a test with labels using a TestGauge.
	type Server struct {
		RunningWorkers metrics.Gauge
	}

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

	g := metrics.NewTestGauge()

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

	// Check metrics
	fmt.Println(metrics.GaugeValue(g.With("type", "http")) == 8)
	fmt.Println(metrics.GaugeValue(g.With("type", "https")) == 5)
	fmt.Println(metrics.GaugeValue(g.With("type", "other")) == 0)
}

Output:

true
true
true

Example (Simple)

package main

import (
	"fmt"

	"github.com/scionproto/scion/pkg/metrics"
)

func main() {
	// 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.

func (*TestGauge) With

func (g *TestGauge) With(labels ...string) Gauge

With creates a new gauge that includes the specified labels in addition to any labels the parent gauge might have.