vendor/github.com/prometheus/client_golang/prometheus/desc.go

   1 package prometheus
   2
   3 import (
   4         "errors"
   5         "fmt"
   6         "regexp"
   7         "sort"
   8         "strings"
   9
  10         "github.com/golang/protobuf/proto"
  11
  12         dto "github.com/prometheus/client_model/go"
  13 )
  14
  15 var (
  16         metricNameRE = regexp.MustCompile(`^[a-zA-Z_][a-zA-Z0-9_:]*$`)
  17         labelNameRE  = regexp.MustCompile("^[a-zA-Z_][a-zA-Z0-9_]*$")
  18 )
  19
  20 // reservedLabelPrefix is a prefix which is not legal in user-supplied
  21 // label names.
  22 const reservedLabelPrefix = "__"
  23
  24 // Labels represents a collection of label name -> value mappings. This type is
  25 // commonly used with the With(Labels) and GetMetricWith(Labels) methods of
  26 // metric vector Collectors, e.g.:
  27 //     myVec.With(Labels{"code": "404", "method": "GET"}).Add(42)
  28 //
  29 // The other use-case is the specification of constant label pairs in Opts or to
  30 // create a Desc.
  31 type Labels map[string]string
  32
  33 // Desc is the descriptor used by every Prometheus Metric. It is essentially
  34 // the immutable meta-data of a Metric. The normal Metric implementations
  35 // included in this package manage their Desc under the hood. Users only have to
  36 // deal with Desc if they use advanced features like the ExpvarCollector or
  37 // custom Collectors and Metrics.
  38 //
  39 // Descriptors registered with the same registry have to fulfill certain
  40 // consistency and uniqueness criteria if they share the same fully-qualified
  41 // name: They must have the same help string and the same label names (aka label
  42 // dimensions) in each, constLabels and variableLabels, but they must differ in
  43 // the values of the constLabels.
  44 //
  45 // Descriptors that share the same fully-qualified names and the same label
  46 // values of their constLabels are considered equal.
  47 //
  48 // Use NewDesc to create new Desc instances.
  49 type Desc struct {
  50         // fqName has been built from Namespace, Subsystem, and Name.
  51         fqName string
  52         // help provides some helpful information about this metric.
  53         help string
  54         // constLabelPairs contains precalculated DTO label pairs based on
  55         // the constant labels.
  56         constLabelPairs []*dto.LabelPair
  57         // VariableLabels contains names of labels for which the metric
  58         // maintains variable values.
  59         variableLabels []string
  60         // id is a hash of the values of the ConstLabels and fqName. This
  61         // must be unique among all registered descriptors and can therefore be
  62         // used as an identifier of the descriptor.
  63         id uint64
  64         // dimHash is a hash of the label names (preset and variable) and the
  65         // Help string. Each Desc with the same fqName must have the same
  66         // dimHash.
  67         dimHash uint64
  68         // err is an error that occured during construction. It is reported on
  69         // registration time.
  70         err error
  71 }
  72
  73 // NewDesc allocates and initializes a new Desc. Errors are recorded in the Desc
  74 // and will be reported on registration time. variableLabels and constLabels can
  75 // be nil if no such labels should be set. fqName and help must not be empty.
  76 //
  77 // variableLabels only contain the label names. Their label values are variable
  78 // and therefore not part of the Desc. (They are managed within the Metric.)
  79 //
  80 // For constLabels, the label values are constant. Therefore, they are fully
  81 // specified in the Desc. See the Opts documentation for the implications of
  82 // constant labels.
  83 func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *Desc {
  84         d := &Desc{
  85                 fqName:         fqName,
  86                 help:           help,
  87                 variableLabels: variableLabels,
  88         }
  89         if help == "" {
  90                 d.err = errors.New("empty help string")
  91                 return d
  92         }
  93         if !metricNameRE.MatchString(fqName) {
  94                 d.err = fmt.Errorf("%q is not a valid metric name", fqName)
  95                 return d
  96         }
  97         // labelValues contains the label values of const labels (in order of
  98         // their sorted label names) plus the fqName (at position 0).
  99         labelValues := make([]string, 1, len(constLabels)+1)
 100         labelValues[0] = fqName
 101         labelNames := make([]string, 0, len(constLabels)+len(variableLabels))
 102         labelNameSet := map[string]struct{}{}
 103         // First add only the const label names and sort them...
 104         for labelName := range constLabels {
 105                 if !checkLabelName(labelName) {
 106                         d.err = fmt.Errorf("%q is not a valid label name", labelName)
 107                         return d
 108                 }
 109                 labelNames = append(labelNames, labelName)
 110                 labelNameSet[labelName] = struct{}{}
 111         }
 112         sort.Strings(labelNames)
 113         // ... so that we can now add const label values in the order of their names.
 114         for _, labelName := range labelNames {
 115                 labelValues = append(labelValues, constLabels[labelName])
 116         }
 117         // Now add the variable label names, but prefix them with something that
 118         // cannot be in a regular label name. That prevents matching the label
 119         // dimension with a different mix between preset and variable labels.
 120         for _, labelName := range variableLabels {
 121                 if !checkLabelName(labelName) {
 122                         d.err = fmt.Errorf("%q is not a valid label name", labelName)
 123                         return d
 124                 }
 125                 labelNames = append(labelNames, "$"+labelName)
 126                 labelNameSet[labelName] = struct{}{}
 127         }
 128         if len(labelNames) != len(labelNameSet) {
 129                 d.err = errors.New("duplicate label names")
 130                 return d
 131         }
 132         vh := hashNew()
 133         for _, val := range labelValues {
 134                 vh = hashAdd(vh, val)
 135                 vh = hashAddByte(vh, separatorByte)
 136         }
 137         d.id = vh
 138         // Sort labelNames so that order doesn't matter for the hash.
 139         sort.Strings(labelNames)
 140         // Now hash together (in this order) the help string and the sorted
 141         // label names.
 142         lh := hashNew()
 143         lh = hashAdd(lh, help)
 144         lh = hashAddByte(lh, separatorByte)
 145         for _, labelName := range labelNames {
 146                 lh = hashAdd(lh, labelName)
 147                 lh = hashAddByte(lh, separatorByte)
 148         }
 149         d.dimHash = lh
 150
 151         d.constLabelPairs = make([]*dto.LabelPair, 0, len(constLabels))
 152         for n, v := range constLabels {
 153                 d.constLabelPairs = append(d.constLabelPairs, &dto.LabelPair{
 154                         Name:  proto.String(n),
 155                         Value: proto.String(v),
 156                 })
 157         }
 158         sort.Sort(LabelPairSorter(d.constLabelPairs))
 159         return d
 160 }
 161
 162 // NewInvalidDesc returns an invalid descriptor, i.e. a descriptor with the
 163 // provided error set. If a collector returning such a descriptor is registered,
 164 // registration will fail with the provided error. NewInvalidDesc can be used by
 165 // a Collector to signal inability to describe itself.
 166 func NewInvalidDesc(err error) *Desc {
 167         return &Desc{
 168                 err: err,
 169         }
 170 }
 171
 172 func (d *Desc) String() string {
 173         lpStrings := make([]string, 0, len(d.constLabelPairs))
 174         for _, lp := range d.constLabelPairs {
 175                 lpStrings = append(
 176                         lpStrings,
 177                         fmt.Sprintf("%s=%q", lp.GetName(), lp.GetValue()),
 178                 )
 179         }
 180         return fmt.Sprintf(
 181                 "Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: %v}",
 182                 d.fqName,
 183                 d.help,
 184                 strings.Join(lpStrings, ","),
 185                 d.variableLabels,
 186         )
 187 }
 188
 189 func checkLabelName(l string) bool {
 190         return labelNameRE.MatchString(l) &&
 191                 !strings.HasPrefix(l, reservedLabelPrefix)
 192 }