metrics

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 12, 2022 License: Apache-2.0 Imports: 6 Imported by: 0

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

Examples

Constants

This section is empty.

Variables

This section is empty.

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 added in v0.7.0 

func GaugeSetCurrentTime(g Gauge)

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

func GaugeSetTimestamp added in v0.7.0 

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 added in v0.7.0 

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/go/lib/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
}

Output:
Example (Interface) 
package main

import (
	"github.com/scionproto/scion/go/lib/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
}

Output:

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 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/go/lib/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/go/lib/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/go/lib/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/go/lib/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.

Source Files

View all Source files

Directories

Path Synopsis
Package mock_metrics is a generated GoMock package.
 Package mock_metrics is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.