Optionally add OM unit

.github/workflows/go.yml

@@ -58,5 +58,5 @@ jobs:
           CI: true
 
       - name: Run style and unused
-        if: ${{ matrix.go_version == '1.20' }}
+        if: ${{ matrix.go_version == '1.21' }}
         run: make style unused

.github/workflows/golangci-lint.yml

@@ -28,7 +28,7 @@ jobs:
       - name: install Go
         uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
         with:
-          go-version: 1.20.x
+          go-version: 1.21.x
       - name: Install snmp_exporter/generator dependencies
         run: sudo apt-get update && sudo apt-get -y install libsnmp-dev
         if: github.repository == 'prometheus/snmp_exporter'

examples/exemplars/main.go

@@ -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),
 	})
 
@@ -61,7 +62,10 @@ func main() {
 		"/metrics", promhttp.HandlerFor(
 			registry,
 			promhttp.HandlerOpts{
-				EnableOpenMetrics: true,
+				OpenMetricsOptions: promhttp.OpenMetricsOptions{
+					Enable:     true,
+					EnableUnit: true,
+				},
 			}),
 	)
 	// To test: curl -H 'Accept: application/openmetrics-text' localhost:8080/metrics

examples/gocollector/main.go

@@ -48,7 +48,9 @@ func main() {
 		reg,
 		promhttp.HandlerOpts{
 			// Opt into OpenMetrics to support exemplars.
-			EnableOpenMetrics: true,
+			OpenMetricsOptions: promhttp.OpenMetricsOptions{
+				Enable: true,
+			},
 		},
 	))
 	fmt.Println("Hello world from new Go Collector!")

prometheus/build_info_collector.go

@@ -30,6 +30,7 @@ func NewBuildInfoCollector() Collector {
 		NewDesc(
 			"go_build_info",
 			"Build information about the main Go module.",
+			"",
 			nil, Labels{"path": path, "version": version, "checksum": sum},
 		),
 		GaugeValue, 1)}

prometheus/collectors/dbstats_collector.go

@@ -46,46 +46,55 @@ func NewDBStatsCollector(db *sql.DB, dbName string) prometheus.Collector {
 		maxOpenConnections: prometheus.NewDesc(
 			fqName("max_open_connections"),
 			"Maximum number of open connections to the database.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		openConnections: prometheus.NewDesc(
 			fqName("open_connections"),
 			"The number of established connections both in use and idle.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		inUseConnections: prometheus.NewDesc(
 			fqName("in_use_connections"),
 			"The number of connections currently in use.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		idleConnections: prometheus.NewDesc(
 			fqName("idle_connections"),
 			"The number of idle connections.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		waitCount: prometheus.NewDesc(
 			fqName("wait_count_total"),
 			"The total number of connections waited for.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		waitDuration: prometheus.NewDesc(
 			fqName("wait_duration_seconds_total"),
 			"The total time blocked waiting for a new connection.",
+			"seconds",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		maxIdleClosed: prometheus.NewDesc(
 			fqName("max_idle_closed_total"),
 			"The total number of connections closed due to SetMaxIdleConns.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		maxIdleTimeClosed: prometheus.NewDesc(
 			fqName("max_idle_time_closed_total"),
 			"The total number of connections closed due to SetConnMaxIdleTime.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 		maxLifetimeClosed: prometheus.NewDesc(
 			fqName("max_lifetime_closed_total"),
 			"The total number of connections closed due to SetConnMaxLifetime.",
+			"",
 			nil, prometheus.Labels{"db_name": dbName},
 		),
 	}

prometheus/counter.go

@@ -88,6 +88,7 @@ func NewCounter(opts CounterOpts) Counter {
 	desc := NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		nil,
 		opts.ConstLabels,
 	)
@@ -203,6 +204,7 @@ func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		opts.VariableLabels,
 		opts.ConstLabels,
 	)
@@ -352,6 +354,7 @@ func NewCounterFunc(opts CounterOpts, function func() float64) CounterFunc {
 	return newValueFunc(NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		nil,
 		opts.ConstLabels,
 	), CounterValue, function)

prometheus/desc.go

@@ -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
@@ -75,8 +77,8 @@ 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)
+func NewDesc(fqName, help, unit string, variableLabels []string, constLabels Labels) *Desc {
+	return V2.NewDesc(fqName, help, unit, UnconstrainedLabels(variableLabels), constLabels)
 }
 
 // NewDesc allocates and initializes a new Desc. Errors are recorded in the Desc
@@ -89,10 +91,11 @@ 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, unit string, variableLabels ConstrainableLabels, constLabels Labels) *Desc {
 	d := &Desc{
 		fqName:         fqName,
 		help:           help,
+		unit:           unit,
 		variableLabels: variableLabels.compile(),
 	}
 	if !model.IsValidMetricName(model.LabelValue(fqName)) {
@@ -149,10 +152,11 @@ 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.WriteString(unit)
 	xxh.Write(separatorByteSlice)
 	for _, labelName := range labelNames {
 		xxh.WriteString(labelName)
@@ -198,9 +202,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, ","),
 	)

prometheus/desc_test.go

@@ -21,6 +21,7 @@ func TestNewDescInvalidLabelValues(t *testing.T) {
 	desc := NewDesc(
 		"sample_label",
 		"sample label",
+		"",
 		nil,
 		Labels{"a": "\xFF"},
 	)

prometheus/example_clustermanager_test.go

@@ -66,11 +66,13 @@ var (
 	oomCountDesc = prometheus.NewDesc(
 		"clustermanager_oom_crashes_total",
 		"Number of OOM crashes.",
+		"",
 		[]string{"host"}, nil,
 	)
 	ramUsageDesc = prometheus.NewDesc(
 		"clustermanager_ram_usage_bytes",
 		"RAM usage as reported to the cluster manager.",
+		"bytes",
 		[]string{"host"}, nil,
 	)
 )

prometheus/example_metricvec_test.go

@@ -52,8 +52,8 @@ type InfoVec struct {
 	*prometheus.MetricVec
 }
 
-func NewInfoVec(name, help string, labelNames []string) *InfoVec {
-	desc := prometheus.NewDesc(name, help, labelNames, nil)
+func NewInfoVec(name, help, unit string, labelNames []string) *InfoVec {
+	desc := prometheus.NewDesc(name, help, unit, labelNames, nil)
 	return &InfoVec{
 		MetricVec: prometheus.NewMetricVec(desc, func(lvs ...string) prometheus.Metric {
 			if len(lvs) != len(labelNames) {
@@ -110,6 +110,7 @@ func ExampleMetricVec() {
 	infoVec := NewInfoVec(
 		"library_version_info",
 		"Versions of the libraries used in this binary.",
+		"",
 		[]string{"library", "version"},
 	)
 

prometheus/examples_test.go

@@ -308,9 +308,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.
@@ -382,6 +382,7 @@ func ExampleNewConstSummary() {
 	desc := prometheus.NewDesc(
 		"http_request_duration_seconds",
 		"A summary of the HTTP request durations.",
+		"seconds",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
 	)
@@ -409,7 +410,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.
@@ -433,6 +435,7 @@ func ExampleNewConstHistogram() {
 	desc := prometheus.NewDesc(
 		"http_request_duration_seconds",
 		"A histogram of the HTTP request durations.",
+		"seconds",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
 	)
@@ -460,6 +463,7 @@ func ExampleNewConstHistogram_WithExemplar() {
 	desc := prometheus.NewDesc(
 		"http_request_duration_seconds",
 		"A histogram of the HTTP request durations.",
+		"seconds",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
 	)
@@ -630,6 +634,7 @@ func ExampleNewMetricWithTimestamp() {
 	desc := prometheus.NewDesc(
 		"temperature_kelvin",
 		"Current temperature in Kelvin.",
+		"kelvin",
 		nil, nil,
 	)
 
@@ -663,6 +668,7 @@ func ExampleNewConstMetricWithCreatedTimestamp() {
 	desc := prometheus.NewDesc(
 		"time_since_epoch_seconds",
 		"Current epoch time in seconds.",
+		"seconds",
 		nil, nil,
 	)
 

prometheus/expvar_collector_test.go

@@ -29,16 +29,19 @@ func ExampleNewExpvarCollector() {
 		"memstats": prometheus.NewDesc(
 			"expvar_memstats",
 			"All numeric memstats as one metric family. Not a good role-model, actually... ;-)",
+			"",
 			[]string{"type"}, nil,
 		),
 		"lone-int": prometheus.NewDesc(
 			"expvar_lone_int",
 			"Just an expvar int as an example.",
+			"",
 			nil, nil,
 		),
 		"http-request-map": prometheus.NewDesc(
 			"expvar_http_request_total",
 			"How many http requests processed, partitioned by status code and http method.",
+			"",
 			[]string{"code", "method"}, nil,
 		),
 	})

prometheus/gauge.go

@@ -79,6 +79,7 @@ func NewGauge(opts GaugeOpts) Gauge {
 	desc := NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		nil,
 		opts.ConstLabels,
 	)
@@ -161,6 +162,7 @@ func (v2) NewGaugeVec(opts GaugeVecOpts) *GaugeVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		opts.VariableLabels,
 		opts.ConstLabels,
 	)
@@ -305,6 +307,7 @@ func NewGaugeFunc(opts GaugeOpts, function func() float64) GaugeFunc {
 	return newValueFunc(NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		opts.Unit,
 		nil,
 		opts.ConstLabels,
 	), GaugeValue, function)

prometheus/gauge_test.go

@@ -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)
 	}