[mdatagen] support adding warnings to status table (#20242)

This change allows components to specify warnings in metadata.yaml. --------- Signed-off-by: Alex Boten <[email protected]>
open-telemetry · Mar 21, 2023 · d645ec2 · d645ec2
1 parent 5046503
commit d645ec2
Show file tree

Hide file tree

Showing 10 changed files with 88 additions and 15 deletions.
diff --git a/.chloggen/codeboten_mdatagen-warning.yaml b/.chloggen/codeboten_mdatagen-warning.yaml
@@ -0,0 +1,16 @@
+# 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. filelogreceiver)
+component: mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Warnings can now be specified in metadata.yaml to be included in the generated status table.
+
+# One or more tracking issues related to the change
+issues: [20242]
+
+# (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:
diff --git a/cmd/mdatagen/main_test.go b/cmd/mdatagen/main_test.go
@@ -105,6 +105,7 @@ func Test_inlineReplace(t *testing.T) {
 		markdown      string
 		outputFile    string
 		componentType string
+		warnings      []string
 	}{
 		{
 			name: "readme with empty status",
@@ -152,6 +153,20 @@ Some info about a component
 `,
 			outputFile: "readme_without_status.md",
 		},
+		{
+			name: "component with warnings",
+			markdown: `# Some component
+
+<!-- status autogenerated section -->
+<!-- end autogenerated section -->
+
+Some info about a component
+### warnings
+Some warning there.
+`,
+			outputFile: "readme_with_warnings.md",
+			warnings:   []string{"warning1"},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -161,6 +176,7 @@ Some info about a component
 					Pipelines:     []string{"metrics"},
 					Distributions: []string{"contrib"},
 					Type:          tt.componentType,
+					Warnings:      tt.warnings,
 				},
 			}
 			tmpdir := t.TempDir()

diff --git a/cmd/mdatagen/statusdata.go b/cmd/mdatagen/statusdata.go
@@ -24,4 +24,5 @@ type Status struct {
 	Pipelines     []string `mapstructure:"pipelines"`
 	Distributions []string `mapstructure:"distributions"`
 	Type          string   `mapstructure:"type"`
+	Warnings      []string `mapstructure:"warnings"`
 }
diff --git a/cmd/mdatagen/templates/readme.md.tmpl b/cmd/mdatagen/templates/readme.md.tmpl
@@ -7,10 +7,13 @@
 | Supported pipeline types | {{ stringsJoin .Status.Pipelines "," }}   |
 {{- end }}
 | Distributions            | [{{ stringsJoin .Status.Distributions "], [" }}] |
+{{- if .Status.Warnings }}
+| Warnings                 | [{{ stringsJoin .Status.Warnings ", " }}](#warnings) |
+{{- end }}
 
 [{{ .Status.Stability }}]: https://github.com/open-telemetry/opentelemetry-collector#{{ .Status.Stability }}
 {{- range .Status.Distributions }}
 [{{.}}]: {{ distroURL . }}
-{{- end}}
+{{- end }}
 {{- end }}
 <!-- end autogenerated section -->
diff --git a/cmd/mdatagen/testdata/readme_with_warnings.md b/cmd/mdatagen/testdata/readme_with_warnings.md
@@ -0,0 +1,17 @@
+# Some component
+
+<!-- status autogenerated section -->
+| Status                   |           |
+| ------------------------ |-----------|
+| Stability                | [beta]   |
+| Supported pipeline types | metrics   |
+| Distributions            | [contrib] |
+| Warnings                 | [warning1](#warnings) |
+
+[beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
+[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
+<!-- end autogenerated section -->
+
+Some info about a component
+### warnings
+Some warning there.
diff --git a/processor/transformprocessor/README.md b/processor/transformprocessor/README.md
@@ -1,12 +1,16 @@
 # Transform Processor
-
-| Status                   |                                                                                    |
-|--------------------------|------------------------------------------------------------------------------------|
-| Stability                | [alpha]                                                                            |
-| Supported pipeline types | traces, metrics, logs                                                              |
-| Distributions            | [contrib]                                                                          |
+<!-- status autogenerated section -->
+| Status                   |           |
+| ------------------------ |-----------|
+| Stability                | [alpha]   |
+| Supported pipeline types | traces,metrics,logs   |
+| Distributions            | [contrib] |
 | Warnings                 | [Unsound Transformations, Identity Conflict, Orphaned Telemetry, Other](#warnings) |
 
+[alpha]: https://github.com/open-telemetry/opentelemetry-collector#alpha
+[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
+<!-- end autogenerated section -->
+
 The transform processor modifies telemetry based on configuration using the [OpenTelemetry Transformation Language](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/ottl).
 
 For each signal type, the processor takes a list of statements associated to a [Context type](#contexts) and executes the statements against the incoming telemetry in the order specified in the config.
@@ -254,6 +258,3 @@ The transform processor's implementation of the [OpenTelemetry Transformation La
   - Although the OTTL allows the `set` function to be used with `metric.data_type`, its implementation in the transform processor is NOOP.  To modify a data type you must use a function specific to that purpose.
 - [Identity Conflict](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/standard-warnings.md#identity-conflict): Transformation of metrics have the potential to affect the identity of a metric leading to an Identity Crisis. Be especially cautious when transforming metric name and when reducing/changing existing attributes.  Adding new attributes is safe.
 - [Orphaned Telemetry](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/standard-warnings.md#orphaned-telemetry): The processor allows you to modify `span_id`, `trace_id`, and `parent_span_id` for traces and `span_id`, and `trace_id` logs.  Modifying these fields could lead to orphaned spans or logs.
-
-[alpha]: https://github.com/open-telemetry/opentelemetry-collector#alpha
-[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
diff --git a/processor/transformprocessor/doc.go b/processor/transformprocessor/doc.go
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//go:generate mdatagen metadata.yaml
+
 // Package transformprocessor contains the logic to execute telemetry transform based
 // on the OpenTelemetry Transformation Language.
 package transformprocessor // import "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor"
diff --git a/processor/transformprocessor/factory.go b/processor/transformprocessor/factory.go
@@ -26,13 +26,13 @@ import (
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor/internal/common"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor/internal/logs"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor/internal/metadata"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor/internal/metrics"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor/internal/traces"
 )
 
 const (
-	typeStr   = "transform"
-	stability = component.StabilityLevelAlpha
+	typeStr = "transform"
 )
 
 var processorCapabilities = consumer.Capabilities{MutatesData: true}
@@ -41,9 +41,9 @@ func NewFactory() processor.Factory {
 	return processor.NewFactory(
 		typeStr,
 		createDefaultConfig,
-		processor.WithLogs(createLogsProcessor, stability),
-		processor.WithTraces(createTracesProcessor, stability),
-		processor.WithMetrics(createMetricsProcessor, stability),
+		processor.WithLogs(createLogsProcessor, metadata.Stability),
+		processor.WithTraces(createTracesProcessor, metadata.Stability),
+		processor.WithMetrics(createMetricsProcessor, metadata.Stability),
 	)
 }
 

diff --git a/processor/transformprocessor/internal/metadata/generated_status.go b/processor/transformprocessor/internal/metadata/generated_status.go
diff --git a/processor/transformprocessor/metadata.yaml b/processor/transformprocessor/metadata.yaml
@@ -0,0 +1,8 @@
+name: transform
+
+status:
+  type: processor
+  stability: alpha
+  pipelines: [traces, metrics, logs]
+  distributions: [contrib]
+  warnings: [Unsound Transformations, Identity Conflict, Orphaned Telemetry, Other]