2015-02-02 17:14:36 +03:00
|
|
|
|
// Copyright 2014 The Prometheus Authors
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// 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
|
2013-02-12 05:36:06 +04:00
|
|
|
|
//
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// 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.
|
2012-12-19 14:48:12 +04:00
|
|
|
|
|
2013-04-03 20:33:32 +04:00
|
|
|
|
package prometheus
|
2012-12-19 14:48:12 +04:00
|
|
|
|
|
|
|
|
|
import (
|
2014-05-07 22:08:33 +04:00
|
|
|
|
"errors"
|
2018-01-19 18:21:07 +03:00
|
|
|
|
"math"
|
|
|
|
|
"sync/atomic"
|
2020-01-14 21:22:19 +03:00
|
|
|
|
"time"
|
2018-01-19 18:21:07 +03:00
|
|
|
|
|
|
|
|
|
dto "github.com/prometheus/client_model/go"
|
2012-12-19 14:48:12 +04:00
|
|
|
|
)
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// Counter is a Metric that represents a single numerical value that only ever
|
|
|
|
|
// goes up. That implies that it cannot be used to count items whose number can
|
|
|
|
|
// also go down, e.g. the number of currently running goroutines. Those
|
|
|
|
|
// "counters" are represented by Gauges.
|
|
|
|
|
//
|
|
|
|
|
// A Counter is typically used to count requests served, tasks completed, errors
|
|
|
|
|
// occurred, etc.
|
|
|
|
|
//
|
|
|
|
|
// To create Counter instances, use NewCounter.
|
2013-01-19 17:48:30 +04:00
|
|
|
|
type Counter interface {
|
2013-04-19 15:22:59 +04:00
|
|
|
|
Metric
|
2014-05-07 22:08:33 +04:00
|
|
|
|
Collector
|
|
|
|
|
|
2016-11-18 18:29:59 +03:00
|
|
|
|
// Inc increments the counter by 1. Use Add to increment it by arbitrary
|
|
|
|
|
// non-negative values.
|
2014-05-07 22:08:33 +04:00
|
|
|
|
Inc()
|
|
|
|
|
// Add adds the given value to the counter. It panics if the value is <
|
|
|
|
|
// 0.
|
|
|
|
|
Add(float64)
|
2020-01-26 01:40:35 +03:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ExemplarAdder is implemented by Counters that offer the option of adding a
|
|
|
|
|
// value to the Counter together with an exemplar. Its AddWithExemplar method
|
|
|
|
|
// works like the Add method of the Counter interface but also replaces the
|
|
|
|
|
// currently saved exemplar (if any) with a new one, created from the provided
|
|
|
|
|
// value, the current time as timestamp, and the provided labels. Empty Labels
|
|
|
|
|
// will lead to a valid (label-less) exemplar. But if Labels is nil, the current
|
|
|
|
|
// exemplar is left in place. AddWithExemplar panics if the value is < 0, if any
|
|
|
|
|
// of the provided labels are invalid, or if the provided labels contain more
|
|
|
|
|
// than 64 runes in total.
|
|
|
|
|
type ExemplarAdder interface {
|
2020-01-14 21:22:19 +03:00
|
|
|
|
AddWithExemplar(value float64, exemplar Labels)
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// CounterOpts is an alias for Opts. See there for doc comments.
|
|
|
|
|
type CounterOpts Opts
|
|
|
|
|
|
|
|
|
|
// NewCounter creates a new Counter based on the provided CounterOpts.
|
2018-01-19 18:21:07 +03:00
|
|
|
|
//
|
2020-01-26 01:40:35 +03:00
|
|
|
|
// The returned implementation also implements ExemplarAdder. It is safe to
|
|
|
|
|
// perform the corresponding type assertion.
|
|
|
|
|
//
|
2018-01-19 18:21:07 +03:00
|
|
|
|
// The returned implementation tracks the counter value in two separate
|
|
|
|
|
// variables, a float64 and a uint64. The latter is used to track calls of the
|
|
|
|
|
// Inc method and calls of the Add method with a value that can be represented
|
|
|
|
|
// as a uint64. This allows atomic increments of the counter with optimal
|
|
|
|
|
// performance. (It is common to have an Inc call in very hot execution paths.)
|
|
|
|
|
// Both internal tracking values are added up in the Write method. This has to
|
|
|
|
|
// be taken into account when it comes to precision and overflow behavior.
|
2014-05-07 22:08:33 +04:00
|
|
|
|
func NewCounter(opts CounterOpts) Counter {
|
|
|
|
|
desc := NewDesc(
|
|
|
|
|
BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
|
|
|
|
|
opts.Help,
|
|
|
|
|
nil,
|
|
|
|
|
opts.ConstLabels,
|
|
|
|
|
)
|
2020-01-24 15:34:44 +03:00
|
|
|
|
result := &counter{desc: desc, labelPairs: desc.constLabelPairs, now: time.Now}
|
2016-08-03 02:09:27 +03:00
|
|
|
|
result.init(result) // Init self-collection.
|
2014-05-07 22:08:33 +04:00
|
|
|
|
return result
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
type counter struct {
|
2018-01-19 18:21:07 +03:00
|
|
|
|
// valBits contains the bits of the represented float64 value, while
|
|
|
|
|
// valInt stores values that are exact integers. Both have to go first
|
|
|
|
|
// in the struct to guarantee alignment for atomic operations.
|
|
|
|
|
// http://golang.org/pkg/sync/atomic/#pkg-note-BUG
|
|
|
|
|
valBits uint64
|
|
|
|
|
valInt uint64
|
|
|
|
|
|
|
|
|
|
selfCollector
|
|
|
|
|
desc *Desc
|
|
|
|
|
|
|
|
|
|
labelPairs []*dto.LabelPair
|
2020-01-14 21:22:19 +03:00
|
|
|
|
exemplar atomic.Value // Containing nil or a *dto.Exemplar.
|
2020-01-24 15:34:44 +03:00
|
|
|
|
|
|
|
|
|
now func() time.Time // To mock out time.Now() for testing.
|
2018-01-19 18:21:07 +03:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (c *counter) Desc() *Desc {
|
|
|
|
|
return c.desc
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
func (c *counter) Add(v float64) {
|
|
|
|
|
if v < 0 {
|
|
|
|
|
panic(errors.New("counter cannot decrease in value"))
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
2020-01-14 21:22:19 +03:00
|
|
|
|
|
2018-01-19 18:21:07 +03:00
|
|
|
|
ival := uint64(v)
|
|
|
|
|
if float64(ival) == v {
|
|
|
|
|
atomic.AddUint64(&c.valInt, ival)
|
|
|
|
|
return
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
for {
|
|
|
|
|
oldBits := atomic.LoadUint64(&c.valBits)
|
|
|
|
|
newBits := math.Float64bits(math.Float64frombits(oldBits) + v)
|
|
|
|
|
if atomic.CompareAndSwapUint64(&c.valBits, oldBits, newBits) {
|
|
|
|
|
return
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2020-01-14 21:22:19 +03:00
|
|
|
|
func (c *counter) AddWithExemplar(v float64, e Labels) {
|
|
|
|
|
c.Add(v)
|
|
|
|
|
c.updateExemplar(v, e)
|
|
|
|
|
}
|
|
|
|
|
|
2018-01-19 18:21:07 +03:00
|
|
|
|
func (c *counter) Inc() {
|
|
|
|
|
atomic.AddUint64(&c.valInt, 1)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (c *counter) Write(out *dto.Metric) error {
|
|
|
|
|
fval := math.Float64frombits(atomic.LoadUint64(&c.valBits))
|
|
|
|
|
ival := atomic.LoadUint64(&c.valInt)
|
|
|
|
|
val := fval + float64(ival)
|
|
|
|
|
|
2020-01-14 21:22:19 +03:00
|
|
|
|
var exemplar *dto.Exemplar
|
|
|
|
|
if e := c.exemplar.Load(); e != nil {
|
|
|
|
|
exemplar = e.(*dto.Exemplar)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return populateMetric(CounterValue, val, c.labelPairs, exemplar, out)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (c *counter) updateExemplar(v float64, l Labels) {
|
|
|
|
|
if l == nil {
|
|
|
|
|
return
|
|
|
|
|
}
|
2020-01-24 15:34:44 +03:00
|
|
|
|
e, err := newExemplar(v, c.now(), l)
|
2020-01-14 21:22:19 +03:00
|
|
|
|
if err != nil {
|
|
|
|
|
panic(err)
|
|
|
|
|
}
|
|
|
|
|
c.exemplar.Store(e)
|
2012-12-19 14:48:12 +04:00
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// CounterVec is a Collector that bundles a set of Counters 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
|
2015-02-19 17:34:04 +03:00
|
|
|
|
// (e.g. number of HTTP requests, partitioned by response code and
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// method). Create instances with NewCounterVec.
|
|
|
|
|
type CounterVec struct {
|
2017-06-28 18:55:59 +03:00
|
|
|
|
*metricVec
|
2014-02-19 17:53:34 +04:00
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// NewCounterVec creates a new CounterVec based on the provided CounterOpts and
|
2017-06-28 18:55:59 +03:00
|
|
|
|
// partitioned by the given label names.
|
2014-05-07 22:08:33 +04:00
|
|
|
|
func NewCounterVec(opts CounterOpts, labelNames []string) *CounterVec {
|
|
|
|
|
desc := NewDesc(
|
|
|
|
|
BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
|
|
|
|
|
opts.Help,
|
|
|
|
|
labelNames,
|
|
|
|
|
opts.ConstLabels,
|
|
|
|
|
)
|
|
|
|
|
return &CounterVec{
|
2017-06-28 18:55:59 +03:00
|
|
|
|
metricVec: newMetricVec(desc, func(lvs ...string) Metric {
|
2018-01-19 18:21:07 +03:00
|
|
|
|
if len(lvs) != len(desc.variableLabels) {
|
2018-11-02 19:01:14 +03:00
|
|
|
|
panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))
|
2018-01-19 18:21:07 +03:00
|
|
|
|
}
|
|
|
|
|
result := &counter{desc: desc, labelPairs: makeLabelPairs(desc, lvs)}
|
2016-08-11 06:03:15 +03:00
|
|
|
|
result.init(result) // Init self-collection.
|
|
|
|
|
return result
|
|
|
|
|
}),
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
2012-12-19 14:48:12 +04:00
|
|
|
|
}
|
|
|
|
|
|
2017-06-28 18:55:59 +03:00
|
|
|
|
// GetMetricWithLabelValues 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.
|
|
|
|
|
//
|
|
|
|
|
// It is possible to call this method without using the returned Counter to only
|
|
|
|
|
// create the new Counter but leave it at its starting value 0. See also the
|
|
|
|
|
// SummaryVec example.
|
|
|
|
|
//
|
|
|
|
|
// Keeping the Counter 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 Counter from the CounterVec. In that case,
|
|
|
|
|
// the Counter will still exist, but it will not be exported anymore, even if a
|
|
|
|
|
// Counter with the same label values is created later.
|
|
|
|
|
//
|
|
|
|
|
// An error is returned if the number of label values is not the same as the
|
2017-08-30 02:05:29 +03:00
|
|
|
|
// number of VariableLabels in Desc (minus any curried labels).
|
2017-06-28 18:55:59 +03:00
|
|
|
|
//
|
|
|
|
|
// 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).
|
|
|
|
|
// See also the GaugeVec example.
|
2017-08-29 15:51:49 +03:00
|
|
|
|
func (v *CounterVec) GetMetricWithLabelValues(lvs ...string) (Counter, error) {
|
|
|
|
|
metric, err := v.metricVec.getMetricWithLabelValues(lvs...)
|
2014-05-07 22:08:33 +04:00
|
|
|
|
if metric != nil {
|
|
|
|
|
return metric.(Counter), err
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
2014-05-07 22:08:33 +04:00
|
|
|
|
return nil, err
|
2012-12-19 14:48:12 +04:00
|
|
|
|
}
|
|
|
|
|
|
2017-06-28 18:55:59 +03:00
|
|
|
|
// GetMetricWith 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. Implications of
|
|
|
|
|
// creating a Counter without using it and keeping the Counter for later use are
|
|
|
|
|
// the same as for GetMetricWithLabelValues.
|
|
|
|
|
//
|
|
|
|
|
// An error is returned if the number and names of the Labels are inconsistent
|
2017-08-30 02:05:29 +03:00
|
|
|
|
// with those of the VariableLabels in Desc (minus any curried labels).
|
2017-06-28 18:55:59 +03:00
|
|
|
|
//
|
|
|
|
|
// This method is used for the same purpose as
|
|
|
|
|
// GetMetricWithLabelValues(...string). See there for pros and cons of the two
|
|
|
|
|
// methods.
|
2017-08-29 15:51:49 +03:00
|
|
|
|
func (v *CounterVec) GetMetricWith(labels Labels) (Counter, error) {
|
|
|
|
|
metric, err := v.metricVec.getMetricWith(labels)
|
2014-05-07 22:08:33 +04:00
|
|
|
|
if metric != nil {
|
|
|
|
|
return metric.(Counter), err
|
2013-01-19 17:48:30 +04:00
|
|
|
|
}
|
2014-05-07 22:08:33 +04:00
|
|
|
|
return nil, err
|
2012-12-19 14:48:12 +04:00
|
|
|
|
}
|
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// WithLabelValues works as GetMetricWithLabelValues, but panics where
|
2017-08-30 02:05:29 +03:00
|
|
|
|
// GetMetricWithLabelValues would have returned an error. Not returning an
|
|
|
|
|
// error allows shortcuts like
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// myVec.WithLabelValues("404", "GET").Add(42)
|
2017-08-29 15:51:49 +03:00
|
|
|
|
func (v *CounterVec) WithLabelValues(lvs ...string) Counter {
|
|
|
|
|
c, err := v.GetMetricWithLabelValues(lvs...)
|
2017-08-29 15:43:37 +03:00
|
|
|
|
if err != nil {
|
|
|
|
|
panic(err)
|
|
|
|
|
}
|
|
|
|
|
return c
|
2012-12-19 14:48:12 +04:00
|
|
|
|
}
|
2013-06-27 20:46:16 +04:00
|
|
|
|
|
2014-05-07 22:08:33 +04:00
|
|
|
|
// With works as GetMetricWith, but panics where GetMetricWithLabels would have
|
2017-08-30 02:05:29 +03:00
|
|
|
|
// returned an error. Not returning an error allows shortcuts like
|
|
|
|
|
// myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Add(42)
|
2017-08-29 15:51:49 +03:00
|
|
|
|
func (v *CounterVec) With(labels Labels) Counter {
|
|
|
|
|
c, err := v.GetMetricWith(labels)
|
2017-08-29 15:43:37 +03:00
|
|
|
|
if err != nil {
|
|
|
|
|
panic(err)
|
|
|
|
|
}
|
|
|
|
|
return c
|
2013-06-27 20:46:16 +04:00
|
|
|
|
}
|
2014-06-23 16:15:35 +04:00
|
|
|
|
|
2017-08-30 02:05:29 +03:00
|
|
|
|
// 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 CounterVec 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 *CounterVec) CurryWith(labels Labels) (*CounterVec, error) {
|
|
|
|
|
vec, err := v.curryWith(labels)
|
|
|
|
|
if vec != nil {
|
|
|
|
|
return &CounterVec{vec}, err
|
|
|
|
|
}
|
|
|
|
|
return nil, err
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// MustCurryWith works as CurryWith but panics where CurryWith would have
|
|
|
|
|
// returned an error.
|
|
|
|
|
func (v *CounterVec) MustCurryWith(labels Labels) *CounterVec {
|
|
|
|
|
vec, err := v.CurryWith(labels)
|
|
|
|
|
if err != nil {
|
|
|
|
|
panic(err)
|
|
|
|
|
}
|
|
|
|
|
return vec
|
|
|
|
|
}
|
|
|
|
|
|
2014-06-23 16:15:35 +04:00
|
|
|
|
// CounterFunc is a Counter whose value is determined at collect time by calling a
|
|
|
|
|
// provided function.
|
|
|
|
|
//
|
|
|
|
|
// To create CounterFunc instances, use NewCounterFunc.
|
|
|
|
|
type CounterFunc interface {
|
|
|
|
|
Metric
|
|
|
|
|
Collector
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// NewCounterFunc creates a new CounterFunc based on the provided
|
|
|
|
|
// CounterOpts. 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 CounterFunc is directly registered with Prometheus, the
|
|
|
|
|
// provided function must be concurrency-safe. The function should also honor
|
|
|
|
|
// the contract for a Counter (values only go up, not down), but compliance will
|
|
|
|
|
// not be checked.
|
|
|
|
|
func NewCounterFunc(opts CounterOpts, function func() float64) CounterFunc {
|
|
|
|
|
return newValueFunc(NewDesc(
|
|
|
|
|
BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
|
|
|
|
|
opts.Help,
|
|
|
|
|
nil,
|
|
|
|
|
opts.ConstLabels,
|
|
|
|
|
), CounterValue, function)
|
|
|
|
|
}
|