Mdatagen: flatten the metric stability level

.chloggen/mdatagen-flatten-metric-stability.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: breaking
+
+# 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: Flatten the metric stability field
+
+# 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: So we better match the weaver schema. Additional deprecation data can be set within the `deprecated` field.
+
+# 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: [api]

cmd/mdatagen/internal/loader_test.go

@@ -259,7 +259,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.StabilityLevelDeprecated},
+							Stability:             component.StabilityLevelDeprecated,
 							Warnings: Warnings{
 								IfEnabledNotSet: "This metric will be disabled by default soon.",
 							},
@@ -280,7 +280,7 @@ func TestLoadMetadata(t *testing.T) {
 						Signal: Signal{
 							Enabled:     true,
 							Description: "Metric for testing spatial reaggregation",
-							Stability:   Stability{Level: component.StabilityLevelBeta},
+							Stability:   component.StabilityLevelBeta,
 							Attributes:  []AttributeName{"string_attr", "boolean_attr"},
 						},
 						Unit: strPtr("1"),
@@ -292,7 +292,7 @@ func TestLoadMetadata(t *testing.T) {
 						Signal: Signal{
 							Enabled:     true,
 							Description: "Metric for testing spatial reaggregation with required attributes",
-							Stability:   Stability{Level: component.StabilityLevelBeta},
+							Stability:   component.StabilityLevelBeta,
 							Attributes:  []AttributeName{"required_string_attr", "string_attr", "boolean_attr"},
 						},
 						Unit: strPtr("1"),
@@ -303,7 +303,7 @@ func TestLoadMetadata(t *testing.T) {
 					"system.cpu.time": {
 						Signal: Signal{
 							Enabled:               true,
-							Stability:             Stability{Level: component.StabilityLevelBeta},
+							Stability:             component.StabilityLevelBeta,
 							SemanticConvention:    &SemanticConvention{SemanticConventionRef: "https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/system/system-metrics.md#metric-systemcputime"},
 							Description:           "Monotonic cumulative sum int metric enabled by default.",
 							ExtendedDocumentation: "The metric will be become optional soon.",
@@ -319,7 +319,7 @@ func TestLoadMetadata(t *testing.T) {
 						Signal: Signal{
 							Enabled:     false,
 							Description: "[DEPRECATED] Gauge double metric disabled by default.",
-							Stability:   Stability{Level: component.StabilityLevelDeprecated},
+							Stability:   component.StabilityLevelDeprecated,
 							Warnings: Warnings{
 								IfConfigured: "This metric is deprecated and will be removed soon.",
 							},
@@ -338,7 +338,7 @@ func TestLoadMetadata(t *testing.T) {
 						Signal: Signal{
 							Enabled:     false,
 							Description: "[DEPRECATED] Gauge double metric disabled by default.",
-							Stability:   Stability{Level: component.StabilityLevelDeprecated},
+							Stability:   component.StabilityLevelDeprecated,
 							Warnings: Warnings{
 								IfConfigured: "This metric is deprecated and will be removed soon.",
 							},
@@ -359,7 +359,7 @@ func TestLoadMetadata(t *testing.T) {
 							Enabled:               true,
 							Description:           "[DEPRECATED] Non-monotonic delta sum double metric enabled by default.",
 							ExtendedDocumentation: "The metric will be removed soon.",
-							Stability:             Stability{Level: component.StabilityLevelDeprecated},
+							Stability:             component.StabilityLevelDeprecated,
 							Warnings: Warnings{
 								IfEnabled: "This metric is deprecated and will be removed soon.",
 							},
@@ -379,7 +379,7 @@ func TestLoadMetadata(t *testing.T) {
 						Signal: Signal{
 							Enabled:     true,
 							Description: "Monotonic cumulative sum int metric with string input_type enabled by default.",
-							Stability:   Stability{Level: component.StabilityLevelDevelopment},
+							Stability:   component.StabilityLevelDevelopment,
 							Attributes:  []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr"},
 						},
 						Unit: strPtr("s"),
@@ -429,10 +429,8 @@ func TestLoadMetadata(t *testing.T) {
 					Metrics: map[MetricName]Metric{
 						"batch_size_trigger_send": {
 							Signal: Signal{
-								Enabled: true,
-								Stability: Stability{
-									Level: component.StabilityLevelDeprecated,
-								},
+								Enabled:     true,
+								Stability:   component.StabilityLevelDeprecated,
 								Description: "Number of times the batch was sent due to a size trigger",
 							},
 							Deprecated: &Deprecated{
@@ -448,7 +446,7 @@ func TestLoadMetadata(t *testing.T) {
 						"request_duration": {
 							Signal: Signal{
 								Enabled:     true,
-								Stability:   Stability{Level: component.StabilityLevelAlpha},
+								Stability:   component.StabilityLevelAlpha,
 								Description: "Duration of request",
 							},
 							Unit: strPtr("s"),
@@ -460,7 +458,7 @@ func TestLoadMetadata(t *testing.T) {
 						"process_runtime_total_alloc_bytes": {
 							Signal: Signal{
 								Enabled:     true,
-								Stability:   Stability{Level: component.StabilityLevelStable},
+								Stability:   component.StabilityLevelStable,
 								Description: "Cumulative bytes allocated for heap objects (see 'go doc runtime.MemStats.TotalAlloc')",
 							},
 							Unit: strPtr("By"),
@@ -475,7 +473,7 @@ func TestLoadMetadata(t *testing.T) {
 						"queue_length": {
 							Signal: Signal{
 								Enabled:               true,
-								Stability:             Stability{Level: component.StabilityLevelAlpha},
+								Stability:             component.StabilityLevelAlpha,
 								Description:           "This metric is optional and therefore not initialized in NewTelemetryBuilder.",
 								ExtendedDocumentation: "For example this metric only exists if feature A is enabled.",
 							},
@@ -492,7 +490,7 @@ func TestLoadMetadata(t *testing.T) {
 							Signal: Signal{
 								Enabled:     true,
 								Description: "Queue capacity - sync gauge example.",
-								Stability:   Stability{Level: component.StabilityLevelDevelopment},
+								Stability:   component.StabilityLevelDevelopment,
 							},
 							Unit: strPtr("{items}"),
 							Gauge: &Gauge{
@@ -603,7 +601,7 @@ func TestLoadMetadata(t *testing.T) {
 		{
 			name:    "testdata/invalid_metric_stability.yaml",
 			want:    Metadata{},
-			wantErr: "decoding failed due to the following error(s):\n\n'metrics[default.metric]' decoding failed due to the following error(s):\n\n'stability' decoding failed due to the following error(s):\n\n'level' unsupported stability level: \"development42\"",
+			wantErr: "decoding failed due to the following error(s):\n\n'metrics[default.metric]' decoding failed due to the following error(s):\n\n'stability' unsupported stability level: \"development42\"",
 		},
 		{
 			name:    "testdata/invalid_metric_semconvref.yaml",
@@ -613,7 +611,12 @@ func TestLoadMetadata(t *testing.T) {
 		{
 			name:    "testdata/no_metric_stability.yaml",
 			want:    Metadata{},
-			wantErr: "decoding failed due to the following error(s):\n\n'metrics[default.metric]' decoding failed due to the following error(s):\n\n'stability' missing required field: `stability.level`",
+			wantErr: "metric \"default.metric\": missing required field: `stability.level`",
+		},
+		{
+			name:    "testdata/undeprecated_with_deprecation.yaml",
+			want:    Metadata{},
+			wantErr: "`stability` must be `deprecated` when specifying a `deprecated` field",
 		},
 		{
 			name:    "testdata/~~this file doesn't exist~~.yaml",

cmd/mdatagen/internal/metadata.go

@@ -623,7 +623,7 @@ type Signal struct {
 	SemanticConvention *SemanticConvention `mapstructure:"semantic_convention"`
 
 	// The stability level of the signal.
-	Stability Stability `mapstructure:"stability"`
+	Stability component.StabilityLevel `mapstructure:"stability"`
 
 	// Extended documentation of the signal. If specified, this will be appended to the description used in generated documentation.
 	ExtendedDocumentation string `mapstructure:"extended_documentation"`

cmd/mdatagen/internal/metric.go

@@ -53,54 +53,14 @@ type Metric struct {
 	Deprecated *Deprecated `mapstructure:"deprecated,omitempty"`
 }
 
-type Stability struct {
-	Level component.StabilityLevel `mapstructure:"level"`
-	// 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 ""
-	}
-	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`")
-	}
-
-	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 m.Stability != component.StabilityLevelDeprecated {
+			errs = errors.Join(errs, errors.New("`stability` must be `deprecated` when specifying a `deprecated` field"))
+		}
+
 		if err := m.Deprecated.validate(); err != nil {
 			errs = errors.Join(errs, err)
 		}
@@ -114,6 +74,9 @@ func (m *Metric) validate(metricName MetricName, semConvVersion string) error {
 		errs = errors.Join(errs, errors.New("more than one metric type keys, "+
 			"only one of the following has to be specified: sum, gauge, histogram"))
 	}
+	if m.Stability == component.StabilityLevelUndefined {
+		errs = errors.Join(errs, errors.New("missing required field: `stability.level`"))
+	}
 	if m.Description == "" {
 		errs = errors.Join(errs, errors.New(`missing metric description`))
 	}

cmd/mdatagen/internal/metric_test.go

@@ -7,10 +7,7 @@ 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"
 )
 
@@ -41,66 +38,3 @@ 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

@@ -64,7 +64,7 @@ Monotonic cumulative sum int metric with string input_type enabled by default.
 
 ### reaggregate.metric
 
-Metric for testing spacial reaggregation
+Metric for testing spatial reaggregation
 
 | Unit | Metric Type | Value Type | Stability |
 | ---- | ----------- | ---------- | --------- |