Introduce MetricVecOpts and add constraints to VariableLabels

Signed-off-by: Quentin Devos <[email protected]>

Author: Okhoshi

prometheus/counter.go

@@ -59,6 +59,18 @@ type ExemplarAdder interface {
 // CounterOpts is an alias for Opts. See there for doc comments.
 type CounterOpts Opts
 
+// CounterVecOpts bundles the options to create a CounterVec metric.
+// It is mandatory to set CounterOpts, see there for mandatory fields. VariableLabels
+// is optional and can safely be left to its default value.
+type CounterVecOpts struct {
+	CounterOpts
+
+	// VariableLabels are used to partition the metric vector by the given set
+	// of labels. Each label value will be constrained with the optional Contraint
+	// function, if provided.
+	VariableLabels ConstrainableLabels
+}
+
 // NewCounter creates a new Counter based on the provided CounterOpts.
 //
 // The returned implementation also implements ExemplarAdder. It is safe to
@@ -174,28 +186,24 @@ type CounterVec struct {
 // NewCounterVec creates a new CounterVec based on the provided CounterOpts and
 // partitioned by the given label names.
 func NewCounterVec(opts CounterOpts, labelNames []string) *CounterVec {
-	return NewConstrainedCounterVec(opts, labelNames, nil)
+	return V2.NewCounterVec(CounterVecOpts{
+		CounterOpts:    opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
 }
 
-// NewConstrainedCounterVec creates a new CounterVec based on the provided CounterOpts
-// and partitioned by the given label names, for which the values will be normalized
-// through the constrainedLabels functions, when provided.
-func NewConstrainedCounterVec(
-	opts CounterOpts,
-	labelNames []string,
-	constrainedLabels ConstrainedLabels,
-) *CounterVec {
-	desc := NewConstrainedDesc(
+// NewCounterVec creates a new CounterVec based on the provided CounterVecOpts.
+func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
+	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		labelNames,
+		opts.VariableLabels,
 		opts.ConstLabels,
-		constrainedLabels,
 	)
 	return &CounterVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
 			if len(lvs) != len(desc.variableLabels) {
-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))
+				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.labelNames(), lvs))
 			}
 			result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: time.Now}
 			result.init(result) // Init self-collection.

prometheus/counter_test.go

@@ -102,7 +102,7 @@ func TestCounterVecGetMetricWithInvalidLabelValues(t *testing.T) {
 			Name: "test",
 		}, []string{"a"})
 
-		labelValues := make([]string, len(test.labels))
+		labelValues := make([]string, 0, len(test.labels))
 		for _, val := range test.labels {
 			labelValues = append(labelValues, val)
 		}

prometheus/desc.go

@@ -54,11 +54,9 @@ type Desc struct {
 	// constLabelPairs contains precalculated DTO label pairs based on
 	// the constant labels.
 	constLabelPairs []*dto.LabelPair
-	// variableLabels contains names of labels for which the metric
-	// maintains variable values.
-	variableLabels []string
-	// labelConstraints contains the constraints applied on the label values.
-	labelConstraints []func(string) string
+	// variableLabels contains names of labels and normalization function for
+	// which the metric maintains variable values.
+	variableLabels ConstrainedLabels
 	// id is a hash of the values of the ConstLabels and fqName. This
 	// must be unique among all registered descriptors and can therefore be
 	// used as an identifier of the descriptor.
@@ -82,10 +80,24 @@ type Desc struct {
 // For constLabels, the label values are constant. Therefore, they are fully
 // specified in the Desc. See the Collector example for a usage pattern.
 func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *Desc {
+	return V2.NewDesc(fqName, help, UnconstrainedLabels(variableLabels), constLabels)
+}
+
+// NewDesc allocates and initializes a new Desc. Errors are recorded in the Desc
+// and will be reported on registration time. variableLabels and constLabels can
+// be nil if no such labels should be set. fqName must not be empty.
+//
+// variableLabels only contain the label names and normalization functions. Their
+// label values are variable and therefore not part of the Desc. (They are managed
+// within the Metric.)
+//
+// For constLabels, the label values are constant. Therefore, they are fully
+// specified in the Desc. See the Collector example for a usage pattern.
+func (v2) NewDesc(fqName, help string, variableLabels ConstrainableLabels, constLabels Labels) *Desc {
 	d := &Desc{
 		fqName:         fqName,
 		help:           help,
-		variableLabels: variableLabels,
+		variableLabels: variableLabels.constrainedLabels(),
 	}
 	if !model.IsValidMetricName(model.LabelValue(fqName)) {
 		d.err = fmt.Errorf("%q is not a valid metric name", fqName)
@@ -95,7 +107,7 @@ func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *
 	// their sorted label names) plus the fqName (at position 0).
 	labelValues := make([]string, 1, len(constLabels)+1)
 	labelValues[0] = fqName
-	labelNames := make([]string, 0, len(constLabels)+len(variableLabels))
+	labelNames := make([]string, 0, len(constLabels)+len(d.variableLabels))
 	labelNameSet := map[string]struct{}{}
 	// First add only the const label names and sort them...
 	for labelName := range constLabels {
@@ -120,13 +132,13 @@ func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *
 	// Now add the variable label names, but prefix them with something that
 	// cannot be in a regular label name. That prevents matching the label
 	// dimension with a different mix between preset and variable labels.
-	for _, labelName := range variableLabels {
-		if !checkLabelName(labelName) {
-			d.err = fmt.Errorf("%q is not a valid label name for metric %q", labelName, fqName)
+	for _, label := range d.variableLabels {
+		if !checkLabelName(label.Name) {
+			d.err = fmt.Errorf("%q is not a valid label name for metric %q", label.Name, fqName)
 			return d
 		}
-		labelNames = append(labelNames, "$"+labelName)
-		labelNameSet[labelName] = struct{}{}
+		labelNames = append(labelNames, "$"+label.Name)
+		labelNameSet[label.Name] = struct{}{}
 	}
 	if len(labelNames) != len(labelNameSet) {
 		d.err = errors.New("duplicate label names")
@@ -163,62 +175,6 @@ func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *
 	return d
 }
 
-// NewConstrainedDesc allocates and initializes a new Desc with constraints on
-// the variable labels. Errors are recorded in the Desc and will be reported on
-// registration time. variableLabels, constLabels and constrainedLabels can be
-// nil if no such labels should be set. fqName must not be empty.
-//
-// variableLabels only contain the label names. Their label values are variable
-// and therefore not part of the Desc. (They are managed within the Metric.)
-//
-// constrainedLabels contains the label names and functions to normalize them.
-// Label names in constrainedLabels are merged into variableLabels, so they can
-// be omitted from variableLabels. Order of variableLabels is preserved, and new
-// labels from constrainedLabels are appended to variableLabels.
-//
-// For constLabels, the label values are constant. Therefore, they are fully
-// specified in the Desc. See the Collector example for a usage pattern.
-func NewConstrainedDesc(
-	fqName, help string,
-	variableLabels []string,
-	constLabels Labels,
-	constrainedLabels ConstrainedLabels,
-) *Desc {
-	if len(constrainedLabels) > 0 {
-		// Merge constrainedLabels into variableLabels as a source for variable
-		// labels in the Desc
-		labelSet := map[string]bool{}
-		for label := range constrainedLabels {
-			labelSet[label] = true
-		}
-		for _, label := range variableLabels {
-			labelSet[label] = false
-		}
-		for label := range constrainedLabels {
-			if labelSet[label] {
-				variableLabels = append(variableLabels, label)
-			}
-		}
-	}
-
-	d := NewDesc(fqName, help, variableLabels, constLabels)
-	if len(constrainedLabels) > 0 {
-		d.labelConstraints = make([]func(string) string, len(d.variableLabels))
-		for i, label := range d.variableLabels {
-			if fn, ok := constrainedLabels[label]; ok {
-				d.labelConstraints[i] = fn
-			} else {
-				d.labelConstraints[i] = identityConstraint
-			}
-		}
-	}
-	return d
-}
-
-func identityConstraint(lv string) string {
-	return lv
-}
-
 // NewInvalidDesc returns an invalid descriptor, i.e. a descriptor with the
 // provided error set. If a collector returning such a descriptor is registered,
 // registration will fail with the provided error. NewInvalidDesc can be used by

prometheus/examples_test.go

@@ -294,9 +294,9 @@ func ExampleRegister() {
 
 	// Output:
 	// taskCounter registered.
-	// taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: [worker_id]} has different label names or a different help string
+	// taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: [{worker_id <nil>}]} has different label names or a different help string
 	// taskCounter unregistered.
-	// taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: [worker_id]} has different label names or a different help string
+	// taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: [{worker_id <nil>}]} has different label names or a different help string
 	// taskCounterVec registered.
 	// Worker initialization failed: inconsistent label cardinality: expected 1 label values but got 2 in []string{"42", "spurious arg"}
 	// notMyCounter is nil.

prometheus/gauge.go

@@ -55,6 +55,18 @@ type Gauge interface {
 // GaugeOpts is an alias for Opts. See there for doc comments.
 type GaugeOpts Opts
 
+// GaugeVecOpts bundles the options to create a GaugeVec metric.
+// It is mandatory to set GaugeOpts, see there for mandatory fields. VariableLabels
+// is optional and can safely be left to its default value.
+type GaugeVecOpts struct {
+	GaugeOpts
+
+	// VariableLabels are used to partition the metric vector by the given set
+	// of labels. Each label value will be constrained with the optional Contraint
+	// function, if provided.
+	VariableLabels ConstrainableLabels
+}
+
 // NewGauge creates a new Gauge based on the provided GaugeOpts.
 //
 // The returned implementation is optimized for a fast Set method. If you have a
@@ -138,28 +150,24 @@ type GaugeVec struct {
 // NewGaugeVec creates a new GaugeVec based on the provided GaugeOpts and
 // partitioned by the given label names.
 func NewGaugeVec(opts GaugeOpts, labelNames []string) *GaugeVec {
-	return NewConstrainedGaugeVec(opts, labelNames, nil)
+	return V2.NewGaugeVec(GaugeVecOpts{
+		GaugeOpts:      opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
 }
 
-// NewConstrainedGaugeVec creates a new GaugeVec based on the provided GaugeOpts
-// and partitioned by the given label names, for which the values will be normalized
-// through the constrainedLabels functions, when provided.
-func NewConstrainedGaugeVec(
-	opts GaugeOpts,
-	labelNames []string,
-	constrainedLabels ConstrainedLabels,
-) *GaugeVec {
-	desc := NewConstrainedDesc(
+// NewGaugeVec creates a new GaugeVec based on the provided GaugeVecOpts.
+func (v2) NewGaugeVec(opts GaugeVecOpts) *GaugeVec {
+	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		labelNames,
+		opts.VariableLabels,
 		opts.ConstLabels,
-		constrainedLabels,
 	)
 	return &GaugeVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
 			if len(lvs) != len(desc.variableLabels) {
-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))
+				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.labelNames(), lvs))
 			}
 			result := &gauge{desc: desc, labelPairs: MakeLabelPairs(desc, lvs)}
 			result.init(result) // Init self-collection.

prometheus/histogram.go

@@ -469,6 +469,18 @@ type HistogramOpts struct {
 	NativeHistogramMaxZeroThreshold float64
 }
 
+// HistogramVecOpts bundles the options to create a HistogramVec metric.
+// It is mandatory to set HistogramOpts, see there for mandatory fields. VariableLabels
+// is optional and can safely be left to its default value.
+type HistogramVecOpts struct {
+	HistogramOpts
+
+	// VariableLabels are used to partition the metric vector by the given set
+	// of labels. Each label value will be constrained with the optional Contraint
+	// function, if provided.
+	VariableLabels ConstrainableLabels
+}
+
 // NewHistogram creates a new Histogram based on the provided HistogramOpts. It
 // panics if the buckets in HistogramOpts are not in strictly increasing order.
 //
@@ -489,11 +501,11 @@ func NewHistogram(opts HistogramOpts) Histogram {
 
 func newHistogram(desc *Desc, opts HistogramOpts, labelValues ...string) Histogram {
 	if len(desc.variableLabels) != len(labelValues) {
-		panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, labelValues))
+		panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.labelNames(), labelValues))
 	}
 
 	for _, n := range desc.variableLabels {
-		if n == bucketLabel {
+		if n.Name == bucketLabel {
 			panic(errBucketLabelNotAllowed)
 		}
 	}
@@ -1034,27 +1046,23 @@ type HistogramVec struct {
 // NewHistogramVec creates a new HistogramVec based on the provided HistogramOpts and
 // partitioned by the given label names.
 func NewHistogramVec(opts HistogramOpts, labelNames []string) *HistogramVec {
-	return NewConstrainedHistogramVec(opts, labelNames, nil)
+	return V2.NewHistogramVec(HistogramVecOpts{
+		HistogramOpts:  opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
 }
 
-// NewConstrainedHistogramVec creates a new HistogramVec based on the provided HistogramOpts
-// and partitioned by the given label names, for which the values will be normalized
-// through the constrainedLabels functions, when provided.
-func NewConstrainedHistogramVec(
-	opts HistogramOpts,
-	labelNames []string,
-	constrainedLabels ConstrainedLabels,
-) *HistogramVec {
-	desc := NewConstrainedDesc(
+// NewHistogramVec creates a new HistogramVec based on the provided HistogramVecOpts.
+func (v2) NewHistogramVec(opts HistogramVecOpts) *HistogramVec {
+	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		labelNames,
+		opts.VariableLabels,
 		opts.ConstLabels,
-		constrainedLabels,
 	)
 	return &HistogramVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
-			return newHistogram(desc, opts, lvs...)
+			return newHistogram(desc, opts.HistogramOpts, lvs...)
 		}),
 	}
 }