@@ -81,7 +81,7 @@ require (

 	github.com/opencontainers/selinux v1.11.0

 	github.com/pelletier/go-toml v1.9.5

 	github.com/pkg/errors v0.9.1

-	github.com/prometheus/client_golang v1.14.0

+	github.com/prometheus/client_golang v1.17.0

 	github.com/rootless-containers/rootlesskit/v2 v2.0.1

 	github.com/sirupsen/logrus v1.9.3

 	github.com/spf13/cobra v1.8.0

@@ -173,9 +173,9 @@ require (

 	github.com/opencontainers/runtime-tools v0.9.1-0.20221107090550-2e043c6bd626 // indirect

 	github.com/package-url/packageurl-go v0.1.1-0.20220428063043-89078438f170 // indirect

 	github.com/philhofer/fwd v1.1.2 // indirect

-	github.com/prometheus/client_model v0.3.0 // indirect

-	github.com/prometheus/common v0.42.0 // indirect

-	github.com/prometheus/procfs v0.9.0 // indirect

+	github.com/prometheus/client_model v0.5.0 // indirect

+	github.com/prometheus/common v0.44.0 // indirect

+	github.com/prometheus/procfs v0.11.1 // indirect

 	github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529 // indirect

 	github.com/secure-systems-lab/go-securesystemslib v0.4.0 // indirect

 	github.com/shibumi/go-pathspec v1.3.0 // indirect

@@ -1056,16 +1056,16 @@ github.com/prometheus/client_golang v1.1.0/go.mod h1:I1FGZT9+L76gKKOs5djB6ezCbFQ

 github.com/prometheus/client_golang v1.4.0/go.mod h1:e9GMxYsXl05ICDXkRhurwBS4Q3OK1iX/F2sw+iXX5zU=

 github.com/prometheus/client_golang v1.7.1/go.mod h1:PY5Wy2awLA44sXw4AOSfFBetzPP4j5+D6mVACh+pe2M=

 github.com/prometheus/client_golang v1.11.1/go.mod h1:Z6t4BnS23TR94PD6BsDNk8yVqroYurpAkEiz0P2BEV0=

-github.com/prometheus/client_golang v1.14.0 h1:nJdhIvne2eSX/XRAFV9PcvFFRbrjbcTUj0VP62TMhnw=

-github.com/prometheus/client_golang v1.14.0/go.mod h1:8vpkKitgIVNcqrRBWh1C4TIUQgYNtG/XQE4E/Zae36Y=

+github.com/prometheus/client_golang v1.17.0 h1:rl2sfwZMtSthVU752MqfjQozy7blglC+1SOtjMAMh+Q=

+github.com/prometheus/client_golang v1.17.0/go.mod h1:VeL+gMmOAxkS2IqfCq0ZmHSL+LjWfWDUmp1mBz9JgUY=

 github.com/prometheus/client_model v0.0.0-20171117100541-99fa1f4be8e5/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=

 github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=

 github.com/prometheus/client_model v0.0.0-20190115171406-56726106282f/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=

 github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

 github.com/prometheus/client_model v0.2.0/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

-github.com/prometheus/client_model v0.3.0 h1:UBgGFHqYdG/TPFD1B1ogZywDqEkwp3fBMvqdiQ7Xew4=

-github.com/prometheus/client_model v0.3.0/go.mod h1:LDGWKZIo7rky3hgvBe+caln+Dr3dPggB5dvjtD7w9+w=

+github.com/prometheus/client_model v0.5.0 h1:VQw1hfvPvk3Uv6Qf29VrPF32JB6rtbgI6cYPYQjL0Qw=

+github.com/prometheus/client_model v0.5.0/go.mod h1:dTiFglRmd66nLR9Pv9f0mZi7B7fk5Pm3gvsjB5tr+kI=

 github.com/prometheus/common v0.0.0-20180110214958-89604d197083/go.mod h1:daVV7qP5qjZbuso7PdcryaAu0sAZbrN9i7WWcTMWvro=

 github.com/prometheus/common v0.0.0-20180801064454-c7de2306084e/go.mod h1:daVV7qP5qjZbuso7PdcryaAu0sAZbrN9i7WWcTMWvro=

 github.com/prometheus/common v0.0.0-20181113130724-41aa239b4cce/go.mod h1:daVV7qP5qjZbuso7PdcryaAu0sAZbrN9i7WWcTMWvro=

@@ -1076,8 +1076,8 @@ github.com/prometheus/common v0.6.0/go.mod h1:eBmuwkDJBwy6iBfxCBob6t6dR6ENT/y+J+

 github.com/prometheus/common v0.9.1/go.mod h1:yhUN8i9wzaXS3w1O07YhxHEBxD+W35wd8bs7vj7HSQ4=

 github.com/prometheus/common v0.10.0/go.mod h1:Tlit/dnDKsSWFlCLTWaA1cyBgKHSMdTB80sz/V91rCo=

 github.com/prometheus/common v0.26.0/go.mod h1:M7rCNAaPfAosfx8veZJCuw84e35h3Cfd9VFqTh1DIvc=

-github.com/prometheus/common v0.42.0 h1:EKsfXEYo4JpWMHH5cg+KOUWeuJSov1Id8zGR8eeI1YM=

-github.com/prometheus/common v0.42.0/go.mod h1:xBwqVerjNdUDjgODMpudtOMwlOwf2SaTr1yjz4b7Zbc=

+github.com/prometheus/common v0.44.0 h1:+5BrQJwiBB9xsMygAB3TNvpQKOwlkc25LbISbrdOOfY=

+github.com/prometheus/common v0.44.0/go.mod h1:ofAIvZbQ1e/nugmZGz4/qCb9Ap1VoSTIO7x0VV9VvuY=

 github.com/prometheus/procfs v0.0.0-20180125133057-cb4147076ac7/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=

 github.com/prometheus/procfs v0.0.0-20180725123919-05ee40e3a273/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=

 github.com/prometheus/procfs v0.0.0-20181005140218-185b4288413d/go.mod h1:c3At6R/oaqEKCNdg8wHV1ftS6bRYblBhIjjI8uT2IGk=

@@ -1090,8 +1090,8 @@ github.com/prometheus/procfs v0.0.5/go.mod h1:4A/X28fw3Fc593LaREMrKMqOKvUAntwMDa

 github.com/prometheus/procfs v0.0.8/go.mod h1:7Qr8sr6344vo1JqZ6HhLceV9o3AJ1Ff+GxbHq6oeK9A=

 github.com/prometheus/procfs v0.1.3/go.mod h1:lV6e/gmhEcM9IjHGsFOCxxuZ+z1YqCvr4OA4YeYWdaU=

 github.com/prometheus/procfs v0.6.0/go.mod h1:cz+aTbrPOrUb4q7XlbU9ygM+/jj0fzG6c1xBZuNvfVA=

-github.com/prometheus/procfs v0.9.0 h1:wzCHvIvM5SxWqYvwgVL7yJY8Lz3PKn49KQtpgMYJfhI=

-github.com/prometheus/procfs v0.9.0/go.mod h1:+pB4zwohETzFnmlpe6yd2lSc+0/46IYZRB/chUwxUZY=

+github.com/prometheus/procfs v0.11.1 h1:xRC8Iq1yyca5ypa9n1EZnWZkt7dwcoRPQwX/5gwaUuI=

+github.com/prometheus/procfs v0.11.1/go.mod h1:eesXgaPo1q7lBpVMoMy0ZOFTth9hBn4W/y0/p/ScXhY=

 github.com/prometheus/tsdb v0.7.1/go.mod h1:qhTCs0VvXwvX/y3TZrWD7rabWM+ijKTux40TwIPHuXU=

 github.com/quasilyte/go-consistent v0.0.0-20190521200055-c6f3937de18c/go.mod h1:5STLWrekHfjyYwxBRVRXNOSewLJ3PWfDJd1VyTS21fI=

 github.com/quasilyte/go-ruleguard v0.1.2-0.20200318202121-b00d7a75d3d8/go.mod h1:CGFX09Ci3pq9QZdj86B+VGIdNj4VyCo2iPOGS9esB/k=

@@ -20,6 +20,7 @@ import (

 	"time"

 	dto "github.com/prometheus/client_model/go"

+	"google.golang.org/protobuf/types/known/timestamppb"

 )

 // Counter is a Metric that represents a single numerical value that only ever

@@ -59,6 +60,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 Constraint

+	// 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

@@ -78,8 +91,12 @@ func NewCounter(opts CounterOpts) Counter {

 		nil,

 		opts.ConstLabels,

 	)

-	result := &counter{desc: desc, labelPairs: desc.constLabelPairs, now: time.Now}

+	if opts.now == nil {

+		opts.now = time.Now

+	}

+	result := &counter{desc: desc, labelPairs: desc.constLabelPairs, now: opts.now}

 	result.init(result) // Init self-collection.

+	result.createdTs = timestamppb.New(opts.now())

 	return result

 }

@@ -94,10 +111,12 @@ type counter struct {

 	selfCollector

 	desc *Desc

+	createdTs  *timestamppb.Timestamp

 	labelPairs []*dto.LabelPair

 	exemplar   atomic.Value // Containing nil or a *dto.Exemplar.

-	now func() time.Time // To mock out time.Now() for testing.

+	// now is for testing purposes, by default it's time.Now.

+	now func() time.Time

 }

 func (c *counter) Desc() *Desc {

@@ -147,8 +166,7 @@ func (c *counter) Write(out *dto.Metric) error {

 		exemplar = e.(*dto.Exemplar)

 	}

 	val := c.get()

-

-	return populateMetric(CounterValue, val, c.labelPairs, exemplar, out)

+	return populateMetric(CounterValue, val, c.labelPairs, exemplar, out, c.createdTs)

 }

 func (c *counter) updateExemplar(v float64, l Labels) {

@@ -174,19 +192,31 @@ 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 {

-	desc := NewDesc(

+	return V2.NewCounterVec(CounterVecOpts{

+		CounterOpts:    opts,

+		VariableLabels: UnconstrainedLabels(labelNames),

+	})

+}

+

+// 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,

 	)

+	if opts.now == nil {

+		opts.now = time.Now

+	}

 	return &CounterVec{

 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {

-			if len(lvs) != len(desc.variableLabels) {

-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))

+			if len(lvs) != len(desc.variableLabels.names) {

+				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))

 			}

-			result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: time.Now}

+			result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: opts.now}

 			result.init(result) // Init self-collection.

+			result.createdTs = timestamppb.New(opts.now())

 			return result

 		}),

 	}

@@ -14,20 +14,16 @@

 package prometheus

 import (

-	"errors"

 	"fmt"

 	"sort"

 	"strings"

 	"github.com/cespare/xxhash/v2"

-

-	"github.com/prometheus/client_golang/prometheus/internal"

-

-	//nolint:staticcheck // Ignore SA1019. Need to keep deprecated package for compatibility.

-	"github.com/golang/protobuf/proto"

+	dto "github.com/prometheus/client_model/go"

 	"github.com/prometheus/common/model"

+	"google.golang.org/protobuf/proto"

-	dto "github.com/prometheus/client_model/go"

+	"github.com/prometheus/client_golang/prometheus/internal"

 )

 // Desc is the descriptor used by every Prometheus Metric. It is essentially

@@ -54,9 +50,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

+	// variableLabels contains names of labels and normalization function for

+	// which the metric maintains variable values.

+	variableLabels *compiledLabels

 	// 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.

@@ -80,10 +76,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.compile(),

 	}

 	if !model.IsValidMetricName(model.LabelValue(fqName)) {

 		d.err = fmt.Errorf("%q is not a valid metric name", fqName)

@@ -93,7 +103,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.names))

 	labelNameSet := map[string]struct{}{}

 	// First add only the const label names and sort them...

 	for labelName := range constLabels {

@@ -118,16 +128,16 @@ 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.names {

+		if !checkLabelName(label) {

+			d.err = fmt.Errorf("%q is not a valid label name for metric %q", label, fqName)

 			return d

 		}

-		labelNames = append(labelNames, "$"+labelName)

-		labelNameSet[labelName] = struct{}{}

+		labelNames = append(labelNames, "$"+label)

+		labelNameSet[label] = struct{}{}

 	}

 	if len(labelNames) != len(labelNameSet) {

-		d.err = errors.New("duplicate label names")

+		d.err = fmt.Errorf("duplicate label names in constant and variable labels for metric %q", fqName)

 		return d

 	}

@@ -179,11 +189,19 @@ func (d *Desc) String() string {

 			fmt.Sprintf("%s=%q", lp.GetName(), lp.GetValue()),

 		)

 	}

+	vlStrings := make([]string, 0, len(d.variableLabels.names))

+	for _, vl := range d.variableLabels.names {

+		if fn, ok := d.variableLabels.labelConstraints[vl]; ok && fn != nil {

+			vlStrings = append(vlStrings, fmt.Sprintf("c(%s)", vl))

+		} else {

+			vlStrings = append(vlStrings, vl)

+		}

+	}

 	return fmt.Sprintf(

-		"Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: %v}",

+		"Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: {%s}}",

 		d.fqName,

 		d.help,

 		strings.Join(lpStrings, ","),

-		d.variableLabels,

+		strings.Join(vlStrings, ","),

 	)

 }

@@ -37,35 +37,35 @@

 //

 //	type metrics struct {

 //		cpuTemp  prometheus.Gauge

-//	  hdFailures *prometheus.CounterVec

+//		hdFailures *prometheus.CounterVec

 //	}

 //

 //	func NewMetrics(reg prometheus.Registerer) *metrics {

-//	  m := &metrics{

-//	    cpuTemp: prometheus.NewGauge(prometheus.GaugeOpts{

-//	      Name: "cpu_temperature_celsius",

-//	      Help: "Current temperature of the CPU.",

-//	    }),

-//	    hdFailures: prometheus.NewCounterVec(

-//	      prometheus.CounterOpts{

-//	        Name: "hd_errors_total",

-//	        Help: "Number of hard-disk errors.",

-//	      },

-//	      []string{"device"},

-//	    ),

-//	  }

-//	  reg.MustRegister(m.cpuTemp)

-//	  reg.MustRegister(m.hdFailures)

-//	  return m

+//		m := &metrics{

+//			cpuTemp: prometheus.NewGauge(prometheus.GaugeOpts{

+//				Name: "cpu_temperature_celsius",

+//				Help: "Current temperature of the CPU.",

+//			}),

+//			hdFailures: prometheus.NewCounterVec(

+//				prometheus.CounterOpts{

+//					Name: "hd_errors_total",

+//					Help: "Number of hard-disk errors.",

+//				},

+//				[]string{"device"},

+//			),

+//		}

+//		reg.MustRegister(m.cpuTemp)

+//		reg.MustRegister(m.hdFailures)

+//		return m

 //	}

 //

 //	func main() {

-//	  // Create a non-global registry.

-//	  reg := prometheus.NewRegistry()

+//		// Create a non-global registry.

+//		reg := prometheus.NewRegistry()

 //

-//	  // Create new metrics and register them using the custom registry.

-//	  m := NewMetrics(reg)

-//	  // Set values for the new created metrics.

+//		// Create new metrics and register them using the custom registry.

+//		m := NewMetrics(reg)

+//		// Set values for the new created metrics.

 //		m.cpuTemp.Set(65.3)

 //		m.hdFailures.With(prometheus.Labels{"device":"/dev/sda"}).Inc()

 //

@@ -48,7 +48,7 @@ func (e *expvarCollector) Collect(ch chan<- Metric) {

 			continue

 		}

 		var v interface{}

-		labels := make([]string, len(desc.variableLabels))

+		labels := make([]string, len(desc.variableLabels.names))

 		if err := json.Unmarshal([]byte(expVar.String()), &v); err != nil {

 			ch <- NewInvalidMetric(desc, err)

 			continue

@@ -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 Constraint

+	// 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

@@ -123,7 +135,7 @@ func (g *gauge) Sub(val float64) {

 func (g *gauge) Write(out *dto.Metric) error {

 	val := math.Float64frombits(atomic.LoadUint64(&g.valBits))

-	return populateMetric(GaugeValue, val, g.labelPairs, nil, out)

+	return populateMetric(GaugeValue, val, g.labelPairs, nil, out, nil)

 }

 // GaugeVec is a Collector that bundles a set of Gauges that all share the same

@@ -138,16 +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 {

-	desc := NewDesc(

+	return V2.NewGaugeVec(GaugeVecOpts{

+		GaugeOpts:      opts,

+		VariableLabels: UnconstrainedLabels(labelNames),

+	})

+}

+

+// 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,

 	)

 	return &GaugeVec{

 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {

-			if len(lvs) != len(desc.variableLabels) {

-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))

+			if len(lvs) != len(desc.variableLabels.names) {

+				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))

 			}

 			result := &gauge{desc: desc, labelPairs: MakeLabelPairs(desc, lvs)}

 			result.init(result) // Init self-collection.

@@ -23,11 +23,10 @@ import (

 	"strings"

 	"sync"

-	//nolint:staticcheck // Ignore SA1019. Need to keep deprecated package for compatibility.

-	"github.com/golang/protobuf/proto"

-	dto "github.com/prometheus/client_model/go"

-

 	"github.com/prometheus/client_golang/prometheus/internal"

+

+	dto "github.com/prometheus/client_model/go"

+	"google.golang.org/protobuf/proto"

 )

 const (

@@ -22,10 +22,10 @@ import (

 	"sync/atomic"

 	"time"

-	//nolint:staticcheck // Ignore SA1019. Need to keep deprecated package for compatibility.

-	"github.com/golang/protobuf/proto"

-

 	dto "github.com/prometheus/client_model/go"

+

+	"google.golang.org/protobuf/proto"

+	"google.golang.org/protobuf/types/known/timestamppb"

 )

 // nativeHistogramBounds for the frac of observed values. Only relevant for

@@ -392,7 +392,7 @@ type HistogramOpts struct {

 	// zero, it is replaced by default buckets. The default buckets are

 	// DefBuckets if no buckets for a native histogram (see below) are used,

 	// otherwise the default is no buckets. (In other words, if you want to

-	// use both reguler buckets and buckets for a native histogram, you have

+	// use both regular buckets and buckets for a native histogram, you have

 	// to define the regular buckets here explicitly.)

 	Buckets []float64

@@ -402,7 +402,7 @@ type HistogramOpts struct {

 	// Histogram by a Prometheus server with that feature enabled (requires

 	// Prometheus v2.40+). Sparse buckets are exponential buckets covering

 	// the whole float64 range (with the exception of the “zero” bucket, see

-	// SparseBucketsZeroThreshold below). From any one bucket to the next,

+	// NativeHistogramZeroThreshold below). From any one bucket to the next,

 	// the width of the bucket grows by a constant

 	// factor. NativeHistogramBucketFactor provides an upper bound for this

 	// factor (exception see below). The smaller

@@ -414,8 +414,8 @@ type HistogramOpts struct {

 	// and 2, same as between 2 and 4, and 4 and 8, etc.).

 	//

 	// Details about the actually used factor: The factor is calculated as

-	// 2^(2^n), where n is an integer number between (and including) -8 and

-	// 4. n is chosen so that the resulting factor is the largest that is

+	// 2^(2^-n), where n is an integer number between (and including) -4 and

+	// 8. n is chosen so that the resulting factor is the largest that is

 	// still smaller or equal to NativeHistogramBucketFactor. Note that the

 	// smallest possible factor is therefore approx. 1.00271 (i.e. 2^(2^-8)

 	// ). If NativeHistogramBucketFactor is greater than 1 but smaller than

@@ -429,12 +429,12 @@ type HistogramOpts struct {

 	// a major version bump.

 	NativeHistogramBucketFactor float64

 	// All observations with an absolute value of less or equal

-	// NativeHistogramZeroThreshold are accumulated into a “zero”

-	// bucket. For best results, this should be close to a bucket

-	// boundary. This is usually the case if picking a power of two. If

+	// NativeHistogramZeroThreshold are accumulated into a “zero” bucket.

+	// For best results, this should be close to a bucket boundary. This is

+	// usually the case if picking a power of two. If

 	// NativeHistogramZeroThreshold is left at zero,

-	// DefSparseBucketsZeroThreshold is used as the threshold. To configure

-	// a zero bucket with an actual threshold of zero (i.e. only

+	// DefNativeHistogramZeroThreshold is used as the threshold. To

+	// configure a zero bucket with an actual threshold of zero (i.e. only

 	// observations of precisely zero will go into the zero bucket), set

 	// NativeHistogramZeroThreshold to the NativeHistogramZeroThresholdZero

 	// constant (or any negative float value).

@@ -447,26 +447,46 @@ type HistogramOpts struct {

 	// Histogram are sufficiently wide-spread. In particular, this could be

 	// used as a DoS attack vector. Where the observed values depend on

 	// external inputs, it is highly recommended to set a

-	// NativeHistogramMaxBucketNumber.)  Once the set

+	// NativeHistogramMaxBucketNumber.) Once the set

 	// NativeHistogramMaxBucketNumber is exceeded, the following strategy is

-	// enacted: First, if the last reset (or the creation) of the histogram

-	// is at least NativeHistogramMinResetDuration ago, then the whole

-	// histogram is reset to its initial state (including regular

-	// buckets). If less time has passed, or if

-	// NativeHistogramMinResetDuration is zero, no reset is

-	// performed. Instead, the zero threshold is increased sufficiently to

-	// reduce the number of buckets to or below

-	// NativeHistogramMaxBucketNumber, but not to more than

-	// NativeHistogramMaxZeroThreshold. Thus, if

-	// NativeHistogramMaxZeroThreshold is already at or below the current

-	// zero threshold, nothing happens at this step. After that, if the

-	// number of buckets still exceeds NativeHistogramMaxBucketNumber, the

-	// resolution of the histogram is reduced by doubling the width of the

-	// sparse buckets (up to a growth factor between one bucket to the next

-	// of 2^(2^4) = 65536, see above).

+	// enacted:

+	//  - First, if the last reset (or the creation) of the histogram is at

+	//    least NativeHistogramMinResetDuration ago, then the whole

+	//    histogram is reset to its initial state (including regular

+	//    buckets).

+	//  - If less time has passed, or if NativeHistogramMinResetDuration is

+	//    zero, no reset is performed. Instead, the zero threshold is

+	//    increased sufficiently to reduce the number of buckets to or below

+	//    NativeHistogramMaxBucketNumber, but not to more than

+	//    NativeHistogramMaxZeroThreshold. Thus, if

+	//    NativeHistogramMaxZeroThreshold is already at or below the current

+	//    zero threshold, nothing happens at this step.

+	//  - After that, if the number of buckets still exceeds

+	//    NativeHistogramMaxBucketNumber, the resolution of the histogram is

+	//    reduced by doubling the width of the sparse buckets (up to a

+	//    growth factor between one bucket to the next of 2^(2^4) = 65536,

+	//    see above).

+	//  - Any increased zero threshold or reduced resolution is reset back

+	//    to their original values once NativeHistogramMinResetDuration has

+	//    passed (since the last reset or the creation of the histogram).

 	NativeHistogramMaxBucketNumber  uint32

 	NativeHistogramMinResetDuration time.Duration

 	NativeHistogramMaxZeroThreshold float64

+

+	// now is for testing purposes, by default it's time.Now.

+	now func() time.Time

+}

+

+// 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 Constraint

+	// function, if provided.

+	VariableLabels ConstrainableLabels

 }

 // NewHistogram creates a new Histogram based on the provided HistogramOpts. It

@@ -488,11 +508,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))

+	if len(desc.variableLabels.names) != len(labelValues) {

+		panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, labelValues))

 	}

-	for _, n := range desc.variableLabels {

+	for _, n := range desc.variableLabels.names {

 		if n == bucketLabel {

 			panic(errBucketLabelNotAllowed)

 		}

@@ -503,6 +523,10 @@ func newHistogram(desc *Desc, opts HistogramOpts, labelValues ...string) Histogr

 		}

 	}

+	if opts.now == nil {

+		opts.now = time.Now

+	}

+

 	h := &histogram{

 		desc:                            desc,

 		upperBounds:                     opts.Buckets,

@@ -510,8 +534,8 @@ func newHistogram(desc *Desc, opts HistogramOpts, labelValues ...string) Histogr

 		nativeHistogramMaxBuckets:       opts.NativeHistogramMaxBucketNumber,

 		nativeHistogramMaxZeroThreshold: opts.NativeHistogramMaxZeroThreshold,

 		nativeHistogramMinResetDuration: opts.NativeHistogramMinResetDuration,

-		lastResetTime:                   time.Now(),

-		now:                             time.Now,

+		lastResetTime:                   opts.now(),

+		now:                             opts.now,

 	}

 	if len(h.upperBounds) == 0 && opts.NativeHistogramBucketFactor <= 1 {

 		h.upperBounds = DefBuckets

@@ -544,16 +568,12 @@ func newHistogram(desc *Desc, opts HistogramOpts, labelValues ...string) Histogr

 	}

 	// Finally we know the final length of h.upperBounds and can make buckets

 	// for both counts as well as exemplars:

-	h.counts[0] = &histogramCounts{

-		buckets:                          make([]uint64, len(h.upperBounds)),

-		nativeHistogramZeroThresholdBits: math.Float64bits(h.nativeHistogramZeroThreshold),

-		nativeHistogramSchema:            h.nativeHistogramSchema,

-	}

-	h.counts[1] = &histogramCounts{

-		buckets:                          make([]uint64, len(h.upperBounds)),

-		nativeHistogramZeroThresholdBits: math.Float64bits(h.nativeHistogramZeroThreshold),

-		nativeHistogramSchema:            h.nativeHistogramSchema,

-	}

+	h.counts[0] = &histogramCounts{buckets: make([]uint64, len(h.upperBounds))}

+	atomic.StoreUint64(&h.counts[0].nativeHistogramZeroThresholdBits, math.Float64bits(h.nativeHistogramZeroThreshold))

+	atomic.StoreInt32(&h.counts[0].nativeHistogramSchema, h.nativeHistogramSchema)

+	h.counts[1] = &histogramCounts{buckets: make([]uint64, len(h.upperBounds))}

+	atomic.StoreUint64(&h.counts[1].nativeHistogramZeroThresholdBits, math.Float64bits(h.nativeHistogramZeroThreshold))

+	atomic.StoreInt32(&h.counts[1].nativeHistogramSchema, h.nativeHistogramSchema)

 	h.exemplars = make([]atomic.Value, len(h.upperBounds)+1)

 	h.init(h) // Init self-collection.

@@ -632,8 +652,8 @@ func (hc *histogramCounts) observe(v float64, bucket int, doSparse bool) {

 			if frac == 0.5 {

 				key--

 			}

-			div := 1 << -schema

-			key = (key + div - 1) / div

+			offset := (1 << -schema) - 1

+			key = (key + offset) >> -schema

 		}

 		if isInf {

 			key++

@@ -694,9 +714,11 @@ type histogram struct {

 	nativeHistogramMaxZeroThreshold float64

 	nativeHistogramMaxBuckets       uint32

 	nativeHistogramMinResetDuration time.Duration

-	lastResetTime                   time.Time // Protected by mtx.

+	// lastResetTime is protected by mtx. It is also used as created timestamp.

+	lastResetTime time.Time

-	now func() time.Time // To mock out time.Now() for testing.

+	// now is for testing purposes, by default it's time.Now.

+	now func() time.Time

 }

 func (h *histogram) Desc() *Desc {

@@ -735,9 +757,10 @@ func (h *histogram) Write(out *dto.Metric) error {

 	waitForCooldown(count, coldCounts)

 	his := &dto.Histogram{

-		Bucket:      make([]*dto.Bucket, len(h.upperBounds)),

-		SampleCount: proto.Uint64(count),

-		SampleSum:   proto.Float64(math.Float64frombits(atomic.LoadUint64(&coldCounts.sumBits))),

+		Bucket:           make([]*dto.Bucket, len(h.upperBounds)),

+		SampleCount:      proto.Uint64(count),

+		SampleSum:        proto.Float64(math.Float64frombits(atomic.LoadUint64(&coldCounts.sumBits))),

+		CreatedTimestamp: timestamppb.New(h.lastResetTime),

 	}

 	out.Histogram = his

 	out.Label = h.labelPairs

@@ -775,6 +798,16 @@ func (h *histogram) Write(out *dto.Metric) error {

 		his.ZeroCount = proto.Uint64(zeroBucket)

 		his.NegativeSpan, his.NegativeDelta = makeBuckets(&coldCounts.nativeHistogramBucketsNegative)

 		his.PositiveSpan, his.PositiveDelta = makeBuckets(&coldCounts.nativeHistogramBucketsPositive)

+

+		// Add a no-op span to a histogram without observations and with

+		// a zero threshold of zero. Otherwise, a native histogram would

+		// look like a classic histogram to scrapers.

+		if *his.ZeroThreshold == 0 && *his.ZeroCount == 0 && len(his.PositiveSpan) == 0 && len(his.NegativeSpan) == 0 {

+			his.PositiveSpan = []*dto.BucketSpan{{

+				Offset: proto.Int32(0),

+				Length: proto.Uint32(0),

+			}}

+		}

 	}

 	addAndResetCounts(hotCounts, coldCounts)

 	return nil

@@ -810,7 +843,7 @@ func (h *histogram) observe(v float64, bucket int) {

 	}

 }

-// limitSparsebuckets applies a strategy to limit the number of populated sparse

+// limitBuckets applies a strategy to limit the number of populated sparse

 // buckets. It's generally best effort, and there are situations where the

 // number can go higher (if even the lowest resolution isn't enough to reduce

 // the number sufficiently, or if the provided counts aren't fully updated yet

@@ -847,20 +880,23 @@ func (h *histogram) limitBuckets(counts *histogramCounts, value float64, bucket

 	h.doubleBucketWidth(hotCounts, coldCounts)

 }

-// maybeReset resests the whole histogram if at least h.nativeHistogramMinResetDuration

+// maybeReset resets the whole histogram if at least h.nativeHistogramMinResetDuration

 // has been passed. It returns true if the histogram has been reset. The caller

 // must have locked h.mtx.

-func (h *histogram) maybeReset(hot, cold *histogramCounts, coldIdx uint64, value float64, bucket int) bool {

+func (h *histogram) maybeReset(

+	hot, cold *histogramCounts, coldIdx uint64, value float64, bucket int,

+) bool {

 	// We are using the possibly mocked h.now() rather than

 	// time.Since(h.lastResetTime) to enable testing.

-	if h.nativeHistogramMinResetDuration == 0 || h.now().Sub(h.lastResetTime) < h.nativeHistogramMinResetDuration {

+	if h.nativeHistogramMinResetDuration == 0 ||

+		h.now().Sub(h.lastResetTime) < h.nativeHistogramMinResetDuration {

 		return false

 	}

 	// Completely reset coldCounts.

 	h.resetCounts(cold)

 	// Repeat the latest observation to not lose it completely.

 	cold.observe(value, bucket, true)

-	// Make coldCounts the new hot counts while ressetting countAndHotIdx.

+	// Make coldCounts the new hot counts while resetting countAndHotIdx.

 	n := atomic.SwapUint64(&h.countAndHotIdx, (coldIdx<<63)+1)

 	count := n & ((1 << 63) - 1)

 	waitForCooldown(count, hot)

@@ -1034,15 +1070,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 {

-	desc := NewDesc(

+	return V2.NewHistogramVec(HistogramVecOpts{

+		HistogramOpts:  opts,

+		VariableLabels: UnconstrainedLabels(labelNames),

+	})

+}

+

+// 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,

 	)

 	return &HistogramVec{

 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {

-			return newHistogram(desc, opts, lvs...)

+			return newHistogram(desc, opts.HistogramOpts, lvs...)

 		}),

 	}

 }

@@ -1161,6 +1205,7 @@ type constHistogram struct {

 	sum        float64

 	buckets    map[float64]uint64

 	labelPairs []*dto.LabelPair

+	createdTs  *timestamppb.Timestamp

 }

 func (h *constHistogram) Desc() *Desc {

@@ -1168,7 +1213,9 @@ func (h *constHistogram) Desc() *Desc {

 }

 func (h *constHistogram) Write(out *dto.Metric) error {

-	his := &dto.Histogram{}

+	his := &dto.Histogram{

+		CreatedTimestamp: h.createdTs,

+	}

 	buckets := make([]*dto.Bucket, 0, len(h.buckets))

@@ -1215,7 +1262,7 @@ func NewConstHistogram(

 	if desc.err != nil {

 		return nil, desc.err

 	}

-	if err := validateLabelValues(labelValues, len(desc.variableLabels)); err != nil {

+	if err := validateLabelValues(labelValues, len(desc.variableLabels.names)); err != nil {

 		return nil, err

 	}

 	return &constHistogram{

@@ -1309,7 +1356,7 @@ func makeBuckets(buckets *sync.Map) ([]*dto.BucketSpan, []int64) {

 		// Multiple spans with only small gaps in between are probably

 		// encoded more efficiently as one larger span with a few empty

 		// buckets. Needs some research to find the sweet spot. For now,

-		// we assume that gaps of one ore two buckets should not create

+		// we assume that gaps of one or two buckets should not create

 		// a new span.

 		iDelta := int32(i - nextI)

 		if n == 0 || iDelta > 2 {

@@ -14,7 +14,7 @@

 // It provides tools to compare sequences of strings and generate textual diffs.

 //

 // Maintaining `GetUnifiedDiffString` here because original repository

-// (https://github.com/pmezard/go-difflib) is no loger maintained.

+// (https://github.com/pmezard/go-difflib) is no longer maintained.

 package internal

 import (

@@ -32,6 +32,104 @@ import (

 // create a Desc.

 type Labels map[string]string

+// LabelConstraint normalizes label values.

+type LabelConstraint func(string) string

+

+// ConstrainedLabels represents a label name and its constrain function

+// to normalize label values. This type is commonly used when constructing

+// metric vector Collectors.

+type ConstrainedLabel struct {

+	Name       string

+	Constraint LabelConstraint

+}

+

+// ConstrainableLabels is an interface that allows creating of labels that can

+// be optionally constrained.

+//

+//	prometheus.V2().NewCounterVec(CounterVecOpts{

+//	  CounterOpts: {...}, // Usual CounterOpts fields

+//	  VariableLabels: []ConstrainedLabels{

+//	    {Name: "A"},

+//	    {Name: "B", Constraint: func(v string) string { ... }},

+//	  },

+//	})

+type ConstrainableLabels interface {

+	compile() *compiledLabels

+	labelNames() []string

+}

+

+// ConstrainedLabels represents a collection of label name -> constrain function

+// to normalize label values. This type is commonly used when constructing

+// metric vector Collectors.

+type ConstrainedLabels []ConstrainedLabel

+

+func (cls ConstrainedLabels) compile() *compiledLabels {

+	compiled := &compiledLabels{

+		names:            make([]string, len(cls)),

+		labelConstraints: map[string]LabelConstraint{},

+	}

+

+	for i, label := range cls {

+		compiled.names[i] = label.Name

+		if label.Constraint != nil {

+			compiled.labelConstraints[label.Name] = label.Constraint

+		}

+	}

+

+	return compiled

+}

+

+func (cls ConstrainedLabels) labelNames() []string {

+	names := make([]string, len(cls))

+	for i, label := range cls {

+		names[i] = label.Name

+	}

+	return names

+}

+

+// UnconstrainedLabels represents collection of label without any constraint on

+// their value. Thus, it is simply a collection of label names.

+//

+//	UnconstrainedLabels([]string{ "A", "B" })

+//

+// is equivalent to

+//

+//	ConstrainedLabels {

+//	  { Name: "A" },

+//	  { Name: "B" },

+//	}

+type UnconstrainedLabels []string

+

+func (uls UnconstrainedLabels) compile() *compiledLabels {

+	return &compiledLabels{

+		names: uls,

+	}

+}

+

+func (uls UnconstrainedLabels) labelNames() []string {