metricslite

README

metricslite

Package metricslite implements a lightweight, testable metrics interface focused on Prometheus metrics. MIT Licensed.

Disclaimer: I (@mdlayher) am a former member of the Prometheus team, but this package is entirely my own work and does not represent the opinions of the Prometheus team as a whole.

Documentation

Overview

Package metricslite implements a lightweight, testable metrics interface focused on Prometheus metrics.

Index

• type Counter
• type Gauge
• type Interface
  • func Discard() Interface
  • func NewPrometheus(reg *prometheus.Registry) Interface
• type Memory
  • func NewMemory() *Memory
  • func (m *Memory) ConstCounter(name, help string, labelNames ...string)
  • func (m *Memory) ConstGauge(name, help string, labelNames ...string)
  • func (m *Memory) Counter(name, help string, labelNames ...string) Counter
  • func (m *Memory) Gauge(name, help string, labelNames ...string) Gauge
  • func (m *Memory) OnConstScrape(scrape ScrapeFunc)
  • func (m *Memory) Series() map[string]Series
• type ScrapeError
  • func (e *ScrapeError) Error() string
• type ScrapeFunc
• type Series

Types

type Counter

type Counter func(value float64, labels ...string)

A Counter is a function which increments a metric's value by value when invoked. Value must be zero or positive or the Counter will panic. Labels enable optional partitioning of a Counter into multiple dimensions.

Counters must be safe for concurrent use. The number of label values passed when the Counter is invoked must match the number of label names defined when the Counter was created, or the Counter will panic.

type Gauge

type Gauge func(value float64, labels ...string)

A Gauge is a function which sets a metric's value when invoked. Labels enable optional partitioning of a Gauge into multiple dimensions.

Gauges must be safe for concurrent use. The number of label values passed when the Gauge is invoked must match the number of label names defined when the Gauge was created, or the Gauge will panic.

type Interface

type Interface interface {
	// Const metrics are used primarily when implementing Prometheus exporters
	// or copying metrics from an external monitoring system. Most applications
	// should use the non-const Counter, Gauge, etc. instead.
	//
	// OnConstScrape invokes the input ScrapeFunc on-demand when the metrics are
	// gathered. OnConstScrape must be called with a ScrapeFunc if const metrics
	// are in use, or the Interface will panic.
	ConstCounter(name, help string, labelNames ...string)
	ConstGauge(name, help string, labelNames ...string)
	OnConstScrape(scrape ScrapeFunc)

	// Non-const (or direct instrumentation) metrics are used to instrument
	// normal Go applications. Their values are only updated when requested
	// by the caller: not on-demand when metrics are gathered.
	Counter(name, help string, labelNames ...string) Counter
	Gauge(name, help string, labelNames ...string) Gauge
}

An Interface is a type which can produce metrics functions. An Interface implementation must be safe for concurrent use.

If any Interface methods are used to create a metric with the same name as a previously created metric, those methods should panic. Callers are expected to create non-const metrics once and pass them through their program as needed.

func Discard

func Discard() Interface

Discard creates an Interface which creates no-op metrics that discard their data.

func NewPrometheus

func NewPrometheus(reg *prometheus.Registry) Interface

NewPrometheus creates an Interface which will register all of its metrics to the specified Prometheus registry. The registry must not be nil.

type Memory

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

Memory implements Interface by storing timeseries and samples in memory. This type is primarily useful for tests.

func NewMemory

func NewMemory() *Memory

NewMemory creates an initialized Memory.

func (*Memory) ConstCounter

func (m *Memory) ConstCounter(name, help string, labelNames ...string)

ConstCounter implements Interface.

func (*Memory) ConstGauge

func (m *Memory) ConstGauge(name, help string, labelNames ...string)

ConstGauge implements Interface.

func (*Memory) Counter

func (m *Memory) Counter(name, help string, labelNames ...string) Counter

Counter implements Interface.

func (*Memory) Gauge

func (m *Memory) Gauge(name, help string, labelNames ...string) Gauge

Gauge implements Interface.

func (*Memory) OnConstScrape

func (m *Memory) OnConstScrape(scrape ScrapeFunc)

OnConstScrape implements Interface.

func (*Memory) Series

func (m *Memory) Series() map[string]Series

Series produces a copy of all of the timeseries and samples stored by the Memory.

type ScrapeError

type ScrapeError struct {
	Metric string
	Err    error
}

A ScrapeError allows a ScrapeFunc to report a specific metric as the cause of a failed metrics scrape.

func (*ScrapeError) Error

func (e *ScrapeError) Error() string

Error implements error.

type ScrapeFunc

type ScrapeFunc func(metrics map[string]func(value float64, labels ...string)) error

A ScrapeFunc is a function which is invoked on demand to collect metric labels and values for each const metric present in the map key for metrics. The user should invoke the collect function for any values they wish to export as metrics. If an error of type *ScrapeError is returned, the error will be reported to the metrics system.

A ScrapeFunc must be safe for concurrent use. The number of label values passed when collect is invoked must match the number of label names defined when the const metric was created, or collect will panic.

type Series

type Series struct {
	Name, Help string
	Samples    map[string]float64
}

A Series is a timeseries with metadata and samples partitioned by labels.