Optionally add OM unit

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

prometheus/counter.go

@@ -90,6 +90,7 @@ func NewCounter(opts CounterOpts) Counter {
 		opts.Help,
 		nil,
 		opts.ConstLabels,
+		opts.Unit,
 	)
 	if opts.now == nil {
 		opts.now = time.Now
@@ -203,6 +204,7 @@ func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
+		// opts.Unit, // QUESTION: shall I put this for last?
 		opts.VariableLabels,
 		opts.ConstLabels,
 	)
@@ -354,5 +356,6 @@ func NewCounterFunc(opts CounterOpts, function func() float64) CounterFunc {
 		opts.Help,
 		nil,
 		opts.ConstLabels,
+		opts.Unit,
 	), 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
@@ -66,6 +68,13 @@ type Desc struct {
 	err error
 }
 
+func optionalUnitValue(unit ...string) string {
+	if len(unit) > 0 {
+		return unit[0]
+	}
+	return ""
+}
+
 // 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.
@@ -75,8 +84,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 string, variableLabels []string, constLabels Labels, unit ...string) *Desc {
+	return V2.NewDesc(fqName, help, UnconstrainedLabels(variableLabels), constLabels, optionalUnitValue(unit...))
 }
 
 // NewDesc allocates and initializes a new Desc. Errors are recorded in the Desc
@@ -89,11 +98,12 @@ 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, unit ...string) *Desc {
 	d := &Desc{
 		fqName:         fqName,
 		help:           help,
 		variableLabels: variableLabels.compile(),
+		unit:           optionalUnitValue(unit...),
 	}
 	//nolint:staticcheck // TODO: Don't use deprecated model.NameValidationScheme.
 	if !model.NameValidationScheme.IsValidMetricName(fqName) {
@@ -150,10 +160,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(optionalUnitValue(unit...))
 	xxh.Write(separatorByteSlice)
 	for _, labelName := range labelNames {
 		xxh.WriteString(labelName)
@@ -211,9 +222,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

@@ -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 := NewDesc(
+		"sample_metric_bytes",
+		"sample metric with unit",
+		nil,
+		nil,
+		"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())
+	}
+}

prometheus/example_metricvec_test.go

@@ -52,8 +52,12 @@ type InfoVec struct {
 	*prometheus.MetricVec
 }
 
-func NewInfoVec(name, help string, labelNames []string) *InfoVec {
-	desc := prometheus.NewDesc(name, help, labelNames, nil)
+func NewInfoVec(name, help string, labelNames []string, unit ...string) *InfoVec {
+	var u string
+	if len(unit) > 0 {
+		u = unit[0]
+	}
+	desc := prometheus.NewDesc(name, help, labelNames, nil, u)
 	return &InfoVec{
 		MetricVec: prometheus.NewMetricVec(desc, func(lvs ...string) prometheus.Metric {
 			if len(lvs) != len(labelNames) {

prometheus/examples_test.go

@@ -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.
@@ -386,6 +386,7 @@ func ExampleNewConstSummary() {
 		"A summary of the HTTP request durations.",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
+		"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.
@@ -466,6 +468,7 @@ func ExampleNewConstHistogram() {
 		"A histogram of the HTTP request durations.",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
+		"seconds",
 	)
 
 	// Create a constant histogram from values we got from a 3rd party telemetry system.
@@ -521,6 +524,7 @@ func ExampleNewConstHistogram_withExemplar() {
 		"A histogram of the HTTP request durations.",
 		[]string{"code", "method"},
 		prometheus.Labels{"owner": "example"},
+		"seconds",
 	)
 
 	// Create a constant histogram from values we got from a 3rd party telemetry system.
@@ -690,6 +694,7 @@ func ExampleNewMetricWithTimestamp() {
 		"temperature_kelvin",
 		"Current temperature in Kelvin.",
 		nil, nil,
+		"kelvin",
 	)
 
 	// Create a constant gauge from values we got from an external
@@ -723,6 +728,7 @@ func ExampleNewConstMetricWithCreatedTimestamp() {
 		"time_since_epoch_seconds",
 		"Current epoch time in seconds.",
 		nil, nil,
+		"seconds",
 	)
 
 	timeSinceEpochReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)

prometheus/gauge.go

@@ -81,6 +81,7 @@ func NewGauge(opts GaugeOpts) Gauge {
 		opts.Help,
 		nil,
 		opts.ConstLabels,
+		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,
+		opts.Unit,
 	)
 	return &GaugeVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
@@ -307,5 +309,6 @@ func NewGaugeFunc(opts GaugeOpts, function func() float64) GaugeFunc {
 		opts.Help,
 		nil,
 		opts.ConstLabels,
+		opts.Unit,
 	), 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)
 	}
 

prometheus/go_collector_latest.go

@@ -98,7 +98,7 @@ type goCollector struct {
 	// snapshot is always produced by Collect.
 	mu sync.Mutex
 
-	// Contains all samples that has to retrieved from runtime/metrics (not all of them will be exposed).
+	// Contains all samples that have to be retrieved from runtime/metrics (not all of them will be exposed).
 	sampleBuf []metrics.Sample
 	// sampleMap allows lookup for MemStats metrics and runtime/metrics histograms for exact sums.
 	sampleMap map[string]*metrics.Sample
@@ -210,16 +210,19 @@ func NewGoCollector(opts ...func(o *internal.GoCollectorOptions)) Collector {
 		sampleBuf = append(sampleBuf, metrics.Sample{Name: d.Name})
 		sampleMap[d.Name] = &sampleBuf[len(sampleBuf)-1]
 
+		// Extract unit from the runtime/metrics name (e.g., "/gc/heap/allocs:bytes" -> "bytes")
+		unit := d.Name[strings.IndexRune(d.Name, ':')+1:]
+
 		var m collectorMetric
 		if d.Kind == metrics.KindFloat64Histogram {
 			_, hasSum := opt.RuntimeMetricSumForHist[d.Name]
-			unit := d.Name[strings.IndexRune(d.Name, ':')+1:]
 			m = newBatchHistogram(
 				NewDesc(
 					BuildFQName(namespace, subsystem, name),
 					help,
 					nil,
 					nil,
+					unit,
 				),
 				internal.RuntimeMetricsBucketsForUnit(bucketsMap[d.Name], unit),
 				hasSum,
@@ -230,6 +233,7 @@ func NewGoCollector(opts ...func(o *internal.GoCollectorOptions)) Collector {
 				Subsystem: subsystem,
 				Name:      name,
 				Help:      help,
+				Unit:      unit,
 			},
 			)
 		} else {
@@ -238,6 +242,7 @@ func NewGoCollector(opts ...func(o *internal.GoCollectorOptions)) Collector {
 				Subsystem: subsystem,
 				Name:      name,
 				Help:      help,
+				Unit:      unit,
 			})
 		}
 		metricSet = append(metricSet, m)

prometheus/histogram.go

@@ -378,6 +378,9 @@ type HistogramOpts struct {
 	// string.
 	Help string
 
+	// Unit provides the unit of this Histogram.
+	Unit string
+
 	// ConstLabels are used to attach fixed labels to this metric. Metrics
 	// with the same fully-qualified name must have the same label names in
 	// their ConstLabels.
@@ -527,6 +530,7 @@ func NewHistogram(opts HistogramOpts) Histogram {
 			opts.Help,
 			nil,
 			opts.ConstLabels,
+			opts.Unit,
 		),
 		opts,
 	)
@@ -1190,6 +1194,7 @@ func (v2) NewHistogramVec(opts HistogramVecOpts) *HistogramVec {
 		opts.Help,
 		opts.VariableLabels,
 		opts.ConstLabels,
+		opts.Unit,
 	)
 	return &HistogramVec{
 		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {

prometheus/metric.go

@@ -81,6 +81,9 @@ type Opts struct {
 	// string.
 	Help string
 
+	// Unit provides the unit of this metric as per https://prometheus.io/docs/specs/om
+	Unit string
+
 	// ConstLabels are used to attach fixed labels to this metric. Metrics
 	// with the same fully-qualified name must have the same label names in
 	// their ConstLabels.

prometheus/metric_test.go

@@ -49,7 +49,7 @@ func TestWithExemplarsMetric(t *testing.T) {
 	t.Run("histogram", func(t *testing.T) {
 		// Create a constant histogram from values we got from a 3rd party telemetry system.
 		h := MustNewConstHistogram(
-			NewDesc("http_request_duration_seconds", "A histogram of the HTTP request durations.", nil, nil),
+			NewDesc("http_request_duration_seconds", "A histogram of the HTTP request durations.", nil, nil, "seconds"),
 			4711, 403.34,
 			// Four buckets, but we expect five as the +Inf bucket will be created if we see value outside of those buckets.
 			map[float64]uint64{25: 121, 50: 2403, 100: 3221, 200: 4233},
@@ -99,7 +99,7 @@ func TestWithExemplarsNativeHistogramMetric(t *testing.T) {
 	t.Run("native histogram single exemplar", func(t *testing.T) {
 		// Create a constant histogram from values we got from a 3rd party telemetry system.
 		h := MustNewConstNativeHistogram(
-			NewDesc("http_request_duration_seconds", "A histogram of the HTTP request durations.", nil, nil),
+			NewDesc("http_request_duration_seconds", "A histogram of the HTTP request durations.", nil, nil, "seconds"),
 			10, 12.1, map[int]int64{1: 7, 2: 1, 3: 2}, map[int]int64{}, 0, 2, 0.2, time.Date(
 				2009, 11, 17, 20, 34, 58, 651387237, time.UTC))
 		m := &withExemplarsMetric{Metric: h, exemplars: []*dto.Exemplar{

prometheus/promhttp/http.go

@@ -226,12 +226,17 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 			rsp.Header().Set(contentEncodingHeader, encodingHeader)
 		}
 
-		var enc expfmt.Encoder
+		var (
+			enc     expfmt.Encoder
+			encOpts []expfmt.EncoderOption
+		)
 		if opts.EnableOpenMetricsTextCreatedSamples {
-			enc = expfmt.NewEncoder(w, contentType, expfmt.WithCreatedLines())
-		} else {
-			enc = expfmt.NewEncoder(w, contentType)
+			encOpts = append(encOpts, expfmt.WithCreatedLines())
+		}
+		if opts.EnableOpenMetricsUnit {
+			encOpts = append(encOpts, expfmt.WithUnit())
 		}
+		enc = expfmt.NewEncoder(w, contentType, encOpts...)
 
 		// handleError handles the error according to opts.ErrorHandling
 		// and returns true if we have to abort after the handling.
@@ -461,6 +466,9 @@ type HandlerOpts struct {
 	// Prometheus introduced the feature flag 'created-timestamp-zero-ingestion'
 	// in version 2.50.0 to handle this situation.
 	EnableOpenMetricsTextCreatedSamples bool
+	// EnableOpenMetricsUnit enables unit metadata in the OpenMetrics output format.
+	// This is only applicable when OpenMetrics format is negotiated.
+	EnableOpenMetricsUnit bool
 	// ProcessStartTime allows setting process start timevalue that will be exposed
 	// with "Process-Start-Time-Unix" response header along with the metrics
 	// payload. This allow callers to have efficient transformations to cumulative