[mdatagen] add stability detail for metrics (open-telemetry#11160)

This allows component authors to specify the stability level of
telemetry emitted by components. This provides visibility to end users
as to what they can expect from the telemetry.

---------

Signed-off-by: Alex Boten <223565+codeboten@users.noreply.github.com>

.chloggen/codeboten_stability-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. otlpreceiver)
+component: mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add stability field to telemetry metrics, allowing the generated description to include a stability string.
+
+# One or more tracking issues or pull requests related to the change
+issues: [11160]
+
+# (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.go

@@ -11,6 +11,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/config/configtelemetry"
 	"go.opentelemetry.io/collector/confmap"
 	"go.opentelemetry.io/collector/confmap/confmaptest"
@@ -97,6 +98,21 @@ func (mvt ValueType) Primitive() string {
 	}
 }
 
+type stability struct {
+	Level string `mapstructure:"level"`
+	From  string `mapstructure:"from"`
+}
+
+func (s stability) String() string {
+	if len(s.Level) == 0 || strings.EqualFold(s.Level, component.StabilityLevelStable.String()) {
+		return ""
+	}
+	if len(s.From) > 0 {
+		return fmt.Sprintf(" [%s since %s]", s.Level, s.From)
+	}
+	return fmt.Sprintf(" [%s]", s.Level)
+}
+
 type Metric struct {
 	// Enabled defines whether the metric is enabled by default.
 	Enabled bool `mapstructure:"enabled"`
@@ -107,6 +123,9 @@ type Metric struct {
 	// Description of the metric.
 	Description string `mapstructure:"description"`
 
+	// The stability level of the metric.
+	Stability stability `mapstructure:"stability"`
+
 	// ExtendedDocumentation of the metric. If specified, this will
 	// be appended to the description used in generated documentation.
 	ExtendedDocumentation string `mapstructure:"extended_documentation"`

cmd/mdatagen/internal/loader_test.go

@@ -243,6 +243,7 @@ func TestLoadMetadata(t *testing.T) {
 					Metrics: map[MetricName]Metric{
 						"batch_size_trigger_send": {
 							Enabled:     true,
+							Stability:   stability{Level: "deprecated", From: "v0.110.0"},
 							Description: "Number of times the batch was sent due to a size trigger",
 							Unit:        strPtr("{times}"),
 							Sum: &sum{
@@ -252,6 +253,7 @@ func TestLoadMetadata(t *testing.T) {
 						},
 						"request_duration": {
 							Enabled:     true,
+							Stability:   stability{Level: "alpha"},
 							Description: "Duration of request",
 							Unit:        strPtr("s"),
 							Histogram: &histogram{
@@ -261,6 +263,7 @@ func TestLoadMetadata(t *testing.T) {
 						},
 						"process_runtime_total_alloc_bytes": {
 							Enabled:     true,
+							Stability:   stability{Level: "stable"},
 							Description: "Cumulative bytes allocated for heap objects (see 'go doc runtime.MemStats.TotalAlloc')",
 							Unit:        strPtr("By"),
 							Sum: &sum{

cmd/mdatagen/internal/samplereceiver/documentation.md

@@ -120,7 +120,7 @@ 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
+Number of times the batch was sent due to a size trigger [deprecated since v0.110.0]
 
 | Unit | Metric Type | Value Type | Monotonic |
 | ---- | ----------- | ---------- | --------- |
@@ -146,7 +146,7 @@ For example this metric only exists if feature A is enabled.
 
 ### otelcol_request_duration
 
-Duration of request
+Duration of request [alpha]
 
 | Unit | Metric Type | Value Type |
 | ---- | ----------- | ---------- |

cmd/mdatagen/internal/samplereceiver/metadata.yaml

@@ -161,20 +161,27 @@ telemetry:
   metrics:
     batch_size_trigger_send:
       enabled: true
+      stability:
+        level: deprecated
+        from: v0.110.0
       description: Number of times the batch was sent due to a size trigger
       unit: "{times}"
       sum:
         value_type: int
         monotonic: true
     request_duration:
       enabled: true
+      stability:
+        level: alpha
       description: Duration of request
       unit: s
       histogram:
         value_type: double
         bucket_boundaries: [1, 10, 100]
     process_runtime_total_alloc_bytes:
       enabled: true
+      stability:
+        level: stable
       description: Cumulative bytes allocated for heap objects (see 'go doc runtime.MemStats.TotalAlloc')
       unit: By
       sum:

cmd/mdatagen/internal/samplereceiver/metrics_test.go

@@ -31,7 +31,7 @@ func TestComponentTelemetry(t *testing.T) {
 	tt.assertMetrics(t, []metricdata.Metrics{
 		{
 			Name:        "otelcol_batch_size_trigger_send",
-			Description: "Number of times the batch was sent due to a size trigger",
+			Description: "Number of times the batch was sent due to a size trigger [deprecated since v0.110.0]",
 			Unit:        "{times}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,
@@ -64,7 +64,7 @@ func TestComponentTelemetry(t *testing.T) {
 	tt.assertMetrics(t, []metricdata.Metrics{
 		{
 			Name:        "otelcol_batch_size_trigger_send",
-			Description: "Number of times the batch was sent due to a size trigger",
+			Description: "Number of times the batch was sent due to a size trigger [deprecated since v0.110.0]",
 			Unit:        "{times}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,

cmd/mdatagen/internal/templates/documentation.md.tmpl

@@ -40,7 +40,7 @@
 
 ### otelcol_{{ $metricName }}
 
-{{ $metric.Description }}
+{{ $metric.Description }}{{ $metric.Stability }}
 
 {{- if $metric.ExtendedDocumentation }}
 

cmd/mdatagen/internal/templates/telemetry.go.tmpl

@@ -116,7 +116,7 @@ func NewTelemetryBuilder(settings component.TelemetrySettings, options ...Teleme
     {{- if not $metric.Optional }}
     builder.{{ $name.Render }}, err = builder.meters[configtelemetry.Level{{ casesTitle $metric.Level.String }}].{{ $metric.Data.Instrument }}(
         "otelcol_{{ $name }}",
-        metric.WithDescription("{{ $metric.Description }}"),
+        metric.WithDescription("{{ $metric.Description }}{{ $metric.Stability }}"),
         metric.WithUnit("{{ $metric.Unit }}"),
         {{- if eq $metric.Data.Type "Histogram" -}}
         {{ if $metric.Data.Boundaries -}}metric.WithExplicitBucketBoundaries([]float64{ {{- range $metric.Data.Boundaries }} {{.}}, {{- end }} }...),{{- end }}

cmd/mdatagen/metadata-schema.yaml

@@ -138,6 +138,8 @@ telemetry:
       enabled: bool
       # Required: metric description.
       description:
+      # Optional: the stability level of the metric. Set to alpha by default.
+      stability: [alpha|stable|deprecated]
       # Optional: extended documentation of the metric.
       extended_documentation:
       # Optional: whether or not this metric is optional. Optional metrics may only be initialized

processor/processorhelper/documentation.md

@@ -56,15 +56,15 @@ Number of spans that were dropped.
 
 ### otelcol_processor_incoming_items
 
-Number of items passed to the processor.
+Number of items passed to the processor. [alpha]
 
 | Unit | Metric Type | Value Type | Monotonic |
 | ---- | ----------- | ---------- | --------- |
 | {items} | Sum | Int | true |
 
 ### otelcol_processor_outgoing_items
 
-Number of items emitted from the processor.
+Number of items emitted from the processor. [alpha]
 
 | Unit | Metric Type | Value Type | Monotonic |
 | ---- | ----------- | ---------- | --------- |

processor/processorhelper/logs_test.go

@@ -97,7 +97,7 @@ func TestLogsProcessor_RecordInOut(t *testing.T) {
 	testTelemetry.assertMetrics(t, []metricdata.Metrics{
 		{
 			Name:        "otelcol_processor_incoming_items",
-			Description: "Number of items passed to the processor.",
+			Description: "Number of items passed to the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,
@@ -112,7 +112,7 @@ func TestLogsProcessor_RecordInOut(t *testing.T) {
 		},
 		{
 			Name:        "otelcol_processor_outgoing_items",
-			Description: "Number of items emitted from the processor.",
+			Description: "Number of items emitted from the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,

processor/processorhelper/metadata.yaml

@@ -12,6 +12,8 @@ telemetry:
 
     processor_incoming_items:
       enabled: true
+      stability:
+        level: alpha
       description: Number of items passed to the processor.
       unit: "{items}"
       sum:
@@ -20,6 +22,8 @@ telemetry:
 
     processor_outgoing_items:
       enabled: true
+      stability:
+        level: alpha
       description: Number of items emitted from the processor.
       unit: "{items}"
       sum:

processor/processorhelper/metrics_test.go

@@ -98,7 +98,7 @@ func TestMetricsProcessor_RecordInOut(t *testing.T) {
 	testTelemetry.assertMetrics(t, []metricdata.Metrics{
 		{
 			Name:        "otelcol_processor_incoming_items",
-			Description: "Number of items passed to the processor.",
+			Description: "Number of items passed to the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,
@@ -113,7 +113,7 @@ func TestMetricsProcessor_RecordInOut(t *testing.T) {
 		},
 		{
 			Name:        "otelcol_processor_outgoing_items",
-			Description: "Number of items emitted from the processor.",
+			Description: "Number of items emitted from the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,

processor/processorhelper/traces_test.go

@@ -98,7 +98,7 @@ func TestTracesProcessor_RecordInOut(t *testing.T) {
 	testTelemetry.assertMetrics(t, []metricdata.Metrics{
 		{
 			Name:        "otelcol_processor_incoming_items",
-			Description: "Number of items passed to the processor.",
+			Description: "Number of items passed to the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,
@@ -113,7 +113,7 @@ func TestTracesProcessor_RecordInOut(t *testing.T) {
 		},
 		{
 			Name:        "otelcol_processor_outgoing_items",
-			Description: "Number of items emitted from the processor.",
+			Description: "Number of items emitted from the processor. [alpha]",
 			Unit:        "{items}",
 			Data: metricdata.Sum[int64]{
 				Temporality: metricdata.CumulativeTemporality,