1
// Copyright 2014 The Prometheus Authors
2
// Licensed under the Apache License, Version 2.0 (the "License");
3
// you may not use this file except in compliance with the License.
4
// You may obtain a copy of the License at
6
// http://www.apache.org/licenses/LICENSE-2.0
8
// Unless required by applicable law or agreed to in writing, software
9
// distributed under the License is distributed on an "AS IS" BASIS,
10
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11
// See the License for the specific language governing permissions and
12
// limitations under the License.
19
dto "github.com/prometheus/client_model/go"
22
const separatorByte byte = 255
24
// A Metric models a single sample value with its meta data being exported to
25
// Prometheus. Implementations of Metric in this package are Gauge, Counter,
26
// Histogram, Summary, and Untyped.
27
type Metric interface {
28
// Desc returns the descriptor for the Metric. This method idempotently
29
// returns the same descriptor throughout the lifetime of the
30
// Metric. The returned descriptor is immutable by contract. A Metric
31
// unable to describe itself must return an invalid descriptor (created
32
// with NewInvalidDesc).
34
// Write encodes the Metric into a "Metric" Protocol Buffer data
35
// transmission object.
37
// Metric implementations must observe concurrency safety as reads of
38
// this metric may occur at any time, and any blocking occurs at the
39
// expense of total performance of rendering all registered
40
// metrics. Ideally, Metric implementations should support concurrent
43
// While populating dto.Metric, it is the responsibility of the
44
// implementation to ensure validity of the Metric protobuf (like valid
45
// UTF-8 strings or syntactically valid metric and label names). It is
46
// recommended to sort labels lexicographically. (Implementers may find
47
// LabelPairSorter useful for that.) Callers of Write should still make
48
// sure of sorting if they depend on it.
49
Write(*dto.Metric) error
50
// TODO(beorn7): The original rationale of passing in a pre-allocated
51
// dto.Metric protobuf to save allocations has disappeared. The
52
// signature of this method should be changed to "Write() (*dto.Metric,
56
// Opts bundles the options for creating most Metric types. Each metric
57
// implementation XXX has its own XXXOpts type, but in most cases, it is just be
58
// an alias of this type (which might change when the requirement arises.)
60
// It is mandatory to set Name and Help to a non-empty string. All other fields
61
// are optional and can safely be left at their zero value.
63
// Namespace, Subsystem, and Name are components of the fully-qualified
64
// name of the Metric (created by joining these components with
65
// "_"). Only Name is mandatory, the others merely help structuring the
66
// name. Note that the fully-qualified name of the metric must be a
67
// valid Prometheus metric name.
72
// Help provides information about this metric. Mandatory!
74
// Metrics with the same fully-qualified name must have the same Help
78
// ConstLabels are used to attach fixed labels to this metric. Metrics
79
// with the same fully-qualified name must have the same label names in
82
// Note that in most cases, labels have a value that varies during the
83
// lifetime of a process. Those labels are usually managed with a metric
84
// vector collector (like CounterVec, GaugeVec, UntypedVec). ConstLabels
85
// serve only special purposes. One is for the special case where the
86
// value of a label does not change during the lifetime of a process,
87
// e.g. if the revision of the running binary is put into a
88
// label. Another, more advanced purpose is if more than one Collector
89
// needs to collect Metrics with the same fully-qualified name. In that
90
// case, those Metrics must differ in the values of their
91
// ConstLabels. See the Collector examples.
93
// If the value of a label never changes (not even between binaries),
94
// that label most likely should not be a label at all (but part of the
99
// BuildFQName joins the given three name components by "_". Empty name
100
// components are ignored. If the name parameter itself is empty, an empty
101
// string is returned, no matter what. Metric implementations included in this
102
// library use this function internally to generate the fully-qualified metric
103
// name from the name component in their Opts. Users of the library will only
104
// need this function if they implement their own Metric or instantiate a Desc
105
// (with NewDesc) directly.
106
func BuildFQName(namespace, subsystem, name string) string {
111
case namespace != "" && subsystem != "":
112
return strings.Join([]string{namespace, subsystem, name}, "_")
113
case namespace != "":
114
return strings.Join([]string{namespace, name}, "_")
115
case subsystem != "":
116
return strings.Join([]string{subsystem, name}, "_")
121
// LabelPairSorter implements sort.Interface. It is used to sort a slice of
122
// dto.LabelPair pointers. This is useful for implementing the Write method of
124
type LabelPairSorter []*dto.LabelPair
126
func (s LabelPairSorter) Len() int {
130
func (s LabelPairSorter) Swap(i, j int) {
131
s[i], s[j] = s[j], s[i]
134
func (s LabelPairSorter) Less(i, j int) bool {
135
return s[i].GetName() < s[j].GetName()
138
type hashSorter []uint64
140
func (s hashSorter) Len() int {
144
func (s hashSorter) Swap(i, j int) {
145
s[i], s[j] = s[j], s[i]
148
func (s hashSorter) Less(i, j int) bool {
152
type invalidMetric struct {
157
// NewInvalidMetric returns a metric whose Write method always returns the
158
// provided error. It is useful if a Collector finds itself unable to collect
159
// a metric and wishes to report an error to the registry.
160
func NewInvalidMetric(desc *Desc, err error) Metric {
161
return &invalidMetric{desc, err}
164
func (m *invalidMetric) Desc() *Desc { return m.desc }
166
func (m *invalidMetric) Write(*dto.Metric) error { return m.err }
added
removed
prometheus/metric.go
