metric

package
v1.15.4 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2024 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewCounterVec 

func NewCounterVec(opts CounterOpts, labelNames []string) *counterVec

NewCounterVec creates a new DeletableVec[Counter] based on the provided CounterOpts and partitioned by the given label names.

func NewCounterVecWithLabels added in v1.15.0 

func NewCounterVecWithLabels(opts CounterOpts, labels Labels) *counterVec

NewCounterVecWithLabels creates a new DeletableVec[Counter] based on the provided CounterOpts and partitioned by the given labels. This will also initialize the labels with the provided values so that metrics with known label value ranges can be pre-initialized to zero upon init.

This should only be used when all label values are known at init, otherwise use of the metric vector with uninitialized labels will result in warnings.

Note: Disabled metrics will not have their label values initialized.

For example: 

NewCounterVecWithLabels(CounterOpts{
	Namespace: "cilium",
	Subsystem: "subsystem",
	Name:      "cilium_test",
	Disabled:  false,
}, Labels{
	{Name: "foo", Values: NewValues("0", "1")},
	{Name: "bar", Values: NewValues("a", "b")},
})

Will initialize the following metrics to: 

cilium_subsystem_cilium_test{foo="0", bar="a"} 0
cilium_subsystem_cilium_test{foo="0", bar="b"} 0
cilium_subsystem_cilium_test{foo="1", bar="a"} 0
cilium_subsystem_cilium_test{foo="1", bar="b"} 0

func NewGaugeVec 

func NewGaugeVec(opts GaugeOpts, labelNames []string) *gaugeVec

NewGaugeVec creates a new DeletableVec[Gauge] based on the provided GaugeOpts and partitioned by the given label names.

func NewGaugeVecWithLabels added in v1.15.0 

func NewGaugeVecWithLabels(opts GaugeOpts, labels Labels) *gaugeVec

NewGaugeVecWithLabels creates a new DeletableVec[Gauge] based on the provided CounterOpts and partitioned by the given labels. This will also initialize the labels with the provided values so that metrics with known label value ranges can be pre-initialized to zero upon init.

This should only be used when all label values are known at init, otherwise use of the metric vector with uninitialized labels will result in warnings.

Note: Disabled metrics will not have their label values initialized.

For example: 

NewGaugeVecWithLabels(GaugeOpts{
	Namespace: "cilium",
	Subsystem: "subsystem",
	Name:      "cilium_test",
	Disabled:  false,
}, Labels{
	{Name: "foo", Values: NewValues("0", "1")},
	{Name: "bar", Values: NewValues("a", "b")},
})

Will initialize the following metrics to: 

cilium_subsystem_cilium_test{foo="0", bar="a"} 0
cilium_subsystem_cilium_test{foo="0", bar="b"} 0
cilium_subsystem_cilium_test{foo="1", bar="a"} 0
cilium_subsystem_cilium_test{foo="1", bar="b"} 0

func NewHistogramVec 

func NewHistogramVec(opts HistogramOpts, labelNames []string) *histogramVec

NewHistogramVec creates a new Vec[Observer] (i.e. Histogram Vec) based on the provided HistogramOpts and partitioned by the given label names.

func NewHistogramVecWithLabels added in v1.15.0 

func NewHistogramVecWithLabels(opts HistogramOpts, labels Labels) *histogramVec

NewHistogramVec creates a new Vec[Observer] based on the provided CounterOpts and partitioned by the given labels. This will also initialize the labels with the provided values so that metrics with known label value ranges can be pre-initialized to zero upon init.

This should only be used when all label values are known at init, otherwise use of the metric vector with uninitialized labels will result in warnings.

Note: Disabled metrics will not have their label values initialized.

Types

type Counter 

type Counter interface {
	prometheus.Counter
	WithMetadata

	Get() float64
}

func NewCounter 

func NewCounter(opts CounterOpts) Counter

type CounterOpts 

type CounterOpts Opts

type DeletableVec 

type DeletableVec[T any] interface {
	Vec[T]

	// Delete deletes the metric where the variable labels are the same as those
	// passed in as labels. It returns true if a metric was deleted.
	//
	// It is not an error if the number and names of the Labels are inconsistent
	// with those of the VariableLabels in Desc. However, such inconsistent Labels
	// can never match an actual metric, so the method will always return false in
	// that case.
	//
	// This method is used for the same purpose as DeleteLabelValues(...string). See
	// there for pros and cons of the two methods.
	Delete(labels prometheus.Labels) bool

	// DeleteLabelValues removes the metric where the variable labels are the same
	// as those passed in as labels (same order as the VariableLabels in Desc). It
	// returns true if a metric was deleted.
	//
	// It is not an error if the number of label values is not the same as the
	// number of VariableLabels in Desc. However, such inconsistent label count can
	// never match an actual metric, so the method will always return false in that
	// case.
	//
	// Note that for more than one label value, this method is prone to mistakes
	// caused by an incorrect order of arguments. Consider Delete(Labels) as an
	// alternative to avoid that type of mistake. For higher label numbers, the
	// latter has a much more readable (albeit more verbose) syntax, but it comes
	// with a performance overhead (for creating and processing the Labels map).
	// See also the CounterVec example.
	DeleteLabelValues(lvs ...string) bool

	// DeletePartialMatch deletes all metrics where the variable labels contain all of those
	// passed in as labels. The order of the labels does not matter.
	// It returns the number of metrics deleted.
	//
	// Note that curried labels will never be matched if deleting from the curried vector.
	// To match curried labels with DeletePartialMatch, it must be called on the base vector.
	DeletePartialMatch(labels prometheus.Labels) int

	// Reset deletes all metrics in this vector.
	Reset()
}

DeletableVec is a generic type to describe a vectorized version of another metric type, like Vec[T], but with the additional ability to remove labels without re-creating the metric.

type Gauge 

type Gauge interface {
	prometheus.Gauge
	WithMetadata

	Get() float64
}

func NewGauge 

func NewGauge(opts GaugeOpts) Gauge

type GaugeFunc 

type GaugeFunc interface {
	prometheus.GaugeFunc
	WithMetadata
}

func NewGaugeFunc 

func NewGaugeFunc(opts GaugeOpts, function func() float64) GaugeFunc

type GaugeOpts 

type GaugeOpts Opts

type Histogram 

type Histogram interface {
	prometheus.Histogram
	WithMetadata
}

func NewHistogram 

func NewHistogram(opts HistogramOpts) Histogram

type HistogramOpts 

type HistogramOpts struct {
	// Namespace, Subsystem, and Name are components of the fully-qualified
	// name of the Histogram (created by joining these components with
	// "_"). Only Name is mandatory, the others merely help structuring the
	// name. Note that the fully-qualified name of the Histogram must be a
	// valid Prometheus metric name.
	Namespace string
	Subsystem string
	Name      string

	// Help provides information about this Histogram.
	//
	// Metrics with the same fully-qualified name must have the same Help
	// string.
	Help string

	// ConstLabels are used to attach fixed labels to this metric. Metrics
	// with the same fully-qualified name must have the same label names in
	// their ConstLabels.
	//
	// ConstLabels are only used rarely. In particular, do not use them to
	// attach the same labels to all your metrics. Those use cases are
	// better covered by target labels set by the scraping Prometheus
	// server, or by one specific metric (e.g. a build_info or a
	// machine_role metric). See also
	// https://prometheus.io/docs/instrumenting/writing_exporters/#target-labels-not-static-scraped-labels
	ConstLabels prometheus.Labels

	// Buckets defines the buckets into which observations are counted. Each
	// element in the slice is the upper inclusive bound of a bucket. The
	// values must be sorted in strictly increasing order. There is no need
	// to add a highest bucket with +Inf bound, it will be added
	// implicitly. If Buckets is left as nil or set to a slice of length
	// zero, it is replaced by default buckets. The default buckets are
	// DefBuckets if no buckets for a native histogram (see below) are used,
	// otherwise the default is no buckets. (In other words, if you want to
	// use both reguler buckets and buckets for a native histogram, you have
	// to define the regular buckets here explicitly.)
	Buckets []float64

	// If NativeHistogramBucketFactor is greater than one, so-called sparse
	// buckets are used (in addition to the regular buckets, if defined
	// above). A Histogram with sparse buckets will be ingested as a Native
	// Histogram by a Prometheus server with that feature enabled (requires
	// Prometheus v2.40+). Sparse buckets are exponential buckets covering
	// the whole float64 range (with the exception of the “zero” bucket, see
	// SparseBucketsZeroThreshold below). From any one bucket to the next,
	// the width of the bucket grows by a constant
	// factor. NativeHistogramBucketFactor provides an upper bound for this
	// factor (exception see below). The smaller
	// NativeHistogramBucketFactor, the more buckets will be used and thus
	// the more costly the histogram will become. A generally good trade-off
	// between cost and accuracy is a value of 1.1 (each bucket is at most
	// 10% wider than the previous one), which will result in each power of
	// two divided into 8 buckets (e.g. there will be 8 buckets between 1
	// and 2, same as between 2 and 4, and 4 and 8, etc.).
	//
	// Details about the actually used factor: The factor is calculated as
	// 2^(2^n), where n is an integer number between (and including) -8 and
	// 4. n is chosen so that the resulting factor is the largest that is
	// still smaller or equal to NativeHistogramBucketFactor. Note that the
	// smallest possible factor is therefore approx. 1.00271 (i.e. 2^(2^-8)
	// ). If NativeHistogramBucketFactor is greater than 1 but smaller than
	// 2^(2^-8), then the actually used factor is still 2^(2^-8) even though
	// it is larger than the provided NativeHistogramBucketFactor.
	//
	// NOTE: Native Histograms are still an experimental feature. Their
	// behavior might still change without a major version
	// bump. Subsequently, all NativeHistogram... options here might still
	// change their behavior or name (or might completely disappear) without
	// a major version bump.
	NativeHistogramBucketFactor float64
	// All observations with an absolute value of less or equal
	// NativeHistogramZeroThreshold are accumulated into a “zero”
	// bucket. For best results, this should be close to a bucket
	// boundary. This is usually the case if picking a power of two. If
	// NativeHistogramZeroThreshold is left at zero,
	// DefSparseBucketsZeroThreshold is used as the threshold. To configure
	// a zero bucket with an actual threshold of zero (i.e. only
	// observations of precisely zero will go into the zero bucket), set
	// NativeHistogramZeroThreshold to the NativeHistogramZeroThresholdZero
	// constant (or any negative float value).
	NativeHistogramZeroThreshold float64

	// The remaining fields define a strategy to limit the number of
	// populated sparse buckets. If NativeHistogramMaxBucketNumber is left
	// at zero, the number of buckets is not limited. (Note that this might
	// lead to unbounded memory consumption if the values observed by the
	// Histogram are sufficiently wide-spread. In particular, this could be
	// used as a DoS attack vector. Where the observed values depend on
	// external inputs, it is highly recommended to set a
	// NativeHistogramMaxBucketNumber.)  Once the set
	// NativeHistogramMaxBucketNumber is exceeded, the following strategy is
	// enacted: First, if the last reset (or the creation) of the histogram
	// is at least NativeHistogramMinResetDuration ago, then the whole
	// histogram is reset to its initial state (including regular
	// buckets). If less time has passed, or if
	// NativeHistogramMinResetDuration is zero, no reset is
	// performed. Instead, the zero threshold is increased sufficiently to
	// reduce the number of buckets to or below
	// NativeHistogramMaxBucketNumber, but not to more than
	// NativeHistogramMaxZeroThreshold. Thus, if
	// NativeHistogramMaxZeroThreshold is already at or below the current
	// zero threshold, nothing happens at this step. After that, if the
	// number of buckets still exceeds NativeHistogramMaxBucketNumber, the
	// resolution of the histogram is reduced by doubling the width of the
	// sparse buckets (up to a growth factor between one bucket to the next
	// of 2^(2^4) = 65536, see above).
	NativeHistogramMaxBucketNumber  uint32
	NativeHistogramMinResetDuration time.Duration
	NativeHistogramMaxZeroThreshold float64

	ConfigName string

	// If true, the metric has to be explicitly enabled via config or flags
	Disabled bool
}

HistogramOpts are a modified and expanded version of the prometheus.HistogramOpts. https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#HistogramOpts

type Label added in v1.15.0 

type Label struct {
	Name string
	// If defined, only these values are allowed.
	Values Values
}

Label represents a metric label with a pre-defined range of values. This is used with the NewxxxVecWithLabels metrics constructors to initialize vector metrics with known label value ranges, avoiding empty metrics.

type Labels added in v1.15.0 

type Labels []Label

Labels is a slice of labels that represents a label set for a vector type metric.

type Observer 

type Observer interface {
	prometheus.Observer
	WithMetadata
}

type Opts 

type Opts struct {
	// Namespace, Subsystem, and Name are components of the fully-qualified
	// name of the Metric (created by joining these components with
	// "_"). Only Name is mandatory, the others merely help structuring the
	// name. Note that the fully-qualified name of the metric must be a
	// valid Prometheus metric name.
	Namespace string
	Subsystem string
	Name      string

	// Help provides information about this metric.
	//
	// Metrics with the same fully-qualified name must have the same Help
	// string.
	Help string

	// ConstLabels are used to attach fixed labels to this metric. Metrics
	// with the same fully-qualified name must have the same label names in
	// their ConstLabels.
	//
	// ConstLabels are only used rarely. In particular, do not use them to
	// attach the same labels to all your metrics. Those use cases are
	// better covered by target labels set by the scraping Prometheus
	// server, or by one specific metric (e.g. a build_info or a
	// machine_role metric). See also
	// https://prometheus.io/docs/instrumenting/writing_exporters/#target-labels-not-static-scraped-labels
	ConstLabels prometheus.Labels

	// The name used to enable/disable this metric via the config/flags
	ConfigName string

	// If true, the metric has to be explicitly enabled via config or flags
	Disabled bool
}

Opts are a modified and extended version of the prometheus.Opts https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#Opts

func (Opts) GetConfigName added in v1.15.0 

func (b Opts) GetConfigName() string

type Values added in v1.15.0 

type Values map[string]struct{}

Values is a distinct set of possible label values for a particular Label.

func NewValues added in v1.15.0 

func NewValues(vs ...string) Values

NewValues constructs a Values type from a set of strings.

type Vec 

type Vec[T any] interface {
	prometheus.Collector
	WithMetadata

	// CurryWith returns a vector curried with the provided labels, i.e. the
	// returned vector has those labels pre-set for all labeled operations performed
	// on it. The cardinality of the curried vector is reduced accordingly. The
	// order of the remaining labels stays the same (just with the curried labels
	// taken out of the sequence – which is relevant for the
	// (GetMetric)WithLabelValues methods). It is possible to curry a curried
	// vector, but only with labels not yet used for currying before.
	//
	// The metrics contained in the `Vec[T]` are shared between the curried and
	// uncurried vectors. They are just accessed differently. Curried and uncurried
	// vectors behave identically in terms of collection. Only one must be
	// registered with a given registry (usually the uncurried version). The Reset
	// method deletes all metrics, even if called on a curried vector.
	CurryWith(labels prometheus.Labels) (Vec[T], error)

	// GetMetricWith returns the `T` for the given Labels map (the label names
	// must match those of the variable labels in Desc). If that label map is
	// accessed for the first time, a new `T` is created. Implications of
	// creating a `T` without using it and keeping the `T` for later use are
	// the same as for GetMetricWithLabelValues.
	//
	// An error is returned if the number and names of the Labels are inconsistent
	// with those of the variable labels in Desc (minus any curried labels).
	//
	// This method is used for the same purpose as
	// GetMetricWithLabelValues(...string). See there for pros and cons of the two
	// methods.
	GetMetricWith(labels prometheus.Labels) (T, error)

	// GetMetricWithLabelValues returns the `T` for the given slice of label
	// values (same order as the variable labels in Desc). If that combination of
	// label values is accessed for the first time, a new `T` is created.
	//
	// It is possible to call this method without using the returned `T` to only
	// create the new `T` but leave it at its starting value 0.
	//
	// Keeping the `T` for later use is possible (and should be considered if
	// performance is critical), but keep in mind that Reset, DeleteLabelValues and
	// Delete can be used to delete the `T` from the `Vec[T]`, assuming it also
	// implements `DeletableVec[T]`. In that case,
	// the `T` will still exist, but it will not be exported anymore, even if a
	// `T` with the same label values is created later.
	//
	// An error is returned if the number of label values is not the same as the
	// number of variable labels in Desc (minus any curried labels).
	//
	// Note that for more than one label value, this method is prone to mistakes
	// caused by an incorrect order of arguments. Consider GetMetricWith(Labels) as
	// an alternative to avoid that type of mistake. For higher label numbers, the
	// latter has a much more readable (albeit more verbose) syntax, but it comes
	// with a performance overhead (for creating and processing the Labels map).
	GetMetricWithLabelValues(lvs ...string) (T, error)

	// With works as GetMetricWith, but panics where GetMetricWithLabels would have
	// returned an error. Not returning an error allows shortcuts like
	//
	//	myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Add(42)
	With(labels prometheus.Labels) T

	// WithLabelValues works as GetMetricWithLabelValues, but panics where
	// GetMetricWithLabelValues would have returned an error. Not returning an
	// error allows shortcuts like
	//
	//	myVec.WithLabelValues("404", "GET").Add(42)
	WithLabelValues(lvs ...string) T
}

Vec is a generic type to describe the vectorized version of another metric type, for example Vec[Counter] would be our version of a prometheus.CounterVec.

type WithMetadata 

type WithMetadata interface {
	IsEnabled() bool
	SetEnabled(bool)
	Opts() Opts
}

WithMetadata is the interface implemented by any metric defined in this package. These typically embed existing prometheus metric types and add additional metadata. In addition, these metrics have the concept of being enabled or disabled which is used in place of conditional registration so all metric types can always be registered.

Source Files

View all Source files

Directories

Path Synopsis

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.