cmd/mdatagen: introduce additional metadata for deprecated metrics

.chloggen/fix_mdatagen-deprecated-metrics.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/otlp)
+component: cmd/mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Introduce additional metadata (the version since the deprecation started, and the deprecation reason) for deprecated metrics."
+
+# One or more tracking issues or pull requests related to the change
+issues: [14113]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:  
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

cmd/mdatagen/internal/loader_test.go

@@ -251,7 +251,7 @@ func TestLoadMetadata(t *testing.T) {
 							Enabled:               true,
 							Description:           "Monotonic cumulative sum int metric enabled by default.",
 							ExtendedDocumentation: "The metric will be become optional soon.",
-							Stability:             Stability{Level: component.StabilityLevelDevelopment},
+							Stability:             Stability{Level: component.StabilityLevelDeprecated},
 							Warnings: Warnings{
 								IfEnabledNotSet: "This metric will be disabled by default soon.",
 							},
@@ -263,6 +263,10 @@ func TestLoadMetadata(t *testing.T) {
 							AggregationTemporality: AggregationTemporality{Aggregation: pmetric.AggregationTemporalityCumulative},
 							Mono:                   Mono{Monotonic: true},
 						},
+						Deprecated: &Deprecated{
+							Since: "1.0.0",
+							Note:  "This metric will be removed",
+						},
 					},
 					"reaggregate.metric": {
 						Signal: Signal{
@@ -301,6 +305,10 @@ func TestLoadMetadata(t *testing.T) {
 							},
 							Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "conditional_string_attr"},
 						},
+						Deprecated: &Deprecated{
+							Since: "1.0.0",
+							Note:  "This metric will be removed",
+						},
 						Unit: strPtr("1"),
 						Gauge: &Gauge{
 							MetricValueType: MetricValueType{pmetric.NumberDataPointValueTypeDouble},
@@ -316,6 +324,10 @@ func TestLoadMetadata(t *testing.T) {
 							},
 							Attributes: []AttributeName{"string_attr", "boolean_attr"},
 						},
+						Deprecated: &Deprecated{
+							Since: "1.0.0",
+							Note:  "This metric will be removed",
+						},
 						Unit: strPtr(""),
 						Gauge: &Gauge{
 							MetricValueType: MetricValueType{pmetric.NumberDataPointValueTypeDouble},
@@ -332,6 +344,10 @@ func TestLoadMetadata(t *testing.T) {
 								IfEnabled: "This metric is deprecated and will be removed soon.",
 							},
 						},
+						Deprecated: &Deprecated{
+							Since: "1.0.0",
+							Note:  "This metric will be removed",
+						},
 						Unit: strPtr("s"),
 						Sum: &Sum{
 							MetricValueType:        MetricValueType{pmetric.NumberDataPointValueTypeDouble},
@@ -393,10 +409,16 @@ func TestLoadMetadata(t *testing.T) {
 					Metrics: map[MetricName]Metric{
 						"batch_size_trigger_send": {
 							Signal: Signal{
-								Enabled:     true,
-								Stability:   Stability{Level: component.StabilityLevelDeprecated, From: "v0.110.0"},
+								Enabled: true,
+								Stability: Stability{
+									Level: component.StabilityLevelDeprecated,
+								},
 								Description: "Number of times the batch was sent due to a size trigger",
 							},
+							Deprecated: &Deprecated{
+								Since: "1.5.0",
+								Note:  "This metric will be removed in favor of batch_send_trigger_size",
+							},
 							Unit: strPtr("{times}"),
 							Sum: &Sum{
 								MetricValueType: MetricValueType{pmetric.NumberDataPointValueTypeInt},

cmd/mdatagen/internal/metadata.go

@@ -58,6 +58,11 @@ type Metadata struct {
 	FeatureGates []FeatureGate `mapstructure:"feature_gates"`
 }
 
+type Deprecated struct {
+	Since string `mapstructure:"since"`
+	Note  string `mapstructure:"note"`
+}
+
 func (md Metadata) GetCodeCovComponentID() string {
 	if md.Status.CodeCovComponentID != "" {
 		return md.Status.CodeCovComponentID

cmd/mdatagen/internal/metric.go

@@ -48,6 +48,9 @@ type Metric struct {
 
 	// Override the default prefix for the metric name.
 	Prefix string `mapstructure:"prefix"`
+
+	// Deprecation metadata for deprecated metrics
+	Deprecated *Deprecated `mapstructure:"deprecated,omitempty"`
 }
 
 type Stability struct {
@@ -60,21 +63,45 @@ func (s Stability) String() string {
 		s.Level == component.StabilityLevelStable {
 		return ""
 	}
-	if s.From != "" {
-		return fmt.Sprintf(" [%s since %s]", s.Level.String(), s.From)
-	}
 	return fmt.Sprintf(" [%s]", s.Level.String())
 }
 
+// Unmarshal decodes the stability configuration.
+// NOTE: confmap rejects unknown keys by default.
+// The "from" field cannot be tested via full metadata loading
+// unless WithIgnoreUnused() is used by the caller.
 func (s *Stability) Unmarshal(parser *confmap.Conf) error {
 	if !parser.IsSet("level") {
 		return errors.New("missing required field: `stability.level`")
 	}
-	return parser.Unmarshal(s)
+
+	var level component.StabilityLevel
+	if err := parser.Unmarshal(&struct {
+		Level *component.StabilityLevel `mapstructure:"level"`
+	}{
+		Level: &level,
+	}); err != nil {
+		return err
+	}
+
+	s.Level = level
+
+	if parser.IsSet("from") {
+		if err := parser.Unmarshal(&struct {
+			From *string `mapstructure:"from"`
+		}{From: &s.From}); err != nil {
+			return err
+		}
+	}
+
+	return nil
 }
 
 func (m *Metric) validate(metricName MetricName, semConvVersion string) error {
 	var errs error
+	// TODO: Enforce deprecated metadata requirements once all components
+	// include deprecated fields consistently.
+	// See discussion in PR #14408.
 	if m.Sum == nil && m.Gauge == nil && m.Histogram == nil {
 		errs = errors.Join(errs, errors.New("missing metric type key, "+
 			"one of the following has to be specified: sum, gauge, histogram"))