metrics

package
v0.24.5 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2022 License: Apache-2.0 Imports: 20 Imported by: 461

Documentation

Index

Constants

View Source 
const (
	// Serve an HTTP status code 500 upon the first error
	// encountered. Report the error message in the body.
	HTTPErrorOnError promhttp.HandlerErrorHandling = iota

	// Ignore errors and try to serve as many metrics as possible.  However,
	// if no metrics can be served, serve an HTTP status code 500 and the
	// last error message in the body. Only use this in deliberate "best
	// effort" metrics collection scenarios. In this case, it is highly
	// recommended to provide other means of detecting errors: By setting an
	// ErrorLog in HandlerOpts, the errors are logged. By providing a
	// Registry in HandlerOpts, the exposed metrics include an error counter
	// "promhttp_metric_handler_errors_total", which can be used for
	// alerts.
	ContinueOnError

	// Panic upon the first error encountered (useful for "crash only" apps).
	PanicOnError
)

These constants cause handlers serving metrics to behave as described if errors are encountered.

Variables

View Source 
var BuildVersion = version.Get

BuildVersion is a helper function that can be easily mocked.

View Source 
var DefBuckets = prometheus.DefBuckets

DefBuckets is a wrapper for prometheus.DefBuckets

Functions

func BuildFQName added in v0.17.0 

func BuildFQName(namespace, subsystem, name string) string

BuildFQName joins the given three name components by "_". Empty name components are ignored. If the name parameter itself is empty, an empty string is returned, no matter what. Metric implementations included in this library use this function internally to generate the fully-qualified metric name from the name component in their Opts. Users of the library will only need this function if they implement their own Metric or instantiate a Desc (with NewDesc) directly.

func ExponentialBuckets added in v0.17.0 

func ExponentialBuckets(start, factor float64, count int) []float64

ExponentialBuckets is a wrapper for prometheus.ExponentialBuckets.

func HandlerFor added in v0.17.0 

func HandlerFor(reg Gatherer, opts HandlerOpts) http.Handler

HandlerFor returns an uninstrumented http.Handler for the provided Gatherer. The behavior of the Handler is defined by the provided HandlerOpts. Thus, HandlerFor is useful to create http.Handlers for custom Gatherers, with non-default HandlerOpts, and/or with custom (or no) instrumentation. Use the InstrumentMetricHandler function to apply the same kind of instrumentation as it is used by the Handler function.

func HandlerWithReset added in v0.19.0 

func HandlerWithReset(reg KubeRegistry, opts HandlerOpts) http.Handler

HandlerWithReset return an http.Handler with Reset

func LinearBuckets added in v0.17.0 

func LinearBuckets(start, width float64, count int) []float64

LinearBuckets is a wrapper for prometheus.LinearBuckets.

func RegisterBuildInfo added in v0.16.4 

func RegisterBuildInfo(r KubeRegistry)

RegisterBuildInfo registers the build and version info in a metadata metric in prometheus

func RegisterProcessStartTime 

func RegisterProcessStartTime(registrationFunc func(Registerable) error) error

RegisterProcessStartTime registers the process_start_time_seconds to a prometheus registry. This metric needs to be included to ensure counter data fidelity.

func SetDisabledMetric added in v0.21.0 

func SetDisabledMetric(name string)

func SetLabelAllowListFromCLI added in v0.21.0 

func SetLabelAllowListFromCLI(allowListMapping map[string]string)

func SetShowHidden added in v0.16.4 

func SetShowHidden()

SetShowHidden will enable showing hidden metrics. This will no-opt after the initial call

func ShouldShowHidden added in v0.16.4 

func ShouldShowHidden() bool

ShouldShowHidden returns whether showing hidden deprecated metrics is enabled. While the primary usecase for this is internal (to determine registration behavior) this can also be used to introspect

func ValidateShowHiddenMetricsVersion added in v0.17.0 

func ValidateShowHiddenMetricsVersion(v string) []error

ValidateShowHiddenMetricsVersion checks invalid version for which show hidden metrics.

Types

type BaseStableCollector added in v0.17.0 

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

BaseStableCollector which implements almost all of the methods defined by StableCollector is a convenient assistant for custom collectors. It is recommend that inherit BaseStableCollector when implementing custom collectors.

func (*BaseStableCollector) ClearState added in v0.18.0 

func (bsc *BaseStableCollector) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*BaseStableCollector) Collect added in v0.17.0 

func (bsc *BaseStableCollector) Collect(ch chan<- prometheus.Metric)

Collect is called by the Prometheus registry when collecting metrics.

func (*BaseStableCollector) CollectWithStability added in v0.17.0 

func (bsc *BaseStableCollector) CollectWithStability(ch chan<- Metric)

CollectWithStability sends all metrics to the provided channel. Every custom collector should over-write this method.

func (*BaseStableCollector) Create added in v0.17.0 

func (bsc *BaseStableCollector) Create(version *semver.Version, self StableCollector) bool

Create intends to be called by registry. Create will return true as long as there is one or more metrics not be hidden. Otherwise return false, that means the whole collector will be ignored by registry.

func (*BaseStableCollector) Describe added in v0.17.0 

func (bsc *BaseStableCollector) Describe(ch chan<- *prometheus.Desc)

Describe sends all descriptors to the provided channel. It intend to be called by prometheus registry.

func (*BaseStableCollector) DescribeWithStability added in v0.17.0 

func (bsc *BaseStableCollector) DescribeWithStability(ch chan<- *Desc)

DescribeWithStability sends all descriptors to the provided channel. Every custom collector should over-write this method.

func (*BaseStableCollector) HiddenMetrics added in v0.18.0 

func (bsc *BaseStableCollector) HiddenMetrics() (fqNames []string)

HiddenMetrics tells the list of hidden metrics with fqName.

type Collector 

type Collector interface {
	Describe(chan<- *prometheus.Desc)
	Collect(chan<- prometheus.Metric)
}

Collector defines a subset of prometheus.Collector interface methods

type Counter 

type Counter struct {
	CounterMetric
	*CounterOpts
	// contains filtered or unexported fields
}

Counter is our internal representation for our wrapping struct around prometheus counters. Counter implements both kubeCollector and CounterMetric.

func NewCounter 

func NewCounter(opts *CounterOpts) *Counter

NewCounter returns an object which satisfies the kubeCollector and CounterMetric interfaces. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

func (*Counter) ClearState added in v0.17.0 

func (r *Counter) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*Counter) Collect 

func (c *Counter) Collect(ch chan<- prometheus.Metric)

func (*Counter) Create 

func (r *Counter) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*Counter) DeprecatedVersion 

func (c *Counter) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*Counter) Desc added in v0.21.0 

func (c *Counter) Desc() *prometheus.Desc

func (*Counter) Describe 

func (c *Counter) Describe(ch chan<- *prometheus.Desc)

func (*Counter) FQName added in v0.18.0 

func (r *Counter) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*Counter) IsCreated 

func (r *Counter) IsCreated() bool

func (*Counter) IsDeprecated 

func (r *Counter) IsDeprecated() bool

func (*Counter) IsHidden 

func (r *Counter) IsHidden() bool

func (*Counter) Reset added in v0.19.0 

func (c *Counter) Reset()

Reset resets the underlying prometheus Counter to start counting from 0 again

func (*Counter) WithContext added in v0.21.0 

func (c *Counter) WithContext(ctx context.Context) CounterMetric

WithContext allows the normal Counter metric to pass in context. The context is no-op now.

func (*Counter) Write added in v0.21.0 

func (c *Counter) Write(to *dto.Metric) error

type CounterMetric 

type CounterMetric interface {
	Inc()
	Add(float64)
}

CounterMetric is an interface which defines a subset of the interface provided by prometheus.Counter

type CounterOpts 

type CounterOpts KubeOpts

CounterOpts is an alias for Opts. See there for doc comments.

type CounterVec 

type CounterVec struct {
	*prometheus.CounterVec
	*CounterOpts
	// contains filtered or unexported fields
}

CounterVec is the internal representation of our wrapping struct around prometheus counterVecs. CounterVec implements both kubeCollector and CounterVecMetric.

func NewCounterVec 

func NewCounterVec(opts *CounterOpts, labels []string) *CounterVec

NewCounterVec returns an object which satisfies the kubeCollector and CounterVecMetric interfaces. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

func (*CounterVec) ClearState added in v0.17.0 

func (r *CounterVec) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*CounterVec) Create 

func (r *CounterVec) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*CounterVec) Delete added in v0.16.4 

func (v *CounterVec) Delete(labels map[string]string) bool

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.

func (*CounterVec) DeprecatedVersion 

func (v *CounterVec) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*CounterVec) FQName added in v0.18.0 

func (r *CounterVec) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*CounterVec) IsCreated 

func (r *CounterVec) IsCreated() bool

func (*CounterVec) IsDeprecated 

func (r *CounterVec) IsDeprecated() bool

func (*CounterVec) IsHidden 

func (r *CounterVec) IsHidden() bool

func (*CounterVec) Reset added in v0.17.0 

func (v *CounterVec) Reset()

Reset deletes all metrics in this vector.

func (*CounterVec) With 

func (v *CounterVec) With(labels map[string]string) CounterMetric

With returns the Counter for the given Labels map (the label names must match those of the VariableLabels in Desc). If that label map is accessed for the first time, a new Counter is created IFF the counterVec has been registered to a metrics registry.

func (*CounterVec) WithContext added in v0.21.0 

func (v *CounterVec) WithContext(ctx context.Context) *CounterVecWithContext

WithContext returns wrapped CounterVec with context

func (*CounterVec) WithLabelValues 

func (v *CounterVec) WithLabelValues(lvs ...string) CounterMetric

WithLabelValues returns the Counter for the given slice of label values (same order as the VariableLabels in Desc). If that combination of label values is accessed for the first time, a new Counter is created IFF the counterVec has been registered to a metrics registry.

type CounterVecMetric 

type CounterVecMetric interface {
	WithLabelValues(...string) CounterMetric
	With(prometheus.Labels) CounterMetric
}

CounterVecMetric is an interface which prometheus.CounterVec satisfies.

type CounterVecWithContext added in v0.21.0 

type CounterVecWithContext struct {
	*CounterVec
	// contains filtered or unexported fields
}

CounterVecWithContext is the wrapper of CounterVec with context.

func (CounterVecWithContext) ClearState added in v0.21.0 

func (r CounterVecWithContext) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (CounterVecWithContext) Create added in v0.21.0 

func (r CounterVecWithContext) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (CounterVecWithContext) FQName added in v0.21.0 

func (r CounterVecWithContext) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (CounterVecWithContext) IsCreated added in v0.21.0 

func (r CounterVecWithContext) IsCreated() bool

func (CounterVecWithContext) IsDeprecated added in v0.21.0 

func (r CounterVecWithContext) IsDeprecated() bool

func (CounterVecWithContext) IsHidden added in v0.21.0 

func (r CounterVecWithContext) IsHidden() bool

func (*CounterVecWithContext) With added in v0.21.0 

func (vc *CounterVecWithContext) With(labels map[string]string) CounterMetric

With is the wrapper of CounterVec.With.

func (*CounterVecWithContext) WithLabelValues added in v0.21.0 

func (vc *CounterVecWithContext) WithLabelValues(lvs ...string) CounterMetric

WithLabelValues is the wrapper of CounterVec.WithLabelValues.

type Desc added in v0.17.0 

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

Desc is a prometheus.Desc extension.

Use NewDesc to create new Desc instances.

func NewDesc added in v0.17.0 

func NewDesc(fqName string, help string, variableLabels []string, constLabels Labels,
	stabilityLevel StabilityLevel, deprecatedVersion string) *Desc

NewDesc extends prometheus.NewDesc with stability support.

The stabilityLevel should be valid stability label, such as "metrics.ALPHA" and "metrics.STABLE"(Maybe "metrics.BETA" in future). Default value "metrics.ALPHA" will be used in case of empty or invalid stability label.

The deprecatedVersion represents in which version this Metric be deprecated. The deprecation policy outlined by the control plane metrics stability KEP.

func (*Desc) ClearState added in v0.18.0 

func (d *Desc) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*Desc) DeprecatedVersion added in v0.17.0 

func (d *Desc) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*Desc) GetRawDesc added in v0.17.0 

func (d *Desc) GetRawDesc() *Desc

GetRawDesc will returns a new *Desc with original parameters provided to NewDesc().

It will be useful in testing scenario that the same Desc be registered to different registry.

  1. Desc `D` is registered to registry 'A' in TestA (Note: `D` maybe created)
  2. Desc `D` is registered to registry 'B' in TestB (Note: since 'D' has been created once, thus will be ignored by registry 'B')

func (*Desc) IsCreated added in v0.18.0 

func (d *Desc) IsCreated() bool

IsCreated returns if metric has been created.

func (*Desc) IsDeprecated added in v0.17.0 

func (d *Desc) IsDeprecated() bool

IsDeprecated returns if metric has been deprecated

func (*Desc) IsHidden added in v0.17.0 

func (d *Desc) IsHidden() bool

IsHidden returns if metric will be hidden

func (*Desc) String added in v0.17.0 

func (d *Desc) String() string

String formats the Desc as a string. The stability metadata maybe annotated in 'HELP' section if called after registry, otherwise not. e.g. "Desc{fqName: "normal_stable_descriptor", help: "STABLE this is a stable descriptor", constLabels: {}, variableLabels: []}"

type Gatherer added in v0.17.0 

type Gatherer interface {
	prometheus.Gatherer
}

Gatherer is the interface for the part of a registry in charge of gathering the collected metrics into a number of MetricFamilies.

type Gauge 

type Gauge struct {
	GaugeMetric
	*GaugeOpts
	// contains filtered or unexported fields
}

Gauge is our internal representation for our wrapping struct around prometheus gauges. kubeGauge implements both kubeCollector and KubeGauge.

func NewGauge 

func NewGauge(opts *GaugeOpts) *Gauge

NewGauge returns an object which satisfies the kubeCollector and KubeGauge interfaces. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

func (*Gauge) ClearState added in v0.17.0 

func (r *Gauge) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*Gauge) Collect 

func (c *Gauge) Collect(ch chan<- prometheus.Metric)

func (*Gauge) Create 

func (r *Gauge) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*Gauge) DeprecatedVersion 

func (g *Gauge) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*Gauge) Describe 

func (c *Gauge) Describe(ch chan<- *prometheus.Desc)

func (*Gauge) FQName added in v0.18.0 

func (r *Gauge) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*Gauge) IsCreated 

func (r *Gauge) IsCreated() bool

func (*Gauge) IsDeprecated 

func (r *Gauge) IsDeprecated() bool

func (*Gauge) IsHidden 

func (r *Gauge) IsHidden() bool

func (*Gauge) WithContext added in v0.21.0 

func (g *Gauge) WithContext(ctx context.Context) GaugeMetric

WithContext allows the normal Gauge metric to pass in context. The context is no-op now.

type GaugeFunc added in v0.17.0 

type GaugeFunc interface {
	Metric
	Collector
}

GaugeFunc is a Gauge whose value is determined at collect time by calling a provided function.

To create GaugeFunc instances, use NewGaugeFunc.

func NewGaugeFunc added in v0.17.0 

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

NewGaugeFunc creates a new GaugeFunc based on the provided GaugeOpts. The value reported is determined by calling the given function from within the Write method. Take into account that metric collection may happen concurrently. If that results in concurrent calls to Write, like in the case where a GaugeFunc is directly registered with Prometheus, the provided function must be concurrency-safe.

type GaugeMetric 

type GaugeMetric interface {
	Set(float64)
	Inc()
	Dec()
	Add(float64)
	Write(out *dto.Metric) error
	SetToCurrentTime()
}

GaugeMetric is an interface which defines a subset of the interface provided by prometheus.Gauge

type GaugeOpts 

type GaugeOpts KubeOpts

GaugeOpts is an alias for Opts. See there for doc comments.

type GaugeVec 

type GaugeVec struct {
	*prometheus.GaugeVec
	*GaugeOpts
	// contains filtered or unexported fields
}

GaugeVec is the internal representation of our wrapping struct around prometheus gaugeVecs. kubeGaugeVec implements both kubeCollector and KubeGaugeVec.

func NewGaugeVec 

func NewGaugeVec(opts *GaugeOpts, labels []string) *GaugeVec

NewGaugeVec returns an object which satisfies the kubeCollector and KubeGaugeVec interfaces. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

func (*GaugeVec) ClearState added in v0.17.0 

func (r *GaugeVec) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*GaugeVec) Create 

func (r *GaugeVec) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*GaugeVec) Delete added in v0.16.4 

func (v *GaugeVec) Delete(labels map[string]string) bool

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.

func (*GaugeVec) DeprecatedVersion 

func (v *GaugeVec) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*GaugeVec) FQName added in v0.18.0 

func (r *GaugeVec) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*GaugeVec) IsCreated 

func (r *GaugeVec) IsCreated() bool

func (*GaugeVec) IsDeprecated 

func (r *GaugeVec) IsDeprecated() bool

func (*GaugeVec) IsHidden 

func (r *GaugeVec) IsHidden() bool

func (*GaugeVec) Reset added in v0.17.0 

func (v *GaugeVec) Reset()

Reset deletes all metrics in this vector.

func (*GaugeVec) With 

func (v *GaugeVec) With(labels map[string]string) GaugeMetric

With returns the GaugeMetric for the given Labels map (the label names must match those of the VariableLabels in Desc). If that label map is accessed for the first time, a new GaugeMetric is created IFF the gaugeVec has been registered to a metrics registry.

func (*GaugeVec) WithContext added in v0.21.0 

func (v *GaugeVec) WithContext(ctx context.Context) *GaugeVecWithContext

WithContext returns wrapped GaugeVec with context

func (*GaugeVec) WithLabelValues 

func (v *GaugeVec) WithLabelValues(lvs ...string) GaugeMetric

WithLabelValues returns the GaugeMetric for the given slice of label values (same order as the VariableLabels in Desc). If that combination of label values is accessed for the first time, a new GaugeMetric is created IFF the gaugeVec has been registered to a metrics registry.

type GaugeVecWithContext added in v0.21.0 

type GaugeVecWithContext struct {
	*GaugeVec
	// contains filtered or unexported fields
}

GaugeVecWithContext is the wrapper of GaugeVec with context.

func (GaugeVecWithContext) ClearState added in v0.21.0 

func (r GaugeVecWithContext) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (GaugeVecWithContext) Create added in v0.21.0 

func (r GaugeVecWithContext) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (GaugeVecWithContext) FQName added in v0.21.0 

func (r GaugeVecWithContext) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (GaugeVecWithContext) IsCreated added in v0.21.0 

func (r GaugeVecWithContext) IsCreated() bool

func (GaugeVecWithContext) IsDeprecated added in v0.21.0 

func (r GaugeVecWithContext) IsDeprecated() bool

func (GaugeVecWithContext) IsHidden added in v0.21.0 

func (r GaugeVecWithContext) IsHidden() bool

func (*GaugeVecWithContext) With added in v0.21.0 

func (vc *GaugeVecWithContext) With(labels map[string]string) GaugeMetric

With is the wrapper of GaugeVec.With.

func (*GaugeVecWithContext) WithLabelValues added in v0.21.0 

func (vc *GaugeVecWithContext) WithLabelValues(lvs ...string) GaugeMetric

WithLabelValues is the wrapper of GaugeVec.WithLabelValues.

type HandlerOpts added in v0.17.0 

type HandlerOpts promhttp.HandlerOpts

HandlerOpts specifies options how to serve metrics via an http.Handler. The zero value of HandlerOpts is a reasonable default.

type Histogram 

type Histogram struct {
	ObserverMetric
	*HistogramOpts
	// contains filtered or unexported fields
}

Histogram is our internal representation for our wrapping struct around prometheus histograms. Summary implements both kubeCollector and ObserverMetric

func NewHistogram 

func NewHistogram(opts *HistogramOpts) *Histogram

NewHistogram returns an object which is Histogram-like. However, nothing will be measured until the histogram is registered somewhere.

func (*Histogram) ClearState added in v0.17.0 

func (r *Histogram) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*Histogram) Collect 

func (c *Histogram) Collect(ch chan<- prometheus.Metric)

func (*Histogram) Create 

func (r *Histogram) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*Histogram) DeprecatedVersion 

func (h *Histogram) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*Histogram) Describe 

func (c *Histogram) Describe(ch chan<- *prometheus.Desc)

func (*Histogram) FQName added in v0.18.0 

func (r *Histogram) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*Histogram) IsCreated 

func (r *Histogram) IsCreated() bool

func (*Histogram) IsDeprecated 

func (r *Histogram) IsDeprecated() bool

func (*Histogram) IsHidden 

func (r *Histogram) IsHidden() bool

func (*Histogram) WithContext added in v0.21.0 

func (h *Histogram) WithContext(ctx context.Context) ObserverMetric

WithContext allows the normal Histogram metric to pass in context. The context is no-op now.

type HistogramOpts 

type HistogramOpts struct {
	Namespace         string
	Subsystem         string
	Name              string
	Help              string
	ConstLabels       map[string]string
	Buckets           []float64
	DeprecatedVersion string

	StabilityLevel       StabilityLevel
	LabelValueAllowLists *MetricLabelAllowList
	// contains filtered or unexported fields
}

HistogramOpts bundles the options for creating a Histogram metric. It is mandatory to set Name to a non-empty string. All other fields are optional and can safely be left at their zero value, although it is strongly encouraged to set a Help string.

type HistogramVec 

type HistogramVec struct {
	*prometheus.HistogramVec
	*HistogramOpts
	// contains filtered or unexported fields
}

HistogramVec is the internal representation of our wrapping struct around prometheus histogramVecs.

func NewHistogramVec 

func NewHistogramVec(opts *HistogramOpts, labels []string) *HistogramVec

NewHistogramVec returns an object which satisfies kubeCollector and wraps the prometheus.HistogramVec object. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

func (*HistogramVec) ClearState added in v0.17.0 

func (r *HistogramVec) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*HistogramVec) Create 

func (r *HistogramVec) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*HistogramVec) Delete added in v0.16.4 

func (v *HistogramVec) Delete(labels map[string]string) bool

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.

func (*HistogramVec) DeprecatedVersion 

func (v *HistogramVec) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*HistogramVec) FQName added in v0.18.0 

func (r *HistogramVec) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*HistogramVec) IsCreated 

func (r *HistogramVec) IsCreated() bool

func (*HistogramVec) IsDeprecated 

func (r *HistogramVec) IsDeprecated() bool

func (*HistogramVec) IsHidden 

func (r *HistogramVec) IsHidden() bool

func (*HistogramVec) Reset added in v0.17.0 

func (v *HistogramVec) Reset()

Reset deletes all metrics in this vector.

func (*HistogramVec) With 

func (v *HistogramVec) With(labels map[string]string) ObserverMetric

With returns the ObserverMetric for the given Labels map (the label names must match those of the VariableLabels in Desc). If that label map is accessed for the first time, a new ObserverMetric is created IFF the HistogramVec has been registered to a metrics registry.

func (*HistogramVec) WithContext added in v0.21.0 

func (v *HistogramVec) WithContext(ctx context.Context) *HistogramVecWithContext

WithContext returns wrapped HistogramVec with context

func (*HistogramVec) WithLabelValues 

func (v *HistogramVec) WithLabelValues(lvs ...string) ObserverMetric

WithLabelValues returns the ObserverMetric for the given slice of label values (same order as the VariableLabels in Desc). If that combination of label values is accessed for the first time, a new ObserverMetric is created IFF the HistogramVec has been registered to a metrics registry.

type HistogramVecWithContext added in v0.21.0 

type HistogramVecWithContext struct {
	*HistogramVec
	// contains filtered or unexported fields
}

HistogramVecWithContext is the wrapper of HistogramVec with context.

func (HistogramVecWithContext) ClearState added in v0.21.0 

func (r HistogramVecWithContext) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (HistogramVecWithContext) Create added in v0.21.0 

func (r HistogramVecWithContext) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (HistogramVecWithContext) FQName added in v0.21.0 

func (r HistogramVecWithContext) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (HistogramVecWithContext) IsCreated added in v0.21.0 

func (r HistogramVecWithContext) IsCreated() bool

func (HistogramVecWithContext) IsDeprecated added in v0.21.0 

func (r HistogramVecWithContext) IsDeprecated() bool

func (HistogramVecWithContext) IsHidden added in v0.21.0 

func (r HistogramVecWithContext) IsHidden() bool

func (*HistogramVecWithContext) With added in v0.21.0 

func (vc *HistogramVecWithContext) With(labels map[string]string) ObserverMetric

With is the wrapper of HistogramVec.With.

func (*HistogramVecWithContext) WithLabelValues added in v0.21.0 

func (vc *HistogramVecWithContext) WithLabelValues(lvs ...string) ObserverMetric

WithLabelValues is the wrapper of HistogramVec.WithLabelValues.

type KubeOpts 

type KubeOpts struct {
	Namespace         string
	Subsystem         string
	Name              string
	Help              string
	ConstLabels       map[string]string
	DeprecatedVersion string

	StabilityLevel       StabilityLevel
	LabelValueAllowLists *MetricLabelAllowList
	// contains filtered or unexported fields
}

KubeOpts is superset struct for prometheus.Opts. The prometheus Opts structure is purposefully not embedded here because that would change struct initialization in the manner which people are currently accustomed.

Name must be set to a non-empty string. DeprecatedVersion is defined only if the metric for which this options applies is, in fact, deprecated.

type KubeRegistry 

type KubeRegistry interface {
	// Deprecated
	RawMustRegister(...prometheus.Collector)
	// CustomRegister is our internal variant of Prometheus registry.Register
	CustomRegister(c StableCollector) error
	// CustomMustRegister is our internal variant of Prometheus registry.MustRegister
	CustomMustRegister(cs ...StableCollector)
	// Register conforms to Prometheus registry.Register
	Register(Registerable) error
	// MustRegister conforms to Prometheus registry.MustRegister
	MustRegister(...Registerable)
	// Unregister conforms to Prometheus registry.Unregister
	Unregister(collector Collector) bool
	// Gather conforms to Prometheus gatherer.Gather
	Gather() ([]*dto.MetricFamily, error)
	// Reset invokes the Reset() function on all items in the registry
	// which are added as resettables.
	Reset()
}

KubeRegistry is an interface which implements a subset of prometheus.Registerer and prometheus.Gatherer interfaces

func NewKubeRegistry 

func NewKubeRegistry() KubeRegistry

NewKubeRegistry creates a new vanilla Registry without any Collectors pre-registered.

type Labels added in v0.17.0 

type Labels prometheus.Labels

Labels represents a collection of label name -> value mappings.

type Metric 

type Metric interface {
	Desc() *prometheus.Desc
	Write(*dto.Metric) error
}

Metric defines a subset of prometheus.Metric interface methods

func NewLazyConstMetric added in v0.17.0 

func NewLazyConstMetric(desc *Desc, valueType ValueType, value float64, labelValues ...string) Metric

NewLazyConstMetric is a helper of MustNewConstMetric.

Note: If the metrics described by the desc is hidden, the metrics will not be created.

func NewLazyMetricWithTimestamp added in v0.17.0 

func NewLazyMetricWithTimestamp(t time.Time, m Metric) Metric

NewLazyMetricWithTimestamp is a helper of NewMetricWithTimestamp.

Warning: the Metric 'm' must be the one created by NewLazyConstMetric(), 

otherwise, no stability guarantees would be offered.

type MetricLabelAllowList added in v0.21.0 

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

func (*MetricLabelAllowList) ConstrainLabelMap added in v0.21.0 

func (allowList *MetricLabelAllowList) ConstrainLabelMap(labels map[string]string)

func (*MetricLabelAllowList) ConstrainToAllowedList added in v0.21.0 

func (allowList *MetricLabelAllowList) ConstrainToAllowedList(labelNameList, labelValueList []string)

type ObserverMetric 

type ObserverMetric interface {
	Observe(float64)
}

ObserverMetric captures individual observations.

type Options added in v0.19.0 

type Options struct {
	ShowHiddenMetricsForVersion string
	DisabledMetrics             []string
	AllowListMapping            map[string]string
}

Options has all parameters needed for exposing metrics from components

func NewOptions added in v0.19.0 

func NewOptions() *Options

NewOptions returns default metrics options

func (*Options) AddFlags added in v0.19.0 

func (o *Options) AddFlags(fs *pflag.FlagSet)

AddFlags adds flags for exposing component metrics.

func (*Options) Apply added in v0.19.0 

func (o *Options) Apply()

Apply applies parameters into global configuration of metrics.

func (*Options) Validate added in v0.19.0 

func (o *Options) Validate() []error

Validate validates metrics flags options.

type PromRegistry 

type PromRegistry interface {
	Register(prometheus.Collector) error
	MustRegister(...prometheus.Collector)
	Unregister(prometheus.Collector) bool
	Gather() ([]*dto.MetricFamily, error)
}

PromRegistry is an interface which implements a subset of prometheus.Registerer and prometheus.Gatherer interfaces

type Registerable added in v0.16.4 

type Registerable interface {
	prometheus.Collector

	// Create will mark deprecated state for the collector
	Create(version *semver.Version) bool

	// ClearState will clear all the states marked by Create.
	ClearState()

	// FQName returns the fully-qualified metric name of the collector.
	FQName() string
}

Registerable is an interface for a collector metric which we will register with KubeRegistry.

type StabilityLevel 

type StabilityLevel string

StabilityLevel represents the API guarantees for a given defined metric. 

const (
	// ALPHA metrics have no stability guarantees, as such, labels may
	// be arbitrarily added/removed and the metric may be deleted at any time.
	ALPHA StabilityLevel = "ALPHA"
	// STABLE metrics are guaranteed not be mutated and removal is governed by
	// the deprecation policy outlined in by the control plane metrics stability KEP.
	STABLE StabilityLevel = "STABLE"
)

type StableCollector added in v0.17.0 

type StableCollector interface {
	prometheus.Collector

	// DescribeWithStability sends the super-set of all possible metrics.Desc collected
	// by this StableCollector to the provided channel.
	DescribeWithStability(chan<- *Desc)

	// CollectWithStability sends each collected metrics.Metric via the provide channel.
	CollectWithStability(chan<- Metric)

	// Create will initialize all Desc and it intends to be called by registry.
	Create(version *semver.Version, self StableCollector) bool

	// ClearState will clear all the states marked by Create.
	ClearState()

	// HiddenMetrics tells the list of hidden metrics with fqName.
	HiddenMetrics() []string
}

StableCollector extends the prometheus.Collector interface to allow customization of the metric registration process, it's especially intend to be used in scenario of custom collector.

type Summary 

type Summary struct {
	ObserverMetric
	*SummaryOpts
	// contains filtered or unexported fields
}

Summary is our internal representation for our wrapping struct around prometheus summaries. Summary implements both kubeCollector and ObserverMetric

DEPRECATED: as per the metrics overhaul KEP

func NewSummary 

func NewSummary(opts *SummaryOpts) *Summary

NewSummary returns an object which is Summary-like. However, nothing will be measured until the summary is registered somewhere.

DEPRECATED: as per the metrics overhaul KEP

func (*Summary) ClearState added in v0.17.0 

func (r *Summary) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*Summary) Collect 

func (c *Summary) Collect(ch chan<- prometheus.Metric)

func (*Summary) Create 

func (r *Summary) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*Summary) DeprecatedVersion 

func (s *Summary) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*Summary) Describe 

func (c *Summary) Describe(ch chan<- *prometheus.Desc)

func (*Summary) FQName added in v0.18.0 

func (r *Summary) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*Summary) IsCreated 

func (r *Summary) IsCreated() bool

func (*Summary) IsDeprecated 

func (r *Summary) IsDeprecated() bool

func (*Summary) IsHidden 

func (r *Summary) IsHidden() bool

func (*Summary) WithContext added in v0.21.0 

func (s *Summary) WithContext(ctx context.Context) ObserverMetric

WithContext allows the normal Summary metric to pass in context. The context is no-op now.

type SummaryOpts 

type SummaryOpts struct {
	Namespace         string
	Subsystem         string
	Name              string
	Help              string
	ConstLabels       map[string]string
	Objectives        map[float64]float64
	MaxAge            time.Duration
	AgeBuckets        uint32
	BufCap            uint32
	DeprecatedVersion string

	StabilityLevel       StabilityLevel
	LabelValueAllowLists *MetricLabelAllowList
	// contains filtered or unexported fields
}

SummaryOpts bundles the options for creating a Summary metric. It is mandatory to set Name to a non-empty string. While all other fields are optional and can safely be left at their zero value, it is recommended to set a help string and to explicitly set the Objectives field to the desired value as the default value will change in the upcoming v0.10 of the library.

type SummaryVec 

type SummaryVec struct {
	*prometheus.SummaryVec
	*SummaryOpts
	// contains filtered or unexported fields
}

SummaryVec is the internal representation of our wrapping struct around prometheus summaryVecs.

DEPRECATED: as per the metrics overhaul KEP

func NewSummaryVec 

func NewSummaryVec(opts *SummaryOpts, labels []string) *SummaryVec

NewSummaryVec returns an object which satisfies kubeCollector and wraps the prometheus.SummaryVec object. However, the object returned will not measure anything unless the collector is first registered, since the metric is lazily instantiated.

DEPRECATED: as per the metrics overhaul KEP

func (*SummaryVec) ClearState added in v0.17.0 

func (r *SummaryVec) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (*SummaryVec) Create 

func (r *SummaryVec) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (*SummaryVec) Delete added in v0.16.4 

func (v *SummaryVec) Delete(labels map[string]string) bool

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.

func (*SummaryVec) DeprecatedVersion 

func (v *SummaryVec) DeprecatedVersion() *semver.Version

DeprecatedVersion returns a pointer to the Version or nil

func (*SummaryVec) FQName added in v0.18.0 

func (r *SummaryVec) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (*SummaryVec) IsCreated 

func (r *SummaryVec) IsCreated() bool

func (*SummaryVec) IsDeprecated 

func (r *SummaryVec) IsDeprecated() bool

func (*SummaryVec) IsHidden 

func (r *SummaryVec) IsHidden() bool

func (*SummaryVec) Reset added in v0.17.0 

func (v *SummaryVec) Reset()

Reset deletes all metrics in this vector.

func (*SummaryVec) With 

func (v *SummaryVec) With(labels map[string]string) ObserverMetric

With returns the ObserverMetric for the given Labels map (the label names must match those of the VariableLabels in Desc). If that label map is accessed for the first time, a new ObserverMetric is created IFF the summaryVec has been registered to a metrics registry.

func (*SummaryVec) WithContext added in v0.21.0 

func (v *SummaryVec) WithContext(ctx context.Context) *SummaryVecWithContext

WithContext returns wrapped SummaryVec with context

func (*SummaryVec) WithLabelValues 

func (v *SummaryVec) WithLabelValues(lvs ...string) ObserverMetric

WithLabelValues returns the ObserverMetric for the given slice of label values (same order as the VariableLabels in Desc). If that combination of label values is accessed for the first time, a new ObserverMetric is created IFF the summaryVec has been registered to a metrics registry.

type SummaryVecWithContext added in v0.21.0 

type SummaryVecWithContext struct {
	*SummaryVec
	// contains filtered or unexported fields
}

SummaryVecWithContext is the wrapper of SummaryVec with context.

func (SummaryVecWithContext) ClearState added in v0.21.0 

func (r SummaryVecWithContext) ClearState()

ClearState will clear all the states marked by Create. It intends to be used for re-register a hidden metric.

func (SummaryVecWithContext) Create added in v0.21.0 

func (r SummaryVecWithContext) Create(version *semver.Version) bool

Create forces the initialization of metric which has been deferred until the point at which this method is invoked. This method will determine whether the metric is deprecated or hidden, no-opting if the metric should be considered hidden. Furthermore, this function no-opts and returns true if metric is already created.

func (SummaryVecWithContext) FQName added in v0.21.0 

func (r SummaryVecWithContext) FQName() string

FQName returns the fully-qualified metric name of the collector.

func (SummaryVecWithContext) IsCreated added in v0.21.0 

func (r SummaryVecWithContext) IsCreated() bool

func (SummaryVecWithContext) IsDeprecated added in v0.21.0 

func (r SummaryVecWithContext) IsDeprecated() bool

func (SummaryVecWithContext) IsHidden added in v0.21.0 

func (r SummaryVecWithContext) IsHidden() bool

func (*SummaryVecWithContext) With added in v0.21.0 

func (vc *SummaryVecWithContext) With(labels map[string]string) ObserverMetric

With is the wrapper of SummaryVec.With.

func (*SummaryVecWithContext) WithLabelValues added in v0.21.0 

func (vc *SummaryVecWithContext) WithLabelValues(lvs ...string) ObserverMetric

WithLabelValues is the wrapper of SummaryVec.WithLabelValues.

type ValueType added in v0.17.0 

type ValueType int

ValueType is an enumeration of metric types that represent a simple value. 

const (
	CounterValue ValueType
	GaugeValue
	UntypedValue
)

Possible values for the ValueType enum.

Source Files

View all Source files

Directories

Path Synopsis
prometheus
clientgo
clientgo/leaderelection
controllers
ratelimiter
restclient
version
workqueue

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.