[mdatagen] Generate documentation for components with resource attrib…

…utes only (#11242)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
This PR adds support for generating `documentation.md` files for
components which only define resource attributes.
This was reported at
#10705
and also applies at
open-telemetry/opentelemetry-collector-contrib#34210.

<!-- Issue number if applicable -->
#### Link to tracking issue
Fixes
#10705

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Tuned tests and added a sample processor component which only defines
resource attributes.

<!--Describe the documentation added.-->
#### Documentation

<!--Please delete paragraphs that you did not use before submitting.-->

Signed-off-by: ChrsMark <[email protected]>

.chloggen/metagen_resource_attrs_only_doc.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: Generate documentation for components with resource attributes only
+
+# One or more tracking issues or pull requests related to the change
+issues: [10705]
+
+# (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/go.mod

@@ -14,6 +14,7 @@ require (
 	go.opentelemetry.io/collector/consumer/consumertest v0.111.0
 	go.opentelemetry.io/collector/filter v0.111.0
 	go.opentelemetry.io/collector/pdata v1.17.0
+	go.opentelemetry.io/collector/processor v0.111.0
 	go.opentelemetry.io/collector/receiver v0.111.0
 	go.opentelemetry.io/collector/semconv v0.111.0
 	go.opentelemetry.io/otel/metric v1.30.0
@@ -42,10 +43,13 @@ require (
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
+	go.opentelemetry.io/collector/component/componentstatus v0.111.0 // indirect
 	go.opentelemetry.io/collector/consumer/consumerprofiles v0.111.0 // indirect
 	go.opentelemetry.io/collector/internal/globalsignal v0.111.0 // indirect
 	go.opentelemetry.io/collector/pdata/pprofile v0.111.0 // indirect
+	go.opentelemetry.io/collector/pdata/testdata v0.111.0 // indirect
 	go.opentelemetry.io/collector/pipeline v0.111.0 // indirect
+	go.opentelemetry.io/collector/processor/processorprofiles v0.111.0 // indirect
 	go.opentelemetry.io/collector/receiver/receiverprofiles v0.111.0 // indirect
 	go.opentelemetry.io/otel v1.30.0 // indirect
 	go.opentelemetry.io/otel/sdk v1.30.0 // indirect
@@ -95,3 +99,9 @@ replace go.opentelemetry.io/collector/receiver/receiverprofiles => ../../receive
 replace go.opentelemetry.io/collector/pipeline => ../../pipeline
 
 replace go.opentelemetry.io/collector/internal/globalsignal => ../../internal/globalsignal
+
+replace go.opentelemetry.io/collector/processor/processorprofiles => ../../processor/processorprofiles
+
+replace go.opentelemetry.io/collector/component/componentstatus => ../../component/componentstatus
+
+replace go.opentelemetry.io/collector/processor => ../../processor

cmd/mdatagen/internal/command.go

@@ -116,7 +116,7 @@ func run(ymlPath string) error {
 		toGenerate[filepath.Join(tmplDir, "telemetry_test.go.tmpl")] = filepath.Join(codeDir, "generated_telemetry_test.go")
 	}
 
-	if len(md.Metrics) != 0 || len(md.Telemetry.Metrics) != 0 { // if there's metrics or internal metrics, generate documentation for them
+	if len(md.Metrics) != 0 || len(md.Telemetry.Metrics) != 0 || len(md.ResourceAttributes) != 0 { // if there's metrics or internal metrics, generate documentation for them
 		toGenerate[filepath.Join(tmplDir, "documentation.md.tmpl")] = filepath.Join(ymlDir, "documentation.md")
 	}
 

cmd/mdatagen/internal/command_test.go

@@ -19,17 +19,18 @@ import (
 
 func TestRunContents(t *testing.T) {
 	tests := []struct {
-		yml                    string
-		wantMetricsGenerated   bool
-		wantMetricsContext     bool
-		wantConfigGenerated    bool
-		wantTelemetryGenerated bool
-		wantStatusGenerated    bool
-		wantGoleakIgnore       bool
-		wantGoleakSkip         bool
-		wantGoleakSetup        bool
-		wantGoleakTeardown     bool
-		wantErr                bool
+		yml                             string
+		wantMetricsGenerated            bool
+		wantMetricsContext              bool
+		wantConfigGenerated             bool
+		wantTelemetryGenerated          bool
+		wantResourceAttributesGenerated bool
+		wantStatusGenerated             bool
+		wantGoleakIgnore                bool
+		wantGoleakSkip                  bool
+		wantGoleakSetup                 bool
+		wantGoleakTeardown              bool
+		wantErr                         bool
 	}{
 		{
 			yml:     "invalid.yaml",
@@ -42,9 +43,10 @@ func TestRunContents(t *testing.T) {
 			wantStatusGenerated:  true,
 		},
 		{
-			yml:                 "resource_attributes_only.yaml",
-			wantConfigGenerated: true,
-			wantStatusGenerated: true,
+			yml:                             "resource_attributes_only.yaml",
+			wantConfigGenerated:             true,
+			wantStatusGenerated:             true,
+			wantResourceAttributesGenerated: true,
 		},
 		{
 			yml:                 "status_only.yaml",
@@ -168,7 +170,7 @@ foo
 				require.NoFileExists(t, filepath.Join(tmpdir, "internal/metadata/generated_telemetry_test.go"))
 			}
 
-			if !tt.wantMetricsGenerated && !tt.wantTelemetryGenerated {
+			if !tt.wantMetricsGenerated && !tt.wantTelemetryGenerated && !tt.wantResourceAttributesGenerated {
 				require.NoFileExists(t, filepath.Join(tmpdir, "documentation.md"))
 			}
 

cmd/mdatagen/internal/sampleprocessor/README.md

@@ -0,0 +1,22 @@
+# Sample Processor
+This processor is used for testing purposes to check the output of mdatagen.
+<!-- status autogenerated section -->
+| Status        |           |
+| ------------- |-----------|
+| Stability     | [development]: logs   |
+|               | [beta]: traces   |
+|               | [stable]: metrics   |
+| Unsupported Platforms | freebsd, illumos |
+| Distributions | [] |
+| Warnings      | [Any additional information that should be brought to the consumer's attention](#warnings) |
+| Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector?query=is%3Aissue%20is%3Aopen%20label%3Aprocessor%2Fsample%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector/issues?q=is%3Aopen+is%3Aissue+label%3Aprocessor%2Fsample) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector?query=is%3Aissue%20is%3Aclosed%20label%3Aprocessor%2Fsample%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector/issues?q=is%3Aclosed+is%3Aissue+label%3Aprocessor%2Fsample) |
+| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@some](https://www.github.com/some) |
+
+[development]: https://github.com/open-telemetry/opentelemetry-collector#development
+[beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
+[stable]: https://github.com/open-telemetry/opentelemetry-collector#stable
+<!-- end autogenerated section -->
+
+## Warnings
+
+This is where warnings are described.

cmd/mdatagen/internal/sampleprocessor/doc.go

@@ -0,0 +1,10 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Generate a test metrics builder from a sample metrics set covering all configuration options.
+//go:generate mdatagen metadata.yaml
+
+// Deprecated: This package is moving to https://github.com/open-telemetry/opentelemetry-collector and will eventually be removed.
+// Please see https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/30497
+// This is a sample receiver package used to showcase how mdatagen is applied.
+package sampleprocessor // import "go.opentelemetry.io/collector/cmd/mdatagen/internal/sampleprocessor"

cmd/mdatagen/internal/sampleprocessor/documentation.md

@@ -0,0 +1,16 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# sample
+
+## Resource Attributes
+
+| Name | Description | Values | Enabled |
+| ---- | ----------- | ------ | ------- |
+| map.resource.attr | Resource attribute with a map value. | Any Map | true |
+| optional.resource.attr | Explicitly disabled ResourceAttribute. | Any Str | false |
+| slice.resource.attr | Resource attribute with a slice value. | Any Slice | true |
+| string.enum.resource.attr | Resource attribute with a known set of string values. | Str: ``one``, ``two`` | true |
+| string.resource.attr | Resource attribute with any string value. | Any Str | true |
+| string.resource.attr_disable_warning | Resource attribute with any string value. | Any Str | true |
+| string.resource.attr_remove_warning | Resource attribute with any string value. | Any Str | false |
+| string.resource.attr_to_be_removed | Resource attribute with any string value. | Any Str | true |

cmd/mdatagen/internal/sampleprocessor/factory.go

@@ -0,0 +1,61 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package sampleprocessor // import "go.opentelemetry.io/collector/cmd/mdatagen/internal/sampleprocessor"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/collector/cmd/mdatagen/internal/sampleprocessor/internal/metadata"
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/consumer"
+	"go.opentelemetry.io/collector/pdata/plog"
+	"go.opentelemetry.io/collector/pdata/pmetric"
+	"go.opentelemetry.io/collector/pdata/ptrace"
+	"go.opentelemetry.io/collector/processor"
+)
+
+// NewFactory returns a receiver.Factory for sample receiver.
+func NewFactory() processor.Factory {
+	return processor.NewFactory(
+		metadata.Type,
+		func() component.Config { return &struct{}{} },
+		processor.WithTraces(createTracesProcessor, metadata.TracesStability),
+		processor.WithMetrics(createMetricsProcessor, metadata.MetricsStability),
+		processor.WithLogs(createLogsProcessor, metadata.LogsStability))
+}
+
+func createTracesProcessor(context.Context, processor.Settings, component.Config, consumer.Traces) (processor.Traces, error) {
+	return nopInstance, nil
+}
+
+func createMetricsProcessor(context.Context, processor.Settings, component.Config, consumer.Metrics) (processor.Metrics, error) {
+	return nopInstance, nil
+}
+
+func createLogsProcessor(context.Context, processor.Settings, component.Config, consumer.Logs) (processor.Logs, error) {
+	return nopInstance, nil
+}
+
+var nopInstance = &nopProcessor{}
+
+type nopProcessor struct {
+	component.StartFunc
+	component.ShutdownFunc
+}
+
+func (n nopProcessor) ConsumeTraces(context.Context, ptrace.Traces) error {
+	return nil
+}
+
+func (n nopProcessor) ConsumeLogs(context.Context, plog.Logs) error {
+	return nil
+}
+
+func (n nopProcessor) Capabilities() consumer.Capabilities {
+	return consumer.Capabilities{MutatesData: true}
+}
+
+func (n nopProcessor) ConsumeMetrics(context.Context, pmetric.Metrics) error {
+	return nil
+}