vendor/github.com/prometheus/common/model/labels.go

   1 // Copyright 2013 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 model
  15
  16 import (
  17         "encoding/json"
  18         "fmt"
  19         "regexp"
  20         "strings"
  21         "unicode/utf8"
  22 )
  23
  24 const (
  25         // AlertNameLabel is the name of the label containing the an alert's name.
  26         AlertNameLabel = "alertname"
  27
  28         // ExportedLabelPrefix is the prefix to prepend to the label names present in
  29         // exported metrics if a label of the same name is added by the server.
  30         ExportedLabelPrefix = "exported_"
  31
  32         // MetricNameLabel is the label name indicating the metric name of a
  33         // timeseries.
  34         MetricNameLabel = "__name__"
  35
  36         // SchemeLabel is the name of the label that holds the scheme on which to
  37         // scrape a target.
  38         SchemeLabel = "__scheme__"
  39
  40         // AddressLabel is the name of the label that holds the address of
  41         // a scrape target.
  42         AddressLabel = "__address__"
  43
  44         // MetricsPathLabel is the name of the label that holds the path on which to
  45         // scrape a target.
  46         MetricsPathLabel = "__metrics_path__"
  47
  48         // ReservedLabelPrefix is a prefix which is not legal in user-supplied
  49         // label names.
  50         ReservedLabelPrefix = "__"
  51
  52         // MetaLabelPrefix is a prefix for labels that provide meta information.
  53         // Labels with this prefix are used for intermediate label processing and
  54         // will not be attached to time series.
  55         MetaLabelPrefix = "__meta_"
  56
  57         // TmpLabelPrefix is a prefix for temporary labels as part of relabelling.
  58         // Labels with this prefix are used for intermediate label processing and
  59         // will not be attached to time series. This is reserved for use in
  60         // Prometheus configuration files by users.
  61         TmpLabelPrefix = "__tmp_"
  62
  63         // ParamLabelPrefix is a prefix for labels that provide URL parameters
  64         // used to scrape a target.
  65         ParamLabelPrefix = "__param_"
  66
  67         // JobLabel is the label name indicating the job from which a timeseries
  68         // was scraped.
  69         JobLabel = "job"
  70
  71         // InstanceLabel is the label name used for the instance label.
  72         InstanceLabel = "instance"
  73
  74         // BucketLabel is used for the label that defines the upper bound of a
  75         // bucket of a histogram ("le" -> "less or equal").
  76         BucketLabel = "le"
  77
  78         // QuantileLabel is used for the label that defines the quantile in a
  79         // summary.
  80         QuantileLabel = "quantile"
  81 )
  82
  83 // LabelNameRE is a regular expression matching valid label names.
  84 var LabelNameRE = regexp.MustCompile("^[a-zA-Z_][a-zA-Z0-9_]*$")
  85
  86 // A LabelName is a key for a LabelSet or Metric.  It has a value associated
  87 // therewith.
  88 type LabelName string
  89
  90 // IsValid is true iff the label name matches the pattern of LabelNameRE.
  91 func (ln LabelName) IsValid() bool {
  92         if len(ln) == 0 {
  93                 return false
  94         }
  95         for i, b := range ln {
  96                 if !((b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || b == '_' || (b >= '0' && b <= '9' && i > 0)) {
  97                         return false
  98                 }
  99         }
 100         return true
 101 }
 102
 103 // UnmarshalYAML implements the yaml.Unmarshaler interface.
 104 func (ln *LabelName) UnmarshalYAML(unmarshal func(interface{}) error) error {
 105         var s string
 106         if err := unmarshal(&s); err != nil {
 107                 return err
 108         }
 109         if !LabelNameRE.MatchString(s) {
 110                 return fmt.Errorf("%q is not a valid label name", s)
 111         }
 112         *ln = LabelName(s)
 113         return nil
 114 }
 115
 116 // UnmarshalJSON implements the json.Unmarshaler interface.
 117 func (ln *LabelName) UnmarshalJSON(b []byte) error {
 118         var s string
 119         if err := json.Unmarshal(b, &s); err != nil {
 120                 return err
 121         }
 122         if !LabelNameRE.MatchString(s) {
 123                 return fmt.Errorf("%q is not a valid label name", s)
 124         }
 125         *ln = LabelName(s)
 126         return nil
 127 }
 128
 129 // LabelNames is a sortable LabelName slice. In implements sort.Interface.
 130 type LabelNames []LabelName
 131
 132 func (l LabelNames) Len() int {
 133         return len(l)
 134 }
 135
 136 func (l LabelNames) Less(i, j int) bool {
 137         return l[i] < l[j]
 138 }
 139
 140 func (l LabelNames) Swap(i, j int) {
 141         l[i], l[j] = l[j], l[i]
 142 }
 143
 144 func (l LabelNames) String() string {
 145         labelStrings := make([]string, 0, len(l))
 146         for _, label := range l {
 147                 labelStrings = append(labelStrings, string(label))
 148         }
 149         return strings.Join(labelStrings, ", ")
 150 }
 151
 152 // A LabelValue is an associated value for a LabelName.
 153 type LabelValue string
 154
 155 // IsValid returns true iff the string is a valid UTF8.
 156 func (lv LabelValue) IsValid() bool {
 157         return utf8.ValidString(string(lv))
 158 }
 159
 160 // LabelValues is a sortable LabelValue slice. It implements sort.Interface.
 161 type LabelValues []LabelValue
 162
 163 func (l LabelValues) Len() int {
 164         return len(l)
 165 }
 166
 167 func (l LabelValues) Less(i, j int) bool {
 168         return string(l[i]) < string(l[j])
 169 }
 170
 171 func (l LabelValues) Swap(i, j int) {
 172         l[i], l[j] = l[j], l[i]
 173 }
 174
 175 // LabelPair pairs a name with a value.
 176 type LabelPair struct {
 177         Name  LabelName
 178         Value LabelValue
 179 }
 180
 181 // LabelPairs is a sortable slice of LabelPair pointers. It implements
 182 // sort.Interface.
 183 type LabelPairs []*LabelPair
 184
 185 func (l LabelPairs) Len() int {
 186         return len(l)
 187 }
 188
 189 func (l LabelPairs) Less(i, j int) bool {
 190         switch {
 191         case l[i].Name > l[j].Name:
 192                 return false
 193         case l[i].Name < l[j].Name:
 194                 return true
 195         case l[i].Value > l[j].Value:
 196                 return false
 197         case l[i].Value < l[j].Value:
 198                 return true
 199         default:
 200                 return false
 201         }
 202 }
 203
 204 func (l LabelPairs) Swap(i, j int) {
 205         l[i], l[j] = l[j], l[i]
 206 }