cmd/bpa-operator/vendor/github.com/prometheus/client_golang/prometheus/desc.go

   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
  14 package prometheus
  15
  16 import (
  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.
  44 type 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.
  77 func 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.
 163 func NewInvalidDesc(err error) *Desc {
 164         return &Desc{
 165                 err: err,
 166         }
 167 }
 168
 169 func (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 }