labels.go

Documentation: github.com/prometheus/common/model

     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  	// ScrapeIntervalLabel is the name of the label that holds the scrape interval
    49  	// used to scrape a target.
    50  	ScrapeIntervalLabel = "__scrape_interval__"
    51  
    52  	// ScrapeTimeoutLabel is the name of the label that holds the scrape
    53  	// timeout used to scrape a target.
    54  	ScrapeTimeoutLabel = "__scrape_timeout__"
    55  
    56  	// ReservedLabelPrefix is a prefix which is not legal in user-supplied
    57  	// label names.
    58  	ReservedLabelPrefix = "__"
    59  
    60  	// MetaLabelPrefix is a prefix for labels that provide meta information.
    61  	// Labels with this prefix are used for intermediate label processing and
    62  	// will not be attached to time series.
    63  	MetaLabelPrefix = "__meta_"
    64  
    65  	// TmpLabelPrefix is a prefix for temporary labels as part of relabelling.
    66  	// Labels with this prefix are used for intermediate label processing and
    67  	// will not be attached to time series. This is reserved for use in
    68  	// Prometheus configuration files by users.
    69  	TmpLabelPrefix = "__tmp_"
    70  
    71  	// ParamLabelPrefix is a prefix for labels that provide URL parameters
    72  	// used to scrape a target.
    73  	ParamLabelPrefix = "__param_"
    74  
    75  	// JobLabel is the label name indicating the job from which a timeseries
    76  	// was scraped.
    77  	JobLabel = "job"
    78  
    79  	// InstanceLabel is the label name used for the instance label.
    80  	InstanceLabel = "instance"
    81  
    82  	// BucketLabel is used for the label that defines the upper bound of a
    83  	// bucket of a histogram ("le" -> "less or equal").
    84  	BucketLabel = "le"
    85  
    86  	// QuantileLabel is used for the label that defines the quantile in a
    87  	// summary.
    88  	QuantileLabel = "quantile"
    89  )
    90  
    91  // LabelNameRE is a regular expression matching valid label names. Note that the
    92  // IsValid method of LabelName performs the same check but faster than a match
    93  // with this regular expression.
    94  var LabelNameRE = regexp.MustCompile("^[a-zA-Z_][a-zA-Z0-9_]*$")
    95  
    96  // A LabelName is a key for a LabelSet or Metric.  It has a value associated
    97  // therewith.
    98  type LabelName string
    99  
   100  // IsValid returns true iff name matches the pattern of LabelNameRE for legacy
   101  // names, and iff it's valid UTF-8 if NameValidationScheme is set to
   102  // UTF8Validation. For the legacy matching, it does not use LabelNameRE for the
   103  // check but a much faster hardcoded implementation.
   104  func (ln LabelName) IsValid() bool {
   105  	if len(ln) == 0 {
   106  		return false
   107  	}
   108  	switch NameValidationScheme {
   109  	case LegacyValidation:
   110  		for i, b := range ln {
   111  			if !((b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || b == '_' || (b >= '0' && b <= '9' && i > 0)) {
   112  				return false
   113  			}
   114  		}
   115  	case UTF8Validation:
   116  		return utf8.ValidString(string(ln))
   117  	default:
   118  		panic(fmt.Sprintf("Invalid name validation scheme requested: %d", NameValidationScheme))
   119  	}
   120  	return true
   121  }
   122  
   123  // UnmarshalYAML implements the yaml.Unmarshaler interface.
   124  func (ln *LabelName) UnmarshalYAML(unmarshal func(interface{}) error) error {
   125  	var s string
   126  	if err := unmarshal(&s); err != nil {
   127  		return err
   128  	}
   129  	if !LabelName(s).IsValid() {
   130  		return fmt.Errorf("%q is not a valid label name", s)
   131  	}
   132  	*ln = LabelName(s)
   133  	return nil
   134  }
   135  
   136  // UnmarshalJSON implements the json.Unmarshaler interface.
   137  func (ln *LabelName) UnmarshalJSON(b []byte) error {
   138  	var s string
   139  	if err := json.Unmarshal(b, &s); err != nil {
   140  		return err
   141  	}
   142  	if !LabelName(s).IsValid() {
   143  		return fmt.Errorf("%q is not a valid label name", s)
   144  	}
   145  	*ln = LabelName(s)
   146  	return nil
   147  }
   148  
   149  // LabelNames is a sortable LabelName slice. In implements sort.Interface.
   150  type LabelNames []LabelName
   151  
   152  func (l LabelNames) Len() int {
   153  	return len(l)
   154  }
   155  
   156  func (l LabelNames) Less(i, j int) bool {
   157  	return l[i] < l[j]
   158  }
   159  
   160  func (l LabelNames) Swap(i, j int) {
   161  	l[i], l[j] = l[j], l[i]
   162  }
   163  
   164  func (l LabelNames) String() string {
   165  	labelStrings := make([]string, 0, len(l))
   166  	for _, label := range l {
   167  		labelStrings = append(labelStrings, string(label))
   168  	}
   169  	return strings.Join(labelStrings, ", ")
   170  }
   171  
   172  // A LabelValue is an associated value for a LabelName.
   173  type LabelValue string
   174  
   175  // IsValid returns true iff the string is a valid UTF-8.
   176  func (lv LabelValue) IsValid() bool {
   177  	return utf8.ValidString(string(lv))
   178  }
   179  
   180  // LabelValues is a sortable LabelValue slice. It implements sort.Interface.
   181  type LabelValues []LabelValue
   182  
   183  func (l LabelValues) Len() int {
   184  	return len(l)
   185  }
   186  
   187  func (l LabelValues) Less(i, j int) bool {
   188  	return string(l[i]) < string(l[j])
   189  }
   190  
   191  func (l LabelValues) Swap(i, j int) {
   192  	l[i], l[j] = l[j], l[i]
   193  }
   194  
   195  // LabelPair pairs a name with a value.
   196  type LabelPair struct {
   197  	Name  LabelName
   198  	Value LabelValue
   199  }
   200  
   201  // LabelPairs is a sortable slice of LabelPair pointers. It implements
   202  // sort.Interface.
   203  type LabelPairs []*LabelPair
   204  
   205  func (l LabelPairs) Len() int {
   206  	return len(l)
   207  }
   208  
   209  func (l LabelPairs) Less(i, j int) bool {
   210  	switch {
   211  	case l[i].Name > l[j].Name:
   212  		return false
   213  	case l[i].Name < l[j].Name:
   214  		return true
   215  	case l[i].Value > l[j].Value:
   216  		return false
   217  	case l[i].Value < l[j].Value:
   218  		return true
   219  	default:
   220  		return false
   221  	}
   222  }
   223  
   224  func (l LabelPairs) Swap(i, j int) {
   225  	l[i], l[j] = l[j], l[i]
   226  }
   227
View as plain text