promutils

Documentation

Overview

Source: https://raw.githubusercontent.com/kubernetes/kubernetes/3dbbd0bdf44cb07fdde85aa392adf99ea7e95939/pkg/util/workqueue/prometheus/prometheus.go

Copyright 2016 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• func DurationToString(duration time.Duration) string
• type Scope
  • func NewScope(name string) Scope
  • func NewTestScope() Scope
• type StopWatch
  • func (s StopWatch) Observe(start, end time.Time)
  • func (s StopWatch) Start() Timer
  • func (s StopWatch) Time(f func())
• type StopWatchVec
  • func (s StopWatchVec) GetMetricWith(labels prometheus.Labels) (StopWatch, error)
  • func (s StopWatchVec) WithLabelValues(values ...string) StopWatch
• type SummaryOptions
• type Timer
  • func (s Timer) Stop() float64

Functions

func DurationToString

func DurationToString(duration time.Duration) string

DurationToString converts the duration to a string suffix that indicates the scale of the timer.

Types

type Scope

type Scope interface {
	// Creates new prometheus.Gauge metric with the prefix as the CurrentScope
	// Name is a string that follows prometheus conventions (mostly [_a-z])
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewGauge(name, description string) (prometheus.Gauge, error)
	MustNewGauge(name, description string) prometheus.Gauge

	// Creates new prometheus.GaugeVec metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewGaugeVec(name, description string, labelNames ...string) (*prometheus.GaugeVec, error)
	MustNewGaugeVec(name, description string, labelNames ...string) *prometheus.GaugeVec

	// Creates new prometheus.Summary metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewSummary(name, description string) (prometheus.Summary, error)
	MustNewSummary(name, description string) prometheus.Summary

	// Creates new prometheus.Summary metric with custom options, such as a custom set of objectives (i.e., target quantiles).
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewSummaryWithOptions(name, description string, options SummaryOptions) (prometheus.Summary, error)
	MustNewSummaryWithOptions(name, description string, options SummaryOptions) prometheus.Summary

	// Creates new prometheus.SummaryVec metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewSummaryVec(name, description string, labelNames ...string) (*prometheus.SummaryVec, error)
	MustNewSummaryVec(name, description string, labelNames ...string) *prometheus.SummaryVec

	// Creates new prometheus.Histogram metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewHistogram(name, description string) (prometheus.Histogram, error)
	MustNewHistogram(name, description string) prometheus.Histogram

	// Creates new prometheus.HistogramVec metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewHistogramVec(name, description string, labelNames ...string) (*prometheus.HistogramVec, error)
	MustNewHistogramVec(name, description string, labelNames ...string) *prometheus.HistogramVec

	// Creates new prometheus.Counter metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	// Important to note, counters are not like typical counters. These are ever increasing and cumulative.
	// So if you want to observe counters within buckets use Summary/Histogram
	NewCounter(name, description string) (prometheus.Counter, error)
	MustNewCounter(name, description string) prometheus.Counter

	// Creates new prometheus.GaugeVec metric with the prefix as the CurrentScope
	// Refer to https://prometheus.io/docs/concepts/metric_types/ for more information
	NewCounterVec(name, description string, labelNames ...string) (*prometheus.CounterVec, error)
	MustNewCounterVec(name, description string, labelNames ...string) *prometheus.CounterVec

	// This is a custom wrapper to create a StopWatch object in the current Scope.
	// Duration is to specify the scale of the Timer. For example if you are measuring times in milliseconds
	// pass scale=times.Millisecond
	// https://golang.org/pkg/time/#Duration
	// The metric name is auto-suffixed with the right scale. Refer to DurationToString to understand
	NewStopWatch(name, description string, scale time.Duration) (StopWatch, error)
	MustNewStopWatch(name, description string, scale time.Duration) StopWatch

	// This is a custom wrapper to create a StopWatch object in the current Scope.
	// Duration is to specify the scale of the Timer. For example if you are measuring times in milliseconds
	// pass scale=times.Millisecond
	// https://golang.org/pkg/time/#Duration
	// The metric name is auto-suffixed with the right scale. Refer to DurationToString to understand
	NewStopWatchVec(name, description string, scale time.Duration, labelNames ...string) (*StopWatchVec, error)
	MustNewStopWatchVec(name, description string, scale time.Duration, labelNames ...string) *StopWatchVec

	// In case nesting is desired for metrics, create a new subScope. This is generally useful in creating
	// Scoped and SubScoped metrics
	NewSubScope(name string) Scope

	// Returns the current ScopeName. Use for creating your own metrics
	CurrentScope() string

	// Method that provides a scoped metric name. Can be used, if you want to directly create your own metric
	NewScopedMetricName(name string) string
}

A Scope represents a prefix in Prometheus. It is nestable, thus every metric that is published does not need to provide a prefix, but just the name of the metric. As long as the Scope is used to create a new instance of the metric The prefix (or scope) is automatically set.

func NewScope

func NewScope(name string) Scope

Creates a new scope in the format `name + defaultScopeDelimiterRune` If the last character is already a defaultScopeDelimiterRune, then it does not add it to the scope name

func NewTestScope

func NewTestScope() Scope

Returns a randomly-named scope for use in tests. Prometheus requires that metric names begin with a single word, which is generated from the alphabetic testScopeNameCharset.

type StopWatch

type StopWatch struct {
	prometheus.Observer
	// contains filtered or unexported fields
}

A Simple StopWatch that works with prometheus summary It will scale the output to match the expected time scale (milliseconds, seconds etc) NOTE: Do not create a StopWatch object by hand, use a Scope to get a new instance of the StopWatch object

func (StopWatch) Observe

func (s StopWatch) Observe(start, end time.Time)

Observes specified duration between the start and end time

func (StopWatch) Start

func (s StopWatch) Start() Timer

Start creates a new Instance of the StopWatch called a Timer that is closeable/stoppable. Common pattern to time a scope would be

{
  timer := stopWatch.Start()
  defer timer.Stop()
  ....
}

func (StopWatch) Time

func (s StopWatch) Time(f func())

Observes/records the time to execute the given function synchronously

type StopWatchVec

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

A Simple StopWatch that works with prometheus summary It will scale the output to match the expected time scale (milliseconds, seconds etc) NOTE: Do not create a StopWatch object by hand, use a Scope to get a new instance of the StopWatch object

func (StopWatchVec) GetMetricWith

func (s StopWatchVec) GetMetricWith(labels prometheus.Labels) (StopWatch, error)

func (StopWatchVec) WithLabelValues

func (s StopWatchVec) WithLabelValues(values ...string) StopWatch

Gets a concrete StopWatch instance that can be used to start a timer and record observations.

type SummaryOptions

type SummaryOptions struct {
	// An Objectives defines the quantile rank estimates with their respective absolute errors.
	// Refer to https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts for details
	Objectives map[float64]float64
}

A SummaryOptions represents a set of options that can be supplied when creating a new prometheus summary metric

type Timer

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

This is a stoppable instance of a StopWatch or a Timer A Timer can only be stopped. On stopping it will output the elapsed duration to prometheus

func (Timer) Stop

func (s Timer) Stop() float64

This method observes the elapsed duration since the creation of the timer. The timer is created using a StopWatch