1 // Copyright 2014 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
6 // http://www.apache.org/licenses/LICENSE-2.0
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.
20 "github.com/prometheus/common/model"
23 // metricVec is a Collector to bundle metrics of the same name that differ in
24 // their label values. metricVec is not used directly (and therefore
25 // unexported). It is used as a building block for implementations of vectors of
26 // a given metric type, like GaugeVec, CounterVec, SummaryVec, and HistogramVec.
27 // It also handles label currying. It uses basicMetricVec internally.
28 type metricVec struct {
31 curry []curriedLabelValue
33 // hashAdd and hashAddByte can be replaced for testing collision handling.
34 hashAdd func(h uint64, s string) uint64
35 hashAddByte func(h uint64, b byte) uint64
38 // newMetricVec returns an initialized metricVec.
39 func newMetricVec(desc *Desc, newMetric func(lvs ...string) Metric) *metricVec {
41 metricMap: &metricMap{
42 metrics: map[uint64][]metricWithLabelValues{},
47 hashAddByte: hashAddByte,
51 // DeleteLabelValues removes the metric where the variable labels are the same
52 // as those passed in as labels (same order as the VariableLabels in Desc). It
53 // returns true if a metric was deleted.
55 // It is not an error if the number of label values is not the same as the
56 // number of VariableLabels in Desc. However, such inconsistent label count can
57 // never match an actual metric, so the method will always return false in that
60 // Note that for more than one label value, this method is prone to mistakes
61 // caused by an incorrect order of arguments. Consider Delete(Labels) as an
62 // alternative to avoid that type of mistake. For higher label numbers, the
63 // latter has a much more readable (albeit more verbose) syntax, but it comes
64 // with a performance overhead (for creating and processing the Labels map).
65 // See also the CounterVec example.
66 func (m *metricVec) DeleteLabelValues(lvs ...string) bool {
67 h, err := m.hashLabelValues(lvs)
72 return m.metricMap.deleteByHashWithLabelValues(h, lvs, m.curry)
75 // Delete deletes the metric where the variable labels are the same as those
76 // passed in as labels. It returns true if a metric was deleted.
78 // It is not an error if the number and names of the Labels are inconsistent
79 // with those of the VariableLabels in Desc. However, such inconsistent Labels
80 // can never match an actual metric, so the method will always return false in
83 // This method is used for the same purpose as DeleteLabelValues(...string). See
84 // there for pros and cons of the two methods.
85 func (m *metricVec) Delete(labels Labels) bool {
86 h, err := m.hashLabels(labels)
91 return m.metricMap.deleteByHashWithLabels(h, labels, m.curry)
94 func (m *metricVec) curryWith(labels Labels) (*metricVec, error) {
96 newCurry []curriedLabelValue
100 for i, label := range m.desc.variableLabels {
101 val, ok := labels[label]
102 if iCurry < len(oldCurry) && oldCurry[iCurry].index == i {
104 return nil, fmt.Errorf("label name %q is already curried", label)
106 newCurry = append(newCurry, oldCurry[iCurry])
110 continue // Label stays uncurried.
112 newCurry = append(newCurry, curriedLabelValue{i, val})
115 if l := len(oldCurry) + len(labels) - len(newCurry); l > 0 {
116 return nil, fmt.Errorf("%d unknown label(s) found during currying", l)
120 metricMap: m.metricMap,
123 hashAddByte: m.hashAddByte,
127 func (m *metricVec) getMetricWithLabelValues(lvs ...string) (Metric, error) {
128 h, err := m.hashLabelValues(lvs)
133 return m.metricMap.getOrCreateMetricWithLabelValues(h, lvs, m.curry), nil
136 func (m *metricVec) getMetricWith(labels Labels) (Metric, error) {
137 h, err := m.hashLabels(labels)
142 return m.metricMap.getOrCreateMetricWithLabels(h, labels, m.curry), nil
145 func (m *metricVec) hashLabelValues(vals []string) (uint64, error) {
146 if err := validateLabelValues(vals, len(m.desc.variableLabels)-len(m.curry)); err != nil {
155 for i := 0; i < len(m.desc.variableLabels); i++ {
156 if iCurry < len(curry) && curry[iCurry].index == i {
157 h = m.hashAdd(h, curry[iCurry].value)
160 h = m.hashAdd(h, vals[iVals])
163 h = m.hashAddByte(h, model.SeparatorByte)
168 func (m *metricVec) hashLabels(labels Labels) (uint64, error) {
169 if err := validateValuesInLabels(labels, len(m.desc.variableLabels)-len(m.curry)); err != nil {
178 for i, label := range m.desc.variableLabels {
179 val, ok := labels[label]
180 if iCurry < len(curry) && curry[iCurry].index == i {
182 return 0, fmt.Errorf("label name %q is already curried", label)
184 h = m.hashAdd(h, curry[iCurry].value)
188 return 0, fmt.Errorf("label name %q missing in label map", label)
190 h = m.hashAdd(h, val)
192 h = m.hashAddByte(h, model.SeparatorByte)
197 // metricWithLabelValues provides the metric and its label values for
198 // disambiguation on hash collision.
199 type metricWithLabelValues struct {
204 // curriedLabelValue sets the curried value for a label at the given index.
205 type curriedLabelValue struct {
210 // metricMap is a helper for metricVec and shared between differently curried
212 type metricMap struct {
213 mtx sync.RWMutex // Protects metrics.
214 metrics map[uint64][]metricWithLabelValues
216 newMetric func(labelValues ...string) Metric
219 // Describe implements Collector. It will send exactly one Desc to the provided
221 func (m *metricMap) Describe(ch chan<- *Desc) {
225 // Collect implements Collector.
226 func (m *metricMap) Collect(ch chan<- Metric) {
228 defer m.mtx.RUnlock()
230 for _, metrics := range m.metrics {
231 for _, metric := range metrics {
237 // Reset deletes all metrics in this vector.
238 func (m *metricMap) Reset() {
242 for h := range m.metrics {
247 // deleteByHashWithLabelValues removes the metric from the hash bucket h. If
248 // there are multiple matches in the bucket, use lvs to select a metric and
249 // remove only that metric.
250 func (m *metricMap) deleteByHashWithLabelValues(
251 h uint64, lvs []string, curry []curriedLabelValue,
256 metrics, ok := m.metrics[h]
261 i := findMetricWithLabelValues(metrics, lvs, curry)
262 if i >= len(metrics) {
266 if len(metrics) > 1 {
267 m.metrics[h] = append(metrics[:i], metrics[i+1:]...)
274 // deleteByHashWithLabels removes the metric from the hash bucket h. If there
275 // are multiple matches in the bucket, use lvs to select a metric and remove
277 func (m *metricMap) deleteByHashWithLabels(
278 h uint64, labels Labels, curry []curriedLabelValue,
283 metrics, ok := m.metrics[h]
287 i := findMetricWithLabels(m.desc, metrics, labels, curry)
288 if i >= len(metrics) {
292 if len(metrics) > 1 {
293 m.metrics[h] = append(metrics[:i], metrics[i+1:]...)
300 // getOrCreateMetricWithLabelValues retrieves the metric by hash and label value
301 // or creates it and returns the new one.
303 // This function holds the mutex.
304 func (m *metricMap) getOrCreateMetricWithLabelValues(
305 hash uint64, lvs []string, curry []curriedLabelValue,
308 metric, ok := m.getMetricWithHashAndLabelValues(hash, lvs, curry)
316 metric, ok = m.getMetricWithHashAndLabelValues(hash, lvs, curry)
318 inlinedLVs := inlineLabelValues(lvs, curry)
319 metric = m.newMetric(inlinedLVs...)
320 m.metrics[hash] = append(m.metrics[hash], metricWithLabelValues{values: inlinedLVs, metric: metric})
325 // getOrCreateMetricWithLabelValues retrieves the metric by hash and label value
326 // or creates it and returns the new one.
328 // This function holds the mutex.
329 func (m *metricMap) getOrCreateMetricWithLabels(
330 hash uint64, labels Labels, curry []curriedLabelValue,
333 metric, ok := m.getMetricWithHashAndLabels(hash, labels, curry)
341 metric, ok = m.getMetricWithHashAndLabels(hash, labels, curry)
343 lvs := extractLabelValues(m.desc, labels, curry)
344 metric = m.newMetric(lvs...)
345 m.metrics[hash] = append(m.metrics[hash], metricWithLabelValues{values: lvs, metric: metric})
350 // getMetricWithHashAndLabelValues gets a metric while handling possible
351 // collisions in the hash space. Must be called while holding the read mutex.
352 func (m *metricMap) getMetricWithHashAndLabelValues(
353 h uint64, lvs []string, curry []curriedLabelValue,
355 metrics, ok := m.metrics[h]
357 if i := findMetricWithLabelValues(metrics, lvs, curry); i < len(metrics) {
358 return metrics[i].metric, true
364 // getMetricWithHashAndLabels gets a metric while handling possible collisions in
365 // the hash space. Must be called while holding read mutex.
366 func (m *metricMap) getMetricWithHashAndLabels(
367 h uint64, labels Labels, curry []curriedLabelValue,
369 metrics, ok := m.metrics[h]
371 if i := findMetricWithLabels(m.desc, metrics, labels, curry); i < len(metrics) {
372 return metrics[i].metric, true
378 // findMetricWithLabelValues returns the index of the matching metric or
379 // len(metrics) if not found.
380 func findMetricWithLabelValues(
381 metrics []metricWithLabelValues, lvs []string, curry []curriedLabelValue,
383 for i, metric := range metrics {
384 if matchLabelValues(metric.values, lvs, curry) {
391 // findMetricWithLabels returns the index of the matching metric or len(metrics)
393 func findMetricWithLabels(
394 desc *Desc, metrics []metricWithLabelValues, labels Labels, curry []curriedLabelValue,
396 for i, metric := range metrics {
397 if matchLabels(desc, metric.values, labels, curry) {
404 func matchLabelValues(values []string, lvs []string, curry []curriedLabelValue) bool {
405 if len(values) != len(lvs)+len(curry) {
409 for i, v := range values {
410 if iCurry < len(curry) && curry[iCurry].index == i {
411 if v != curry[iCurry].value {
425 func matchLabels(desc *Desc, values []string, labels Labels, curry []curriedLabelValue) bool {
426 if len(values) != len(labels)+len(curry) {
430 for i, k := range desc.variableLabels {
431 if iCurry < len(curry) && curry[iCurry].index == i {
432 if values[i] != curry[iCurry].value {
438 if values[i] != labels[k] {
445 func extractLabelValues(desc *Desc, labels Labels, curry []curriedLabelValue) []string {
446 labelValues := make([]string, len(labels)+len(curry))
448 for i, k := range desc.variableLabels {
449 if iCurry < len(curry) && curry[iCurry].index == i {
450 labelValues[i] = curry[iCurry].value
454 labelValues[i] = labels[k]
459 func inlineLabelValues(lvs []string, curry []curriedLabelValue) []string {
460 labelValues := make([]string, len(lvs)+len(curry))
462 for i := range labelValues {
463 if iCurry < len(curry) && curry[iCurry].index == i {
464 labelValues[i] = curry[iCurry].value
468 labelValues[i] = lvs[iLVs]