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 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 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. 13 14package prometheus 15 16import ( 17 "errors" 18 "fmt" 19 "sort" 20 "strings" 21 22 "github.com/golang/protobuf/proto" 23 "github.com/prometheus/common/model" 24 25 dto "github.com/prometheus/client_model/go" 26) 27 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. 33// 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. 39// 40// Descriptors that share the same fully-qualified names and the same label 41// values of their constLabels are considered equal. 42// 43// Use NewDesc to create new Desc instances. 44type Desc struct { 45 // fqName has been built from Namespace, Subsystem, and Name. 46 fqName string 47 // help provides some helpful information about this metric. 48 help string 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. 58 id uint64 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 61 // dimHash. 62 dimHash uint64 63 // err is an error that occurred during construction. It is reported on 64 // registration time. 65 err error 66} 67 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. 71// 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.) 74// 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. 77func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *Desc { 78 d := &Desc{ 79 fqName: fqName, 80 help: help, 81 variableLabels: variableLabels, 82 } 83 if !model.IsValidMetricName(model.LabelValue(fqName)) { 84 d.err = fmt.Errorf("%q is not a valid metric name", fqName) 85 return d 86 } 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) 97 return d 98 } 99 labelNames = append(labelNames, labelName) 100 labelNameSet[labelName] = struct{}{} 101 } 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]) 106 } 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 { 110 d.err = err 111 return d 112 } 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) 119 return d 120 } 121 labelNames = append(labelNames, "$"+labelName) 122 labelNameSet[labelName] = struct{}{} 123 } 124 if len(labelNames) != len(labelNameSet) { 125 d.err = errors.New("duplicate label names") 126 return d 127 } 128 129 vh := hashNew() 130 for _, val := range labelValues { 131 vh = hashAdd(vh, val) 132 vh = hashAddByte(vh, separatorByte) 133 } 134 d.id = vh 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 138 // label names. 139 lh := hashNew() 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) 145 } 146 d.dimHash = lh 147 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), 153 }) 154 } 155 sort.Sort(labelPairSorter(d.constLabelPairs)) 156 return d 157} 158 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. 163func NewInvalidDesc(err error) *Desc { 164 return &Desc{ 165 err: err, 166 } 167} 168 169func (d *Desc) String() string { 170 lpStrings := make([]string, 0, len(d.constLabelPairs)) 171 for _, lp := range d.constLabelPairs { 172 lpStrings = append( 173 lpStrings, 174 fmt.Sprintf("%s=%q", lp.GetName(), lp.GetValue()), 175 ) 176 } 177 return fmt.Sprintf( 178 "Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: %v}", 179 d.fqName, 180 d.help, 181 strings.Join(lpStrings, ","), 182 d.variableLabels, 183 ) 184} 185