prometheus · bwplotka · Apr 2, 2026 · Nov 26, 2023 · Nov 30, 2023 · Nov 30, 2023
@@ -32,6 +32,7 @@ func main() {
 	requestDurations := prometheus.NewHistogram(prometheus.HistogramOpts{
 		Name:    "http_request_duration_seconds",
 		Help:    "A histogram of the HTTP request durations in seconds.",
+		Unit:    "seconds",
 		Buckets: prometheus.ExponentialBuckets(0.1, 1.5, 5),
 	})
 

@@ -10,15 +10,15 @@ require (
 	github.com/klauspost/compress v1.18.5
 	github.com/kylelemons/godebug v1.1.0
 	github.com/prometheus/client_model v0.6.2
-	github.com/prometheus/common v0.67.5
+	github.com/prometheus/common v0.67.6-0.20260224092343-e4c38a0aea47
 	github.com/prometheus/procfs v0.20.1
 	go.uber.org/goleak v1.3.0
 	golang.org/x/sys v0.42.0
 	google.golang.org/protobuf v1.36.11
 )
 
 require (
-	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/jpillora/backoff v1.0.0 // indirect
 	github.com/kr/pretty v0.3.1 // indirect
@@ -27,9 +27,9 @@ require (
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f // indirect
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
-	golang.org/x/net v0.48.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
 	golang.org/x/oauth2 v0.34.0 // indirect
-	golang.org/x/text v0.32.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
 )
 
 exclude github.com/prometheus/client_golang v1.12.1
@@ -6,8 +6,8 @@ github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ3
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
-github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -39,8 +39,8 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
-github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
+github.com/prometheus/common v0.67.6-0.20260224092343-e4c38a0aea47 h1:DXz2mpU9UOivlNi73hwwVm7KSYGImaPDdYsniI6uOdE=
+github.com/prometheus/common v0.67.6-0.20260224092343-e4c38a0aea47/go.mod h1:6wuJRcHcgBM1w2vIgTuCW7XSzlfCat/lS3C39U02oDA=
 github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
 github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
@@ -54,14 +54,14 @@ go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
 go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
-golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
-golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
 golang.org/x/oauth2 v0.34.0 h1:hqK/t4AKgbqWkdkcAeI8XLmbK+4m4G5YeQRrmiotGlw=
 golang.org/x/oauth2 v0.34.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
-golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
+golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
+golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

@@ -85,11 +85,12 @@ type CounterVecOpts struct {
 // Both internal tracking values are added up in the Write method. This has to
 // be taken into account when it comes to precision and overflow behavior.
 func NewCounter(opts CounterOpts) Counter {
-	desc := NewDesc(
+	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		nil,
+		UnconstrainedLabels(nil),
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	)
 	if opts.now == nil {
 		opts.now = time.Now
@@ -205,6 +206,7 @@ func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
 		opts.Help,
 		opts.VariableLabels,
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	)
 	if opts.now == nil {
 		opts.now = time.Now
@@ -349,10 +351,11 @@ type CounterFunc interface {
 //
 // Check out the ExampleGaugeFunc examples for the similar GaugeFunc.
 func NewCounterFunc(opts CounterOpts, function func() float64) CounterFunc {
-	return newValueFunc(NewDesc(
+	return newValueFunc(V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		nil,
+		UnconstrainedLabels(nil),
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	), CounterValue, function)
 }
@@ -47,6 +47,8 @@ type Desc struct {
 	fqName string
 	// help provides some helpful information about this metric.
 	help string
+	// unit provides the unit of this metric.
+	unit string
 	// constLabelPairs contains precalculated DTO label pairs based on
 	// the constant labels.
 	constLabelPairs []*dto.LabelPair
@@ -66,6 +68,16 @@ type Desc struct {
 	err error
 }
 
+// DescOpt allows setting optional fields for NewDesc.
+type DescOpt func(*Desc)
+
+// WithUnit sets the unit for a Desc.
+func WithUnit(unit string) DescOpt {
+	return func(d *Desc) {
+		d.unit = unit
+	}
+}
+
 // 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.
@@ -89,12 +101,16 @@ func NewDesc(fqName, help string, variableLabels []string, constLabels Labels) *
 //
 // 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 {
+func (v2) NewDesc(fqName, help string, variableLabels ConstrainableLabels, constLabels Labels, opts ...DescOpt) *Desc {
 	d := &Desc{
 		fqName:         fqName,
 		help:           help,
 		variableLabels: variableLabels.compile(),
 	}
+
+	for _, opt := range opts {
+		opt(d)
+	}
 	//nolint:staticcheck // TODO: Don't use deprecated model.NameValidationScheme.
 	if !model.NameValidationScheme.IsValidMetricName(fqName) {
 		d.err = fmt.Errorf("%q is not a valid metric name", fqName)
@@ -150,11 +166,13 @@ func (v2) NewDesc(fqName, help string, variableLabels ConstrainableLabels, const
 	d.id = xxh.Sum64()
 	// Sort labelNames so that order doesn't matter for the hash.
 	sort.Strings(labelNames)
-	// Now hash together (in this order) the help string and the sorted
+	// Now hash together (in this order) the help string, the unit string and the sorted
 	// label names.
 	xxh.Reset()
 	xxh.WriteString(help)
 	xxh.Write(separatorByteSlice)
+	xxh.WriteString(d.unit)
+	xxh.Write(separatorByteSlice)
 	for _, labelName := range labelNames {
 		xxh.WriteString(labelName)
 		xxh.Write(separatorByteSlice)
@@ -211,9 +229,10 @@ func (d *Desc) String() string {
 		}
 	}
 	return fmt.Sprintf(
-		"Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: {%s}}",
+		"Desc{fqName: %q, help: %q, unit: %q, constLabels: {%s}, variableLabels: {%s}}",
 		d.fqName,
 		d.help,
+		d.unit,
 		strings.Join(lpStrings, ","),
 		strings.Join(vlStrings, ","),
 	)

@@ -62,7 +62,7 @@ func TestNewDescWithNilLabelValues_String(t *testing.T) {
 		nil,
 		nil,
 	)
-	if desc.String() != `Desc{fqName: "sample_label", help: "sample label", constLabels: {}, variableLabels: {}}` {
+	if desc.String() != `Desc{fqName: "sample_label", help: "sample label", unit: "", constLabels: {}, variableLabels: {}}` {
 		t.Errorf("String: unexpected output: %s", desc.String())
 	}
 }
@@ -71,7 +71,20 @@ func TestNewInvalidDesc_String(t *testing.T) {
 	desc := NewInvalidDesc(
 		nil,
 	)
-	if desc.String() != `Desc{fqName: "", help: "", constLabels: {}, variableLabels: {}}` {
+	if desc.String() != `Desc{fqName: "", help: "", unit: "", constLabels: {}, variableLabels: {}}` {
 		t.Errorf("String: unexpected output: %s", desc.String())
 	}
 }
+
+func TestNewDescWithUnit_String(t *testing.T) {
+	desc := V2.NewDesc(
+		"sample_metric_bytes",
+		"sample metric with unit",
+		UnconstrainedLabels(nil),
+		nil,
+		WithUnit("bytes"),
+	)
+	if desc.String() != `Desc{fqName: "sample_metric_bytes", help: "sample metric with unit", unit: "bytes", constLabels: {}, variableLabels: {}}` {
+		t.Errorf("String: unexpected output:\ngot:  %s\nwant: %s", desc.String(), desc.String())
+	}
+}
@@ -53,7 +53,7 @@ type InfoVec struct {
 }
 
 func NewInfoVec(name, help string, labelNames []string) *InfoVec {
-	desc := prometheus.NewDesc(name, help, labelNames, nil)
+	desc := prometheus.V2.NewDesc(name, help, prometheus.UnconstrainedLabels(labelNames), nil)
 	return &InfoVec{
 		MetricVec: prometheus.NewMetricVec(desc, func(lvs ...string) prometheus.Metric {
 			if len(lvs) != len(labelNames) {

@@ -310,9 +310,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.", unit: "", constLabels: {}, variableLabels: {worker_id}} 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.", unit: "", constLabels: {}, variableLabels: {worker_id}} 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.
@@ -381,11 +381,12 @@ func ExampleSummaryVec() {
 }
 
 func ExampleNewConstSummary() {
-	desc := prometheus.NewDesc(
+	desc := prometheus.V2.NewDesc(
 		"http_request_duration_seconds",
 		"A summary of the HTTP request durations.",
-		[]string{"code", "method"},
+		prometheus.UnconstrainedLabels([]string{"code", "method"}),
 		prometheus.Labels{"owner": "example"},
+		prometheus.WithUnit("seconds"),
 	)
 
 	// Create a constant summary from values we got from a 3rd party telemetry system.
@@ -440,7 +441,8 @@ func ExampleHistogram() {
 	temps := prometheus.NewHistogram(prometheus.HistogramOpts{
 		Name:    "pond_temperature_celsius",
 		Help:    "The temperature of the frog pond.", // Sorry, we can't measure how badly it smells.
-		Buckets: prometheus.LinearBuckets(20, 5, 5),  // 5 buckets, each 5 centigrade wide.
+		Unit:    "celsius",
+		Buckets: prometheus.LinearBuckets(20, 5, 5), // 5 buckets, each 5 centigrade wide.
 	})
 
 	// Simulate some observations.
@@ -461,11 +463,12 @@ func ExampleHistogram() {
 }
 
 func ExampleNewConstHistogram() {
-	desc := prometheus.NewDesc(
+	desc := prometheus.V2.NewDesc(
 		"http_request_duration_seconds",
 		"A histogram of the HTTP request durations.",
-		[]string{"code", "method"},
+		prometheus.UnconstrainedLabels([]string{"code", "method"}),
 		prometheus.Labels{"owner": "example"},
+		prometheus.WithUnit("seconds"),
 	)
 
 	// Create a constant histogram from values we got from a 3rd party telemetry system.
@@ -516,11 +519,12 @@ func ExampleNewConstHistogramWithCreatedTimestamp() {
 }
 
 func ExampleNewConstHistogram_withExemplar() {
-	desc := prometheus.NewDesc(
+	desc := prometheus.V2.NewDesc(
 		"http_request_duration_seconds",
 		"A histogram of the HTTP request durations.",
-		[]string{"code", "method"},
+		prometheus.UnconstrainedLabels([]string{"code", "method"}),
 		prometheus.Labels{"owner": "example"},
+		prometheus.WithUnit("seconds"),
 	)
 
 	// Create a constant histogram from values we got from a 3rd party telemetry system.
@@ -686,10 +690,11 @@ temperature_kelvin 4.5
 }
 
 func ExampleNewMetricWithTimestamp() {
-	desc := prometheus.NewDesc(
+	desc := prometheus.V2.NewDesc(
 		"temperature_kelvin",
 		"Current temperature in Kelvin.",
-		nil, nil,
+		prometheus.UnconstrainedLabels(nil), nil,
+		prometheus.WithUnit("kelvin"),
 	)
 
 	// Create a constant gauge from values we got from an external
@@ -719,10 +724,11 @@ func ExampleNewConstMetricWithCreatedTimestamp() {
 	// Here we have a metric that is reported by an external system.
 	// Besides providing the value, the external system also provides the
 	// timestamp when the metric was created.
-	desc := prometheus.NewDesc(
+	desc := prometheus.V2.NewDesc(
 		"time_since_epoch_seconds",
 		"Current epoch time in seconds.",
-		nil, nil,
+		prometheus.UnconstrainedLabels(nil), nil,
+		prometheus.WithUnit("seconds"),
 	)
 
 	timeSinceEpochReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)

@@ -76,11 +76,12 @@ type GaugeVecOpts struct {
 // scenarios for Gauges and Counters, where the former tends to be Set-heavy and
 // the latter Inc-heavy.
 func NewGauge(opts GaugeOpts) Gauge {
-	desc := NewDesc(
+	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		nil,
+		UnconstrainedLabels(nil),
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	)
 	result := &gauge{desc: desc, labelPairs: desc.constLabelPairs}
 	result.init(result) // Init self-collection.
@@ -163,6 +164,7 @@ func (v2) NewGaugeVec(opts GaugeVecOpts) *GaugeVec {
 		opts.Help,
 		opts.VariableLabels,
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	)
 	return &GaugeVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
@@ -302,10 +304,11 @@ type GaugeFunc interface {
 // value of 1. Example:
 // https://github.com/prometheus/common/blob/8558a5b7db3c84fa38b4766966059a7bd5bfa2ee/version/info.go#L36-L56
 func NewGaugeFunc(opts GaugeOpts, function func() float64) GaugeFunc {
-	return newValueFunc(NewDesc(
+	return newValueFunc(V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
-		nil,
+		UnconstrainedLabels(nil),
 		opts.ConstLabels,
+		WithUnit(opts.Unit),
 	), GaugeValue, function)
 }
@@ -171,7 +171,7 @@ func TestGaugeFunc(t *testing.T) {
 		func() float64 { return 3.1415 },
 	)
 
-	if expected, got := `Desc{fqName: "test_name", help: "test help", constLabels: {a="1",b="2"}, variableLabels: {}}`, gf.Desc().String(); expected != got {
+	if expected, got := `Desc{fqName: "test_name", help: "test help", unit: "", constLabels: {a="1",b="2"}, variableLabels: {}}`, gf.Desc().String(); expected != got {
 		t.Errorf("expected %q, got %q", expected, got)
 	}