Code refactoring for bpa operator

[icn.git] / cmd / bpa-operator / vendor / github.com / prometheus / client_golang / prometheus / gauge.go

// Copyright 2014 The Prometheus 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.

package prometheus

import (
        "math"
        "sync/atomic"
        "time"

        dto "github.com/prometheus/client_model/go"
)

// Gauge is a Metric that represents a single numerical value that can
// arbitrarily go up and down.
//
// A Gauge is typically used for measured values like temperatures or current
// memory usage, but also "counts" that can go up and down, like the number of
// running goroutines.
//
// To create Gauge instances, use NewGauge.
type Gauge interface {
        Metric
        Collector

        // Set sets the Gauge to an arbitrary value.
        Set(float64)
        // Inc increments the Gauge by 1. Use Add to increment it by arbitrary
        // values.
        Inc()
        // Dec decrements the Gauge by 1. Use Sub to decrement it by arbitrary
        // values.
        Dec()
        // Add adds the given value to the Gauge. (The value can be negative,
        // resulting in a decrease of the Gauge.)
        Add(float64)
        // Sub subtracts the given value from the Gauge. (The value can be
        // negative, resulting in an increase of the Gauge.)
        Sub(float64)

        // SetToCurrentTime sets the Gauge to the current Unix time in seconds.
        SetToCurrentTime()
}

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

// NewGauge creates a new Gauge based on the provided GaugeOpts.
//
// The returned implementation is optimized for a fast Set method. If you have a
// choice for managing the value of a Gauge via Set vs. Inc/Dec/Add/Sub, pick
// the former. For example, the Inc method of the returned Gauge is slower than
// the Inc method of a Counter returned by NewCounter. This matches the typical
// scenarios for Gauges and Counters, where the former tends to be Set-heavy and
// the latter Inc-heavy.
func NewGauge(opts GaugeOpts) Gauge {
        desc := NewDesc(
                BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
                opts.Help,
                nil,
                opts.ConstLabels,
        )
        result := &gauge{desc: desc, labelPairs: desc.constLabelPairs}
        result.init(result) // Init self-collection.
        return result
}

type gauge struct {
        // valBits contains the bits of the represented float64 value. It has
        // to go first in the struct to guarantee alignment for atomic
        // operations.  http://golang.org/pkg/sync/atomic/#pkg-note-BUG
        valBits uint64

        selfCollector

        desc       *Desc
        labelPairs []*dto.LabelPair
}

func (g *gauge) Desc() *Desc {
        return g.desc
}

func (g *gauge) Set(val float64) {
        atomic.StoreUint64(&g.valBits, math.Float64bits(val))
}

func (g *gauge) SetToCurrentTime() {
        g.Set(float64(time.Now().UnixNano()) / 1e9)
}

func (g *gauge) Inc() {
        g.Add(1)
}

func (g *gauge) Dec() {
        g.Add(-1)
}

func (g *gauge) Add(val float64) {
        for {
                oldBits := atomic.LoadUint64(&g.valBits)
                newBits := math.Float64bits(math.Float64frombits(oldBits) + val)
                if atomic.CompareAndSwapUint64(&g.valBits, oldBits, newBits) {
                        return
                }
        }
}

func (g *gauge) Sub(val float64) {
        g.Add(val * -1)
}

func (g *gauge) Write(out *dto.Metric) error {
        val := math.Float64frombits(atomic.LoadUint64(&g.valBits))
        return populateMetric(GaugeValue, val, g.labelPairs, out)
}

// GaugeVec is a Collector that bundles a set of Gauges that all share the same
// Desc, but have different values for their variable labels. This is used if
// you want to count the same thing partitioned by various dimensions
// (e.g. number of operations queued, partitioned by user and operation
// type). Create instances with NewGaugeVec.
type GaugeVec struct {
        *metricVec
}

// NewGaugeVec creates a new GaugeVec based on the provided GaugeOpts and
// partitioned by the given label names.
func NewGaugeVec(opts GaugeOpts, labelNames []string) *GaugeVec {
        desc := NewDesc(
                BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
                opts.Help,
                labelNames,
                opts.ConstLabels,
        )
        return &GaugeVec{
                metricVec: newMetricVec(desc, func(lvs ...string) Metric {
                        if len(lvs) != len(desc.variableLabels) {
                                panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))
                        }
                        result := &gauge{desc: desc, labelPairs: makeLabelPairs(desc, lvs)}
                        result.init(result) // Init self-collection.
                        return result
                }),
        }
}

// GetMetricWithLabelValues returns the Gauge 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 Gauge is created.
//
// It is possible to call this method without using the returned Gauge to only
// create the new Gauge but leave it at its starting value 0. See also the
// SummaryVec example.
//
// Keeping the Gauge 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 Gauge from the GaugeVec. In that case, the
// Gauge will still exist, but it will not be exported anymore, even if a
// Gauge with the same label values is created later. See also the CounterVec
// example.
//
// An error is returned if the number of label values is not the same as the
// number of VariableLabels 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).
func (v *GaugeVec) GetMetricWithLabelValues(lvs ...string) (Gauge, error) {
        metric, err := v.metricVec.getMetricWithLabelValues(lvs...)
        if metric != nil {
                return metric.(Gauge), err
        }
        return nil, err
}

// GetMetricWith returns the Gauge 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 Gauge is created. Implications of
// creating a Gauge without using it and keeping the Gauge 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 VariableLabels 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.
func (v *GaugeVec) GetMetricWith(labels Labels) (Gauge, error) {
        metric, err := v.metricVec.getMetricWith(labels)
        if metric != nil {
                return metric.(Gauge), err
        }
        return nil, err
}

// 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)
func (v *GaugeVec) WithLabelValues(lvs ...string) Gauge {
        g, err := v.GetMetricWithLabelValues(lvs...)
        if err != nil {
                panic(err)
        }
        return g
}

// 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)
func (v *GaugeVec) With(labels Labels) Gauge {
        g, err := v.GetMetricWith(labels)
        if err != nil {
                panic(err)
        }
        return g
}

// 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 GaugeVec 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.
func (v *GaugeVec) CurryWith(labels Labels) (*GaugeVec, error) {
        vec, err := v.curryWith(labels)
        if vec != nil {
                return &GaugeVec{vec}, err
        }
        return nil, err
}

// MustCurryWith works as CurryWith but panics where CurryWith would have
// returned an error.
func (v *GaugeVec) MustCurryWith(labels Labels) *GaugeVec {
        vec, err := v.CurryWith(labels)
        if err != nil {
                panic(err)
        }
        return vec
}

// GaugeFunc is a Gauge whose value is determined at collect time by calling a
// provided function.
//
// To create GaugeFunc instances, use NewGaugeFunc.
type GaugeFunc interface {
        Metric
        Collector
}

// 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.
func NewGaugeFunc(opts GaugeOpts, function func() float64) GaugeFunc {
        return newValueFunc(NewDesc(
                BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
                opts.Help,
                nil,
                opts.ConstLabels,
        ), GaugeValue, function)
}