xmetrics

Documentation

Overview

Package xmetrics provides configurability for Prometheus-based metrics. The more general go-kit interfaces are used where possible.

Deprecated: xmetrics is no longer planned to be used by future WebPA/XMiDT services.

This package is frozen and no new functionality will be added.

Index

• Constants
• func NewCollector(m Metric) (prometheus.Collector, error)
• type AddSetter
• type Adder
• type Incrementer
  • func NewIncrementer(a Adder) Incrementer
• type LabelValuer
• type Merger
  • func NewMerger() *Merger
  • func (mr *Merger) AddMetrics(allowOverride bool, m []Metric) *Merger
  • func (mr *Merger) AddModules(allowOverride bool, m ...Module) *Merger
  • func (mr *Merger) DefaultNamespace(v string) *Merger
  • func (mr *Merger) DefaultSubsystem(v string) *Merger
  • func (mr *Merger) Err() error
  • func (mr *Merger) Logger(logger *zap.Logger) *Merger
  • func (mr *Merger) Merged() map[string]Metric
  • func (mr *Merger) Namer(f func(namespace, subsystem, name string) string) *Merger
• type Metric
• type Module
• type Observer
• type Options
  • func (o *Options) Module() []Metric
• type PrometheusProvider
• type Registry
  • func MustNewRegistry(o *Options, modules ...Module) Registry
  • func NewRegistry(o *Options, modules ...Module) (Registry, error)
• type Setter
• type Valuer

Constants

const (
	CounterType   = "counter"
	GaugeType     = "gauge"
	HistogramType = "histogram"
	SummaryType   = "summary"
)

const (
	DefaultNamespace = "test"
	DefaultSubsystem = "test"
)

Functions

func NewCollector

func NewCollector(m Metric) (prometheus.Collector, error)

NewCollector creates a Prometheus metric from a Metric descriptor. The name must not be empty. If not supplied in the metric, namespace, subsystem, and help all take on defaults.

Types

type AddSetter

type AddSetter interface {
	Adder
	Setter
}

AddSetter represents a metric that can both have deltas applied and receive new values. Gauges most commonly implement this interface.

type Adder

type Adder interface {
	Add(float64)
}

Adder represents a metrics to which deltas can be added. Go-kit's metrics.Counter, metrics.Gauge, and several prometheus interfaces implement this interface.

type Incrementer

type Incrementer interface {
	Inc()
}

Incrementer represents an Adder which can only be incremented by 1

func NewIncrementer

func NewIncrementer(a Adder) Incrementer

NewIncrementer creates a wrapper around a given Adder. This is syntactic sugar around using the Adder directly.

type LabelValuer

type LabelValuer interface {
	LabelValues() []string
}

LabelValuer is implemented by metrics which expose what their label values are. All of go-kit's metrics/generic types implement this interface.

type Merger

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

Merger is the strategy for merging metrics from various sources. It applies a configurable default namespace and subsystem to each metric. This type implements a Fluent Interface which tracks the first error encountered.

func NewMerger

func NewMerger() *Merger

NewMerger creates a merging strategy with useful defaults.

func (*Merger) AddMetrics

func (mr *Merger) AddMetrics(allowOverride bool, m []Metric) *Merger

AddMetrics merges the given slice of metrics into this instance. If Err() returns non-nil, this method has no effect.

If allowOverride is false, then any metric with the same fully-qualified name as a metric already merged will result in an error. If allowOverride is true, then metrics with the same name are allowed to override previously merged metrics if and only if they are of the same type.

func (*Merger) AddModules

func (mr *Merger) AddModules(allowOverride bool, m ...Module) *Merger

AddModules merges zero or more modules into this instance. If Err() returns non-nil, this method has no effect.

See AddMetrics for a description of allowOverride.

func (*Merger) DefaultNamespace

func (mr *Merger) DefaultNamespace(v string) *Merger

DefaultNamespace sets the default namespace used for metrics that do not specify one. This value applies to all subsequent AddXXX calls, but does not affect any metrics already merged. If the value is empty, the global DefaultNamespace constant is used.

func (*Merger) DefaultSubsystem

func (mr *Merger) DefaultSubsystem(v string) *Merger

DefaultSubsystem sets the default subsystem used for metrics that do not specify one. This value applies to all subsequent AddXXX calls, but does not affect any metrics already merged. If the value is empty, the global DefaultSubsystem constant is used.

func (*Merger) Err

func (mr *Merger) Err() error

Err returns any error that occurred during merging. When this method returns non-nil, no further additions will be accepted.

func (*Merger) Logger

func (mr *Merger) Logger(logger *zap.Logger) *Merger

Logger sets a go-kit logger to use for merging output

func (*Merger) Merged

func (mr *Merger) Merged() map[string]Metric

Merged returns the built map of metrics from all sources, keyed by fully-qualified name

func (*Merger) Namer

func (mr *Merger) Namer(f func(namespace, subsystem, name string) string) *Merger

Namer sets the fully-qualified naming strategy for this merger. This method applies to all subsequent AddXXX calls, but does not affect any metrics already merged. If f is nil, an internal default naming strategy is used.

type Metric

type Metric struct {
	// Name is the required name of this metric.  This value is required.
	Name string

	// Type is the required type of metric.  This value must be one of the constants defined in this package.
	Type string

	// Namespace is the namespace of this metric.  This value is optional.  The enclosing Options' Namespace
	// field is used if this is not supplied.
	Namespace string

	// Subsystem is the subsystem of this metric.  This value is optional.  The enclosing Options' Subsystem
	// field is used if this is not supplied.
	Subsystem string

	// Help is the help string for this metric.  If not supplied, the metric's name is used
	Help string

	// ConstLabels are the Prometheus ConstLabels for this metric.  This field is optional.
	ConstLabels map[string]string

	// LabelNames are the Prometheus label names for this metric.  This field is optional.
	LabelNames []string

	// Buckets describes the observation buckets for a histogram.  This field is only valid for histogram metrics
	// and is ignored for other metric types.
	Buckets []float64

	// Objectives is the Summary objectives.  This field is only valid for summary metrics, and is ignored
	// for other metric types.
	Objectives map[float64]float64

	// MaxAge is the Summary MaxAge.  This field is only valid for summary metrics, and is ignored
	// for other metric types.
	MaxAge time.Duration

	// AgeBuckets is the Summary AgeBuckets.  This field is only valid for summary metrics, and is ignored
	// for other metric types.
	AgeBuckets uint32

	// BufCap is the Summary BufCap.  This field is only valid for summary metrics, and is ignored
	// for other metric types.
	BufCap uint32
}

Metric describes a single metric that will be preregistered. This type loosely corresponds with Prometheus' Opts struct. The fields in this type are the union of all necessary data for creating Prometheus metrics.

type Module

type Module func() []Metric

Module is a function type that returns prebuilt metrics.

type Observer

type Observer interface {
	Observe(float64)
}

Observer is a type of metric which receives observations. Histograms and summaries implement this interface.

type Options

type Options struct {
	// Logger is the go-kit logger to use for metrics output.  If unset, sallust.Default() is used.
	Logger *zap.Logger

	// Namespace is the global default namespace for metrics which don't define a namespace (or for ad hoc metrics).
	// If not supplied, DefaultNamespace is used.
	Namespace string

	// Subsystem is the global default subsystem for metrics which don't define a subsystem (or for ad hoc metrics).
	// If not supplied, DefaultSubsystem is used.
	Subsystem string

	// Pedantic indicates whether the registry is created via NewPedanticRegistry().  By default, this is false.  Set
	// to true for testing or development.
	Pedantic bool

	// DisableGoCollector controls whether the Go Collector is registered with the Registry.  By default this is false,
	// meaning that a GoCollector is registered.
	DisableGoCollector bool

	// DisableProcessCollector controls whether the Process Collector is registered with the Registry.  By default this is false,
	// meaning that a ProcessCollector is registered.
	DisableProcessCollector bool

	// ReportProcessCollectorErrors is the value passed to NewProcessCollector via the ProcessCollectorOpts.ReportErrors field
	ReportProcessCollectorErrors bool

	// Metrics defines the set of predefined metrics.  These metrics will be defined immediately by an Registry
	// created using this Options instance.  This field is optional.
	//
	// Any duplicate metrics will cause an error.  Duplicate metrics are defined as those having the same namespace,
	// subsystem, and name.
	Metrics []Metric
}

Options is the configurable options for creating a Prometheus registry

func (*Options) Module

func (o *Options) Module() []Metric

Module acts as a metrics module function using the (normally) injected metrics.

type PrometheusProvider

type PrometheusProvider interface {
	NewCounterVec(name string) *prometheus.CounterVec
	NewCounterVecEx(namespace, subsystem, name string) *prometheus.CounterVec

	NewGaugeVec(name string) *prometheus.GaugeVec
	NewGaugeVecEx(namespace, subsystem, name string) *prometheus.GaugeVec

	NewHistogramVec(name string) *prometheus.HistogramVec
	NewHistogramVecEx(namespace, subsystem, name string) *prometheus.HistogramVec

	NewSummaryVec(name string) *prometheus.SummaryVec
	NewSummaryVecEx(namespace, subsystem, name string) *prometheus.SummaryVec
}

PrometheusProvider is a Prometheus-specific version of go-kit's metrics.Provider. Use this interface when interacting directly with Prometheus.

type Registry

type Registry interface {
	PrometheusProvider
	provider.Provider
	prometheus.Gatherer

	NewPrometheusGaugeEx(namespace, subsystem, name string) prometheus.Gauge
	NewPrometheusGauge(name string) prometheus.Gauge
}

Registry is the core abstraction for this package. It is a Prometheus gatherer and a go-kit metrics.Provider all in one.

The Provider implementation works slightly differently than the go-kit implementation. For any metric that is already defined the provider returns a new go-kit wrapper for that metric. Additionally, new metrics (including ad hoc metrics) are cached and returned by subsequent calles to the Provider methods.

func MustNewRegistry

func MustNewRegistry(o *Options, modules ...Module) Registry

MustNewRegistry is like NewRegistry, except that it panics when NewRegistry would return an error.

func NewRegistry

func NewRegistry(o *Options, modules ...Module) (Registry, error)

NewRegistry creates an xmetrics.Registry from an externally supplied set of Options and a set of modules, which are functions that just return Metrics to register. The module functions are expected to come from application or library code, and are to define any built-in metrics. Metrics present in the options will override any corresponding metric from modules.

type Setter

type Setter interface {
	Set(float64)
}

Setter represents a metric that can receive updates, e.g. a gauge. Go-kit's metrics.Gauge and prometheus gauges implement this interface.

type Valuer

type Valuer interface {
	Value() float64
}

Valuer is implemented by metrics which can expose their current value. A couple of go-kit's metrics/generic types implement this interface.