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,24 @@ type Metadata struct {
 	FeatureGates []FeatureGate `mapstructure:"feature_gates"`
 }
 
+type Deprecated struct {
+	Since string `mapstructure:"since"`
+	Note  string `mapstructure:"note"`
+}
+
+func (d *Deprecated) validate() error {
+	if strings.TrimSpace(d.Since) == "" {
+		return errors.New("deprecated.since must be set")
+	}
+
+	// NOTE: note is optional, but if present, it must not be empty
+	if d.Note != "" && strings.TrimSpace(d.Note) == "" {
+		return errors.New("deprecated.note must not be empty")
+	}
+
+	return nil
+}
+
 func (md Metadata) GetCodeCovComponentID() string {
 	if md.Status.CodeCovComponentID != "" {
 		return md.Status.CodeCovComponentID

cmd/mdatagen/internal/metric.go

@@ -48,33 +48,64 @@ 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 {
 	Level component.StabilityLevel `mapstructure:"level"`
-	From  string                   `mapstructure:"from"`
+	// Deprecated: [0.144.0] Replaced with `deprecated.since`.
+	From string `mapstructure:"from"`
 }
 
 func (s Stability) String() string {
 	if s.Level == component.StabilityLevelUndefined ||
 		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
+
+	if m.Deprecated != nil {
+		if err := m.Deprecated.validate(); err != nil {
+			errs = errors.Join(errs, err)
+		}
+	}
+
 	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"))

cmd/mdatagen/internal/metric_test.go

@@ -7,7 +7,10 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/confmap"
 	"go.opentelemetry.io/collector/pdata/pmetric"
 )
 
@@ -38,3 +41,66 @@ func TestMetricData(t *testing.T) {
 		assert.Equal(t, arg.wantAsync, arg.metricData.IsAsync())
 	}
 }
+
+func TestStability_String(t *testing.T) {
+	tests := []struct {
+		name      string
+		stability Stability
+		want      string
+	}{
+		{
+			name: "undefined level",
+			stability: Stability{
+				Level: component.StabilityLevelUndefined,
+			},
+			want: "",
+		},
+		{
+			name: "stable level",
+			stability: Stability{
+				Level: component.StabilityLevelStable,
+			},
+			want: "",
+		},
+		{
+			name: "beta level",
+			stability: Stability{
+				Level: component.StabilityLevelBeta,
+			},
+			want: " [Beta]",
+		},
+		{
+			name: "alpha level",
+			stability: Stability{
+				Level: component.StabilityLevelAlpha,
+			},
+			want: " [Alpha]",
+		},
+		{
+			name: "deprecated level",
+			stability: Stability{
+				Level: component.StabilityLevelDeprecated,
+			},
+			want: " [Deprecated]",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := tt.stability.String()
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestStability_Unmarshal_WithoutFrom(t *testing.T) {
+	parser := confmap.NewFromStringMap(map[string]any{
+		"level": "beta",
+	})
+
+	var s Stability
+	err := s.Unmarshal(parser)
+	require.NoError(t, err)
+	assert.Equal(t, component.StabilityLevelBeta, s.Level)
+	assert.Empty(t, s.From)
+}

cmd/mdatagen/internal/sampleconnector/documentation.md

@@ -40,7 +40,9 @@ The metric will be removed soon.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
-| s | Sum | Double | Delta | false | Deprecated |
+| s | Sum | Double | Delta | false | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 ### metric.input_type
 
@@ -91,7 +93,9 @@ metrics:
 
 | Unit | Metric Type | Value Type | Stability |
 | ---- | ----------- | ---------- | --------- |
-| 1 | Gauge | Double | Deprecated |
+| 1 | Gauge | Double | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 #### Attributes
 
@@ -107,7 +111,9 @@ metrics:
 
 | Unit | Metric Type | Value Type | Stability |
 | ---- | ----------- | ---------- | --------- |
-|  | Gauge | Double | Deprecated |
+|  | Gauge | Double | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 #### Attributes
 

cmd/mdatagen/internal/sampleconnector/metadata.yaml

@@ -133,6 +133,9 @@ metrics:
     extended_documentation: The metric will be removed soon.
     stability:
       level: deprecated
+    deprecated:
+      since: "1.0.0"
+      note: "This metric will be removed"
     unit: s
     sum:
       value_type: double
@@ -160,6 +163,9 @@ metrics:
     description: "[DEPRECATED] Gauge double metric disabled by default."
     stability:
       level: deprecated
+    deprecated:
+       since: "1.0.0"
+       note: "This metric will be removed"
     unit: "1"
     gauge:
       value_type: double
@@ -172,6 +178,9 @@ metrics:
     description: "[DEPRECATED] Gauge double metric disabled by default."
     stability:
       level: deprecated
+    deprecated:
+      since: "1.0.0"
+      note: "This metric will be removed"
     unit: ""
     gauge:
       value_type: double

cmd/mdatagen/internal/samplereceiver/documentation.md

@@ -20,7 +20,9 @@ The metric will be become optional soon.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
-| s | Sum | Int | Cumulative | true | Development |
+| s | Sum | Int | Cumulative | true | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 #### Attributes
 
@@ -43,7 +45,9 @@ The metric will be removed soon.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
-| s | Sum | Double | Delta | false | Deprecated |
+| s | Sum | Double | Delta | false | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 ### metric.input_type
 
@@ -104,7 +108,9 @@ metrics:
 
 | Unit | Metric Type | Value Type | Stability |
 | ---- | ----------- | ---------- | --------- |
-| 1 | Gauge | Double | Deprecated |
+| 1 | Gauge | Double | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 #### Attributes
 
@@ -121,7 +127,9 @@ metrics:
 
 | Unit | Metric Type | Value Type | Stability |
 | ---- | ----------- | ---------- | --------- |
-|  | Gauge | Double | Deprecated |
+|  | Gauge | Double | Deprecated since 1.0.0 |
+
+**Deprecation note**: This metric will be removed
 
 #### Attributes
 
@@ -217,11 +225,16 @@ The following telemetry is emitted by this component.
 
 ### otelcol_batch_size_trigger_send
 
-Number of times the batch was sent due to a size trigger [Deprecated since v0.110.0]
+Number of times the batch was sent due to a size trigger [Deprecated]
+
+> **Deprecated since 1.5.0**
+> This metric will be removed in favor of batch_send_trigger_size
 
 | Unit | Metric Type | Value Type | Monotonic | Stability |
 | ---- | ----------- | ---------- | --------- | --------- |
-| {times} | Sum | Int | true | Deprecated |
+| {times} | Sum | Int | true | Deprecated since 1.5.0 |
+
+**Deprecation note**: This metric will be removed in favor of batch_send_trigger_size
 
 ### otelcol_process_runtime_total_alloc_bytes