chore(labels): add more context to labels.MetricName deprecation. (#17590)

Signed-off-by: bwplotka <bwplotka@gmail.com>

model/labels/labels_common.go

@@ -26,7 +26,9 @@ import (
 const (
 	// MetricName is a special label name that represent a metric name.
 	//
-	// Deprecated: Use schema.Metadata structure and its methods.
+	// Deprecated: Instead, consider using schema.Metadata structure and its methods for consistent metadata behaviour with the newly added __type__ and __unit__ labels. Alternatively use github.com/prometheus/common/model.MetricNameLabel for the direct replacement.
+	//
+	// labels package is providing label transport, agnostic to semantic meaning of each label.
 	MetricName = "__name__"
 
 	AlertName   = "alertname"

schema/labels.go

@@ -19,20 +19,10 @@ import (
 	"github.com/prometheus/prometheus/model/labels"
 )
 
-const (
-	// Special label names and selectors for schema.Metadata fields.
-	// They are currently private to ensure __name__, __type__ and __unit__ are used
-	// together and remain extensible in Prometheus. See NewMetadataFromLabels and Metadata
-	// methods for the interactions with the labels package structs.
-	metricName = "__name__"
-	metricType = "__type__"
-	metricUnit = "__unit__"
-)
-
 // IsMetadataLabel returns true if the given label name is a special
 // schema Metadata label.
 func IsMetadataLabel(name string) bool {
-	return name == metricName || name == metricType || name == metricUnit
+	return name == model.MetricNameLabel || name == model.MetricTypeLabel || name == model.MetricUnitLabel
 }
 
 // Metadata represents the core metric schema/metadata elements that:
@@ -79,13 +69,13 @@ type Metadata struct {
 // NewMetadataFromLabels returns the schema metadata from the labels.
 func NewMetadataFromLabels(ls labels.Labels) Metadata {
 	typ := model.MetricTypeUnknown
-	if got := ls.Get(metricType); got != "" {
+	if got := ls.Get(model.MetricTypeLabel); got != "" {
 		typ = model.MetricType(got)
 	}
 	return Metadata{
-		Name: ls.Get(metricName),
+		Name: ls.Get(model.MetricNameLabel),
 		Type: typ,
-		Unit: ls.Get(metricUnit),
+		Unit: ls.Get(model.MetricUnitLabel),
 	}
 }
 
@@ -99,11 +89,11 @@ func (m Metadata) IsTypeEmpty() bool {
 // IsEmptyFor returns true.
 func (m Metadata) IsEmptyFor(labelName string) bool {
 	switch labelName {
-	case metricName:
+	case model.MetricNameLabel:
 		return m.Name == ""
-	case metricType:
+	case model.MetricTypeLabel:
 		return m.IsTypeEmpty()
-	case metricUnit:
+	case model.MetricUnitLabel:
 		return m.Unit == ""
 	default:
 		return true
@@ -114,13 +104,13 @@ func (m Metadata) IsEmptyFor(labelName string) bool {
 // Empty Metadata fields will be ignored (not added).
 func (m Metadata) AddToLabels(b *labels.ScratchBuilder) {
 	if m.Name != "" {
-		b.Add(metricName, m.Name)
+		b.Add(model.MetricNameLabel, m.Name)
 	}
 	if !m.IsTypeEmpty() {
-		b.Add(metricType, string(m.Type))
+		b.Add(model.MetricTypeLabel, string(m.Type))
 	}
 	if m.Unit != "" {
-		b.Add(metricUnit, m.Unit)
+		b.Add(model.MetricUnitLabel, m.Unit)
 	}
 }
 
@@ -128,15 +118,15 @@ func (m Metadata) AddToLabels(b *labels.ScratchBuilder) {
 // It follows the labels.Builder.Set semantics, so empty Metadata fields will
 // remove the corresponding existing labels if they were previously set.
 func (m Metadata) SetToLabels(b *labels.Builder) {
-	b.Set(metricName, m.Name)
+	b.Set(model.MetricNameLabel, m.Name)
 	if m.Type == model.MetricTypeUnknown {
 		// Unknown equals empty semantically, so remove the label on unknown too as per
 		// method signature comment.
-		b.Set(metricType, "")
+		b.Set(model.MetricTypeLabel, "")
 	} else {
-		b.Set(metricType, string(m.Type))
+		b.Set(model.MetricTypeLabel, string(m.Type))
 	}
-	b.Set(metricUnit, m.Unit)
+	b.Set(model.MetricUnitLabel, m.Unit)
 }
 
 // NewIgnoreOverriddenMetadataLabelScratchBuilder creates IgnoreOverriddenMetadataLabelScratchBuilder.

schema/labels_test.go

@@ -50,17 +50,17 @@ func TestMetadata(t *testing.T) {
 			lb.Add("foo", "bar")
 
 			if !tcase.emptyName {
-				lb.Add(metricName, testMeta.Name)
+				lb.Add(model.MetricNameLabel, testMeta.Name)
 				expectedMeta.Name = testMeta.Name
 			}
 			if !tcase.emptyType {
-				lb.Add(metricType, string(testMeta.Type))
+				lb.Add(model.MetricTypeLabel, string(testMeta.Type))
 				expectedMeta.Type = testMeta.Type
 			} else {
 				expectedMeta.Type = model.MetricTypeUnknown
 			}
 			if !tcase.emptyUnit {
-				lb.Add(metricUnit, testMeta.Unit)
+				lb.Add(model.MetricUnitLabel, testMeta.Unit)
 				expectedMeta.Unit = testMeta.Unit
 			}
 			lb.Sort()
@@ -75,10 +75,10 @@ func TestMetadata(t *testing.T) {
 			}
 			{
 				// Empty methods.
-				require.Equal(t, tcase.emptyName, expectedMeta.IsEmptyFor(metricName))
+				require.Equal(t, tcase.emptyName, expectedMeta.IsEmptyFor(model.MetricNameLabel))
-				require.Equal(t, tcase.emptyType, expectedMeta.IsEmptyFor(metricType))
+				require.Equal(t, tcase.emptyType, expectedMeta.IsEmptyFor(model.MetricTypeLabel))
 				require.Equal(t, tcase.emptyType, expectedMeta.IsTypeEmpty())
-				require.Equal(t, tcase.emptyUnit, expectedMeta.IsEmptyFor(metricUnit))
+				require.Equal(t, tcase.emptyUnit, expectedMeta.IsEmptyFor(model.MetricUnitLabel))
 			}
 			{
 				// From Metadata to labels for various builders.
@@ -100,7 +100,7 @@ func TestIgnoreOverriddenMetadataLabelsScratchBuilder(t *testing.T) {
 	// PROM-39 specifies that metadata labels should be sourced primarily from the metadata structures.
 	// However, the original labels should be preserved IF the metadata structure does not set or support certain information.
 	// Test those cases with common label interactions.
-	incomingLabels := labels.FromStrings(metricName, "different_name", metricType, string(model.MetricTypeSummary), metricUnit, "MB", "foo", "bar")
+	incomingLabels := labels.FromStrings(model.MetricNameLabel, "different_name", model.MetricTypeLabel, string(model.MetricTypeSummary), model.MetricUnitLabel, "MB", "foo", "bar")
 	for _, tcase := range []struct {
 		highPrioMeta   Metadata
 		expectedLabels labels.Labels
@@ -114,21 +114,21 @@ func TestIgnoreOverriddenMetadataLabelsScratchBuilder(t *testing.T) {
 				Type: model.MetricTypeCounter,
 				Unit: "seconds",
 			},
-			expectedLabels: labels.FromStrings(metricName, "metric_total", metricType, string(model.MetricTypeCounter), metricUnit, "seconds", "foo", "bar"),
+			expectedLabels: labels.FromStrings(model.MetricNameLabel, "metric_total", model.MetricTypeLabel, string(model.MetricTypeCounter), model.MetricUnitLabel, "seconds", "foo", "bar"),
 		},
 		{
 			highPrioMeta: Metadata{
 				Name: "metric_total",
 				Type: model.MetricTypeCounter,
 			},
-			expectedLabels: labels.FromStrings(metricName, "metric_total", metricType, string(model.MetricTypeCounter), metricUnit, "MB", "foo", "bar"),
+			expectedLabels: labels.FromStrings(model.MetricNameLabel, "metric_total", model.MetricTypeLabel, string(model.MetricTypeCounter), model.MetricUnitLabel, "MB", "foo", "bar"),
 		},
 		{
 			highPrioMeta: Metadata{
 				Type: model.MetricTypeCounter,
 				Unit: "seconds",
 			},
-			expectedLabels: labels.FromStrings(metricName, "different_name", metricType, string(model.MetricTypeCounter), metricUnit, "seconds", "foo", "bar"),
+			expectedLabels: labels.FromStrings(model.MetricNameLabel, "different_name", model.MetricTypeLabel, string(model.MetricTypeCounter), model.MetricUnitLabel, "seconds", "foo", "bar"),
 		},
 		{
 			highPrioMeta: Metadata{
@@ -136,7 +136,7 @@ func TestIgnoreOverriddenMetadataLabelsScratchBuilder(t *testing.T) {
 				Type: model.MetricTypeUnknown,
 				Unit: "seconds",
 			},
-			expectedLabels: labels.FromStrings(metricName, "metric_total", metricType, string(model.MetricTypeSummary), metricUnit, "seconds", "foo", "bar"),
+			expectedLabels: labels.FromStrings(model.MetricNameLabel, "metric_total", model.MetricTypeLabel, string(model.MetricTypeSummary), model.MetricUnitLabel, "seconds", "foo", "bar"),
 		},
 	} {
 		t.Run(fmt.Sprintf("meta=%#v", tcase.highPrioMeta), func(t *testing.T) {