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
• func SanitizeMetricName(name string) 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

Examples

• StopWatch.Start

Functions

func DurationToString

func DurationToString(duration time.Duration) string

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

func SanitizeMetricName

func SanitizeMetricName(name string) string

SanitizeMetricName ensures the generates metric name is compatible with the underlying prometheus library.

Types

type Scope

type Scope interface {
	// NewGauge 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

	// NewGaugeVec 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

	// NewSummary 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

	// NewSummaryWithOptions 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

	// NewSummaryVec 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

	// NewHistogram 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

	// NewHistogramVec 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

	// NewCounter 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

	// NewCounterVec 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

	// NewStopWatch 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

	// NewStopWatchVec 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

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

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

	// NewScopedMetricName 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

NewScope 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

NewTestScope 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
}

StopWatch implements a stopwatch style interface 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)

Observe records a 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

Example

scope := NewTestScope()
stopWatch, _ := scope.NewStopWatch("test", "This is a test stop watch", time.Millisecond)

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

	// Do the operation you want to measure
	time.Sleep(time.Second)
}

func (StopWatch) Time

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

Time 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
}

Timer 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

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