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
14package model
15
16import (
17	"encoding/json"
18	"fmt"
19	"regexp"
20	"strings"
21	"unicode/utf8"
22)
23
24const (
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. Note that the
84// IsValid method of LabelName performs the same check but faster than a match
85// with this regular expression.
86var LabelNameRE = regexp.MustCompile("^[a-zA-Z_][a-zA-Z0-9_]*$")
87
88// A LabelName is a key for a LabelSet or Metric.  It has a value associated
89// therewith.
90type LabelName string
91
92// IsValid is true iff the label name matches the pattern of LabelNameRE. This
93// method, however, does not use LabelNameRE for the check but a much faster
94// hardcoded implementation.
95func (ln LabelName) IsValid() bool {
96	if len(ln) == 0 {
97		return false
98	}
99	for i, b := range ln {
100		if !((b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || b == '_' || (b >= '0' && b <= '9' && i > 0)) {
101			return false
102		}
103	}
104	return true
105}
106
107// UnmarshalYAML implements the yaml.Unmarshaler interface.
108func (ln *LabelName) UnmarshalYAML(unmarshal func(interface{}) error) error {
109	var s string
110	if err := unmarshal(&s); err != nil {
111		return err
112	}
113	if !LabelName(s).IsValid() {
114		return fmt.Errorf("%q is not a valid label name", s)
115	}
116	*ln = LabelName(s)
117	return nil
118}
119
120// UnmarshalJSON implements the json.Unmarshaler interface.
121func (ln *LabelName) UnmarshalJSON(b []byte) error {
122	var s string
123	if err := json.Unmarshal(b, &s); err != nil {
124		return err
125	}
126	if !LabelName(s).IsValid() {
127		return fmt.Errorf("%q is not a valid label name", s)
128	}
129	*ln = LabelName(s)
130	return nil
131}
132
133// LabelNames is a sortable LabelName slice. In implements sort.Interface.
134type LabelNames []LabelName
135
136func (l LabelNames) Len() int {
137	return len(l)
138}
139
140func (l LabelNames) Less(i, j int) bool {
141	return l[i] < l[j]
142}
143
144func (l LabelNames) Swap(i, j int) {
145	l[i], l[j] = l[j], l[i]
146}
147
148func (l LabelNames) String() string {
149	labelStrings := make([]string, 0, len(l))
150	for _, label := range l {
151		labelStrings = append(labelStrings, string(label))
152	}
153	return strings.Join(labelStrings, ", ")
154}
155
156// A LabelValue is an associated value for a LabelName.
157type LabelValue string
158
159// IsValid returns true iff the string is a valid UTF8.
160func (lv LabelValue) IsValid() bool {
161	return utf8.ValidString(string(lv))
162}
163
164// LabelValues is a sortable LabelValue slice. It implements sort.Interface.
165type LabelValues []LabelValue
166
167func (l LabelValues) Len() int {
168	return len(l)
169}
170
171func (l LabelValues) Less(i, j int) bool {
172	return string(l[i]) < string(l[j])
173}
174
175func (l LabelValues) Swap(i, j int) {
176	l[i], l[j] = l[j], l[i]
177}
178
179// LabelPair pairs a name with a value.
180type LabelPair struct {
181	Name  LabelName
182	Value LabelValue
183}
184
185// LabelPairs is a sortable slice of LabelPair pointers. It implements
186// sort.Interface.
187type LabelPairs []*LabelPair
188
189func (l LabelPairs) Len() int {
190	return len(l)
191}
192
193func (l LabelPairs) Less(i, j int) bool {
194	switch {
195	case l[i].Name > l[j].Name:
196		return false
197	case l[i].Name < l[j].Name:
198		return true
199	case l[i].Value > l[j].Value:
200		return false
201	case l[i].Value < l[j].Value:
202		return true
203	default:
204		return false
205	}
206}
207
208func (l LabelPairs) Swap(i, j int) {
209	l[i], l[j] = l[j], l[i]
210}
211