feature: type-and-unit-labels (extended MetricIdentity)

Experimental implementation of prometheus/proposals#39

Previous (unmerged) experiments:
* prometheus/prometheus@main...dashpole:prometheus:type_and_unit_labels
* prometheus#16025

Signed-off-by: bwplotka <[email protected]>

Author: bwplotka

cmd/prometheus/main.go

@@ -283,19 +283,9 @@ func (c *flagConfig) setFeatureListOptions(logger *slog.Logger) error {
 			case "otlp-deltatocumulative":
 				c.web.ConvertOTLPDelta = true
 				logger.Info("Converting delta OTLP metrics to cumulative")
-			case "otlp-native-delta-ingestion":
-				// Experimental OTLP native delta ingestion.
-				// This currently just stores the raw delta value as-is with unknown metric type. Better typing and
-				// type-aware functions may come later.
-				// See proposal: https://github.com/prometheus/proposals/pull/48
-				c.web.NativeOTLPDeltaIngestion = true
-				logger.Info("Enabling native ingestion of delta OTLP metrics, storing the raw sample values without conversion. WARNING: Delta support is in an early stage of development. The ingestion and querying process is likely to change over time.")
 			case "type-and-unit-labels":
 				c.scrape.EnableTypeAndUnitLabels = true
 				logger.Info("Experimental type and unit labels enabled")
-			case "use-uncached-io":
-				c.tsdb.UseUncachedIO = true
-				logger.Info("Experimental Uncached IO is enabled.")
 			default:
 				logger.Warn("Unknown option for --enable-feature", "option", o)
 			}

docs/feature_flags.md

@@ -217,70 +217,23 @@ Examples of equivalent durations:
 
 [d2c]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/deltatocumulativeprocessor
 
-## OTLP Native Delta Support
-
-`--enable-feature=otlp-native-delta-ingestion`
-
-When enabled, allows for the native ingestion of delta OTLP metrics, storing the raw sample values without conversion. This cannot be enabled in conjunction with `otlp-deltatocumulative`.
-
-Currently, the StartTimeUnixNano field is ignored, and deltas are given the unknown metric metadata type.
-
-Delta support is in a very early stage of development and the ingestion and querying process my change over time. For the open proposal see [prometheus/proposals#48](https://github.com/prometheus/proposals/pull/48).
-
-### Querying
-
-We encourage users to experiment with deltas and existing PromQL functions; we will collect feedback and likely build features to improve the experience around querying deltas.
-
-Note that standard PromQL counter functions like `rate()` and `increase()` are designed for cumulative metrics and will produce incorrect results when used with delta metrics. This may change in the future, but for now, to get similar results for delta metrics, you need `sum_over_time()`:
-
-* `sum_over_time(delta_metric[<range>])`: Calculates the sum of delta values over the specified time range.
-* `sum_over_time(delta_metric[<range>]) / <range>`: Calculates the per-second rate of the delta metric.
-
-These may not work well if the `<range>` is not a multiple of the collection interval of the metric. For example, if you do `sum_over_time(delta_metric[1m]) / 1m` range query (with a 1m step), but the collection interval of a metric is 10m, the graph will show a single point every 10 minutes with a high rate value, rather than 10 points with a lower, constant value.
-
-### Current gotchas
-
-* If delta metrics are exposed via [federation](https://prometheus.io/docs/prometheus/latest/federation/), data can be incorrectly collected if the ingestion interval is not the same as the scrape interval for the federated endpoint.
-
-* It is difficult to figure out whether a metric has delta or cumulative temporality, since there's no indication of temporality in metric names or labels. For now, if you are ingesting a mix of delta and cumulative metrics we advise you to explicitly add your own labels to distinguish them. In the future, we plan to introduce type labels to consistently distinguish metric types and potentially make PromQL functions type-aware (e.g. providing warnings when cumulative-only functions are used with delta metrics).
-
-* If there are multiple samples being ingested at the same timestamp, only one of the points is kept - the samples are **not** summed together (this is how Prometheus works in general - duplicate timestamp samples are rejected). Any aggregation will have to be done before sending samples to Prometheus.
-
 ## Type and Unit Labels
 
 `--enable-feature=type-and-unit-labels`
 
-When enabled, Prometheus will start injecting additional, reserved `__type__`
-and `__unit__` labels as designed in the [PROM-39 proposal](https://github.com/prometheus/proposals/pull/39).
-
-Those labels are sourced from the metadata structured of the existing scrape and ingestion formats
-like OpenMetrics Text, Prometheus Text, Prometheus Proto, Remote Write 2 and OTLP. All the user provided labels with
-`__type__` and `__unit__` will be overridden.
-
-PromQL layer will handle those labels the same way __name__ is handled, e.g. dropped
-on certain operations like `-` or `+` and affected by `promql-delayed-name-removal` feature.
+When enabled, Prometheus will start injecting additional, special `__type__`
+and `__unit__` labels that extends the existing `__name__` metric identity.
 
-This feature enables important metadata information to be accessible directly with samples and PromQL layer.
- 
-It's especially useful for users who:
+Those labels are injected from the metadata parts of OpenMetrics and other scrape expositions
+, as well as Remote Write 2.0 and OTLP receive. All user provided labels with
+`__type__` and `__unit__` will be dropped or overridden.
 
+This is useful for users who:
 * Want to be able to select metrics based on type or unit.
 * Want to handle cases of series with the same metric name and different type and units.
-  e.g. native histogram migrations or OpenTelemetry metrics from OTLP endpoint, without translation.
+e.g. native histogram migrations or OpenTelemetry metrics from OTLP endpoint, without translation.
 
-In future more [work is planned](https://github.com/prometheus/prometheus/issues/16610) that will depend on this e.g. rich PromQL UX that helps
+In future more work is planned that will depend on this e.g. rich PromQL UX that helps 
 when wrong types are used on wrong functions, automatic renames, delta types and more.
 
-## Use Uncached IO
-
-`--enable-feature=use-uncached-io`
-
-Experimental and only available on Linux.
-
-When enabled, it makes chunks writing bypass the page cache. Its primary
-goal is to reduce confusion around page‐cache behavior and to prevent over‑allocation of
-memory in response to misleading cache growth.
-
-This is currently implemented using direct I/O.
-
-For more details, see the [proposal](https://github.com/prometheus/proposals/pull/45).
+See [proposal](https://github.com/prometheus/proposals/pull/39)

model/labels/labels.go

@@ -364,6 +364,25 @@ func (ls Labels) DropReserved(shouldDropFn func(name string) bool) Labels {
 	return ls
 }
 
+// DropMetricIdentity is like DropMetricName but drops all parts of MetricIdentity.
+func (ls Labels) DropMetricIdentity() Labels {
+	rm := 0
+	for i, l := range ls {
+		if IsMetricIdentityLabel(l.Name) {
+			i := i - rm // Offsetting after removals.
+			if i == 0 { // Make common case fast with no allocations.
+				ls = ls[1:]
+			} else {
+				// Avoid modifying original Labels - use [:i:i] so that left slice would not
+				// have any spare capacity and append would have to allocate a new slice for the result.
+				ls = append(ls[:i:i], ls[i+1:]...)
+			}
+			rm++
+		}
+	}
+	return ls
+}
+
 // InternStrings calls intern on every string value inside ls, replacing them with what it returns.
 func (ls *Labels) InternStrings(intern func(string) string) {
 	for i, l := range *ls {

model/labels/labels_common.go

@@ -18,30 +18,138 @@ import (
 	"encoding/json"
 	"slices"
 	"strconv"
+	"strings"
 	"unsafe"
 
 	"github.com/prometheus/common/model"
 )
 
 const (
-	// MetricName is a special label name that represent a metric name.
-	// Deprecated: Use schema.Metadata structure and its methods.
+	// MetricName is a special label name and selector for MetricIdentity.Name.
 	MetricName = "__name__"
 
-	AlertName   = "alertname"
-	BucketLabel = "le"
+	// metricType is a special label name and selector for MetricIdentity.Type.
+	// Private to ensure __name__, __type__ and __unit__ are used together
+	// and remain extensible in Prometheus. See Labels.MetricIdentity,
+	// Builder.SetMetricIdentity and ScratchBuilder.AddMetricIdentity for access.
+	metricType = "__type__"
+	// MetricUnit is a special label name and selector for MetricIdentity.Unit,
+	// which in the past used to be stored in metadata.
+	// Private to ensure __name__, __type__ and __unit__ are used together
+	// and remain extensible in Prometheus. See Labels.MetricIdentity,
+	// Builder.SetMetricIdentity and ScratchBuilder.AddMetricIdentity for access.
+	metricUnit = "__unit__"
+
+	AlertName    = "alertname"
+	BucketLabel  = "le"
+	InstanceName = "instance"
 
 	labelSep = '\xfe' // Used at beginning of `Bytes` return.
 	sep      = '\xff' // Used between labels in `Bytes` and `Hash`.
 )
 
+// IsMetricIdentityLabel returns true if the given label name is a special
+// metric identity label.
+func IsMetricIdentityLabel(name string) bool {
+	return name == MetricName || name == metricType || name == metricUnit
+}
+
+// MetricIdentity represents extended metric identity parts beyond the metric name.
+// Each "time series" is identifiable by MetricIdentity and other labels e.g. job.
+type MetricIdentity struct {
+	// Name represents metric name (not always the same as metric family, until we
+	// have native, structured metric representation for all types).
+	// Empty means nameless metric (e.g. result of the PromQL function).
+	Name string
+	// Type, empty ("") is equivalent to model.UnknownMetricType.
+	// In the past Prometheus used to be stored it n metadata.
+	Type model.MetricType
+	// Unit of the metric, regardless if encoded in the metric name. Empty means
+	// unitless metric (e.g. result of the PromQL function).
+	// In the past Prometheus used to be stored it n metadata.
+	Unit string
+}
+
+func (m MetricIdentity) String() string {
+	b := strings.Builder{}
+	b.WriteString(m.Name)
+	if m.Unit != "" {
+		b.WriteString("~")
+		b.WriteString(m.Unit)
+	}
+	if m.Type != "" && m.Type != model.MetricTypeUnknown {
+		b.WriteString(".")
+		b.WriteString(string(m.Type))
+	}
+	return b.String()
+}
+
 var seps = []byte{sep} // Used with Hash, which has no WriteByte method.
 
 // Label is a key/value a pair of strings.
 type Label struct {
 	Name, Value string
 }
 
+// MetricIdentity returns the metric identity parts.
+func (ls Labels) MetricIdentity() MetricIdentity {
+	typ := model.MetricTypeUnknown
+	if got := ls.Get(metricType); got != "" {
+		typ = model.MetricType(got)
+	}
+	return MetricIdentity{
+		Name: ls.Get(MetricName),
+		Type: typ,
+		Unit: ls.Get(metricUnit),
+	}
+}
+
+// SetMetricIdentity injects metric identity parts into labels.
+// Empty fields of the given MetricIdentity (or unknown metric type), will
+// cause removal of the existing part labels.
+func (b *Builder) SetMetricIdentity(mid MetricIdentity) *Builder {
+	b.Set(MetricName, mid.Name)
+	if mid.Type == model.MetricTypeUnknown {
+		// Unknown equals empty semantically, so remove the label on unknown too as per
+		// method signature comment.
+		mid.Type = ""
+	}
+	b.Set(metricType, string(mid.Type))
+	b.Set(metricUnit, mid.Unit)
+	return b
+}
+
+// IgnoreIdentityLabelsScratchBuilder is a wrapper over scratch builder
+// that ignores subsequent additions of special metric identity labels.
+type IgnoreIdentityLabelsScratchBuilder struct {
+	*ScratchBuilder
+}
+
+// Add a name/value pair, unless it's a special metric identity label e.g. __name__, __type__, __unit__.
+// Note if you Add the same name twice you will get a duplicate label, which is invalid.
+func (b IgnoreIdentityLabelsScratchBuilder) Add(name, value string) {
+	if IsMetricIdentityLabel(name) {
+		return
+	}
+	b.ScratchBuilder.Add(name, value)
+}
+
+// AddMetricIdentity adds metric identity parts into labels.
+// Empty fields of the given MetricIdentity (or unknown metric type), will be ignored.
+//
+//nolint:revive // unexported type
+func (b *ScratchBuilder) AddMetricIdentity(mid MetricIdentity) {
+	if mid.Name != "" {
+		b.Add(MetricName, mid.Name)
+	}
+	if mid.Type != "" && mid.Type != model.MetricTypeUnknown {
+		b.Add(metricType, string(mid.Type))
+	}
+	if mid.Unit != "" {
+		b.Add(metricUnit, mid.Unit)
+	}
+}
+
 func (ls Labels) String() string {
 	var bytea [1024]byte // On stack to avoid memory allocation while building the output.
 	b := bytes.NewBuffer(bytea[:0])

model/labels/labels_dedupelabels.go

@@ -554,8 +554,8 @@ func (ls Labels) ReleaseStrings(release func(string)) {
 	// TODO: remove these calls as there is nothing to do.
 }
 
-// DropMetricName returns Labels with the "__name__" removed.
-// Deprecated: Use DropReserved instead.
+// DropMetricName returns Labels with "__name__" removed.
+// Deprecate: Use DropMetric instead to handle type and unit correctly.
 func (ls Labels) DropMetricName() Labels {
 	return ls.DropReserved(func(n string) bool { return n == MetricName })
 }
@@ -581,6 +581,27 @@ func (ls Labels) DropReserved(shouldDropFn func(name string) bool) Labels {
 	return ls
 }
 
+// DropMetricIdentity is like DropMetricName but drops all parts of MetricIdentity.
+func (ls Labels) DropMetricIdentity() Labels {
+	for i := 0; i < len(ls.data); {
+		lName, i2 := decodeString(ls.syms, ls.data, i)
+		_, i2 = decodeVarint(ls.data, i2)
+		if lName[0] > '_' { // Stop looking if we've gone past special labels.
+			break
+		}
+		if IsMetricIdentityLabel(lName) {
+			if i == 0 { // Make common case fast with no allocations.
+				ls.data = ls.data[i2:]
+			} else {
+				ls.data = ls.data[:i] + ls.data[i2:]
+			}
+			continue
+		}
+		i = i2
+	}
+	return ls
+}
+
 // Builder allows modifying Labels.
 type Builder struct {
 	syms *SymbolTable

model/labels/labels_stringlabels.go

@@ -441,6 +441,28 @@ func (ls Labels) DropReserved(shouldDropFn func(name string) bool) Labels {
 	return ls
 }
 
+// DropMetricIdentity is like DropMetricName but drops all parts of MetricIdentity.
+func (ls Labels) DropMetricIdentity() Labels {
+	for i := 0; i < len(ls.data); {
+		lName, i2 := decodeString(ls.data, i)
+		size, i2 := decodeSize(ls.data, i2)
+		i2 += size
+		if lName[0] > '_' { // Stop looking if we've gone past special labels.
+			break
+		}
+		if IsMetricIdentityLabel(lName) {
+			if i == 0 { // Make common case fast with no allocations.
+				ls.data = ls.data[i2:]
+			} else {
+				ls.data = ls.data[:i] + ls.data[i2:]
+			}
+			continue
+		}
+		i = i2
+	}
+	return ls
+}
+
 // InternStrings is a no-op because it would only save when the whole set of labels is identical.
 func (ls *Labels) InternStrings(_ func(string) string) {
 }

model/labels/labels_test.go

@@ -528,17 +528,15 @@ func TestLabels_DropMetricName(t *testing.T) {
 	require.True(t, Equal(original, check))
 }
 
-func TestLabels_DropReserved(t *testing.T) {
-	shouldDropFn := func(n string) bool {
-		return n == MetricName || n == "__something__"
-	}
-	require.True(t, Equal(FromStrings("aaa", "111", "bbb", "222"), FromStrings("aaa", "111", "bbb", "222").DropReserved(shouldDropFn)))
-	require.True(t, Equal(FromStrings("aaa", "111"), FromStrings(MetricName, "myname", "aaa", "111").DropReserved(shouldDropFn)))
-	require.True(t, Equal(FromStrings("aaa", "111"), FromStrings(MetricName, "myname", "__something__", string(model.MetricTypeCounter), "aaa", "111").DropReserved(shouldDropFn)))
+func TestLabels_DropMetricIdentity(t *testing.T) {
+	require.True(t, Equal(FromStrings("aaa", "111", "bbb", "222"), FromStrings("aaa", "111", "bbb", "222").DropMetricIdentity()))
+	require.True(t, Equal(FromStrings("aaa", "111"), FromStrings(MetricName, "myname", "aaa", "111").DropMetricIdentity()))
+	require.True(t, Equal(FromStrings("aaa", "111"), FromStrings(MetricName, "myname", metricType, string(model.MetricTypeCounter), "aaa", "111").DropMetricIdentity()))
+	require.True(t, Equal(FromStrings("aaa", "111"), FromStrings(MetricName, "myname", metricType, string(model.MetricTypeCounter), metricUnit, "seconds", "aaa", "111").DropMetricIdentity()))
 
 	original := FromStrings("__aaa__", "111", MetricName, "myname", "bbb", "222")
 	check := original.Copy()
-	require.True(t, Equal(FromStrings("__aaa__", "111", "bbb", "222"), check.DropReserved(shouldDropFn)))
+	require.True(t, Equal(FromStrings("__aaa__", "111", "bbb", "222"), check.DropMetricIdentity()))
 	require.True(t, Equal(original, check))
 }
 

model/textparse/openmetricsparse.go

@@ -219,6 +219,15 @@ func (p *OpenMetricsParser) Labels(l *labels.Labels) {
 
 	p.builder.Reset()
 	metricName := unreplace(s[p.offsets[0]-p.start : p.offsets[1]-p.start])
+	if p.enableTypeAndUnitLabels {
+		p.builder.AddMetricIdentity(labels.MetricIdentity{
+			Name: metricName,
+			Type: p.mtype,
+			Unit: p.unit,
+		})
+	} else {
+		p.builder.Add(labels.MetricName, metricName)
+	}
 
 	m := schema.Metadata{
 		Name: metricName,
@@ -234,8 +243,8 @@ func (p *OpenMetricsParser) Labels(l *labels.Labels) {
 		a := p.offsets[i] - p.start
 		b := p.offsets[i+1] - p.start
 		label := unreplace(s[a:b])
-		if p.enableTypeAndUnitLabels && !m.IsEmptyFor(label) {
-			// Dropping user provided metadata labels, if found in the OM metadata.
+		if p.enableTypeAndUnitLabels && labels.IsMetricIdentityLabel(label) {
+			// Dropping user provided id labels if needed.
 			continue
 		}
 		c := p.offsets[i+2] - p.start