1 // Copyright 2016 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.
22 "github.com/golang/protobuf/proto"
23 "github.com/prometheus/common/model"
25 dto "github.com/prometheus/client_model/go"
28 // Desc is the descriptor used by every Prometheus Metric. It is essentially
29 // the immutable meta-data of a Metric. The normal Metric implementations
30 // included in this package manage their Desc under the hood. Users only have to
31 // deal with Desc if they use advanced features like the ExpvarCollector or
32 // custom Collectors and Metrics.
34 // Descriptors registered with the same registry have to fulfill certain
35 // consistency and uniqueness criteria if they share the same fully-qualified
36 // name: They must have the same help string and the same label names (aka label
37 // dimensions) in each, constLabels and variableLabels, but they must differ in
38 // the values of the constLabels.
40 // Descriptors that share the same fully-qualified names and the same label
41 // values of their constLabels are considered equal.
43 // Use NewDesc to create new Desc instances.
45 // fqName has been built from Namespace, Subsystem, and Name.
47 // help provides some helpful information about this metric.
49 // constLabelPairs contains precalculated DTO label pairs based on
50 // the constant labels.
51 constLabelPairs []*dto.LabelPair
52 // VariableLabels contains names of labels for which the metric
53 // maintains variable values.
54 variableLabels []string
55 // id is a hash of the values of the ConstLabels and fqName. This
56 // must be unique among all registered descriptors and can therefore be
57 // used as an identifier of the descriptor.
59 // dimHash is a hash of the label names (preset and variable) and the
60 // Help string. Each Desc with the same fqName must have the same
63 // err is an error that occurred during construction. It is reported on
68 // NewDesc allocates and initializes a new Desc. Errors are recorded in the Desc
69 // and will be reported on registration time. variableLabels and constLabels can
70 // be nil if no such labels should be set. fqName must not be empty.
72 // variableLabels only contain the label names. Their label values are variable
73 // and therefore not part of the Desc. (They are managed within the Metric.)
75 // For constLabels, the label values are constant. Therefore, they are fully
76 // specified in the Desc. See the Collector example for a usage pattern.
77 func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *Desc {
81 variableLabels: variableLabels,
83 if !model.IsValidMetricName(model.LabelValue(fqName)) {
84 d.err = fmt.Errorf("%q is not a valid metric name", fqName)
87 // labelValues contains the label values of const labels (in order of
88 // their sorted label names) plus the fqName (at position 0).
89 labelValues := make([]string, 1, len(constLabels)+1)
90 labelValues[0] = fqName
91 labelNames := make([]string, 0, len(constLabels)+len(variableLabels))
92 labelNameSet := map[string]struct{}{}
93 // First add only the const label names and sort them...
94 for labelName := range constLabels {
95 if !checkLabelName(labelName) {
96 d.err = fmt.Errorf("%q is not a valid label name for metric %q", labelName, fqName)
99 labelNames = append(labelNames, labelName)
100 labelNameSet[labelName] = struct{}{}
102 sort.Strings(labelNames)
103 // ... so that we can now add const label values in the order of their names.
104 for _, labelName := range labelNames {
105 labelValues = append(labelValues, constLabels[labelName])
107 // Validate the const label values. They can't have a wrong cardinality, so
108 // use in len(labelValues) as expectedNumberOfValues.
109 if err := validateLabelValues(labelValues, len(labelValues)); err != nil {
113 // Now add the variable label names, but prefix them with something that
114 // cannot be in a regular label name. That prevents matching the label
115 // dimension with a different mix between preset and variable labels.
116 for _, labelName := range variableLabels {
117 if !checkLabelName(labelName) {
118 d.err = fmt.Errorf("%q is not a valid label name for metric %q", labelName, fqName)
121 labelNames = append(labelNames, "$"+labelName)
122 labelNameSet[labelName] = struct{}{}
124 if len(labelNames) != len(labelNameSet) {
125 d.err = errors.New("duplicate label names")
130 for _, val := range labelValues {
131 vh = hashAdd(vh, val)
132 vh = hashAddByte(vh, separatorByte)
135 // Sort labelNames so that order doesn't matter for the hash.
136 sort.Strings(labelNames)
137 // Now hash together (in this order) the help string and the sorted
140 lh = hashAdd(lh, help)
141 lh = hashAddByte(lh, separatorByte)
142 for _, labelName := range labelNames {
143 lh = hashAdd(lh, labelName)
144 lh = hashAddByte(lh, separatorByte)
148 d.constLabelPairs = make([]*dto.LabelPair, 0, len(constLabels))
149 for n, v := range constLabels {
150 d.constLabelPairs = append(d.constLabelPairs, &dto.LabelPair{
151 Name: proto.String(n),
152 Value: proto.String(v),
155 sort.Sort(labelPairSorter(d.constLabelPairs))
159 // NewInvalidDesc returns an invalid descriptor, i.e. a descriptor with the
160 // provided error set. If a collector returning such a descriptor is registered,
161 // registration will fail with the provided error. NewInvalidDesc can be used by
162 // a Collector to signal inability to describe itself.
163 func NewInvalidDesc(err error) *Desc {
169 func (d *Desc) String() string {
170 lpStrings := make([]string, 0, len(d.constLabelPairs))
171 for _, lp := range d.constLabelPairs {
174 fmt.Sprintf("%s=%q", lp.GetName(), lp.GetValue()),
178 "Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: %v}",
181 strings.Join(lpStrings, ","),