[mdatagen] Add support for example configurations in metadata.yaml

.chloggen/mdatagen-example-configs.yaml

@@ -0,0 +1,27 @@
+# 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: 'Add support for `example_configs` field in metadata.yaml to include example configurations with auto-generated documentation and validation tests'
+
+# One or more tracking issues or pull requests related to the change
+issues: [14097, 14133]
+
+# (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: |
+  Components can now define example configurations in metadata.yaml with name, description, and config fields.
+  mdatagen automatically generates documentation sections and validation tests for these examples.
+
+# 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/metadata.go

@@ -51,6 +51,8 @@
 	ScopeName string `mapstructure:"scope_name"`
 	// ShortFolderName is the shortened folder name of the component, removing class if present
 	ShortFolderName string `mapstructure:"-"`
+	// ExampleConfigs are example configuration snippets for the component.
+	ExampleConfigs []ExampleConfig `mapstructure:"example_configs"`
 	// Tests is the set of tests generated with the component
 	Tests Tests `mapstructure:"tests"`
 	// PackageName is the name of the package where the component is defined.

cmd/mdatagen/internal/samplereceiver/documentation.md

@@ -2,6 +2,51 @@
 
 # sample
 
+## Example Configurations
+
+### Basic Configuration
+
+This example demonstrates the most basic configuration for the sample receiver with default settings.
+
+```yaml
+sample:
+  metrics:
+    default.metric:
+      enabled: true
+
+```
+
+### Advanced Configuration
+
+This example shows an advanced configuration with custom metrics enabled and resource attributes configured.
+
+```yaml
+sample:
+  metrics:
+    default.metric:
+      enabled: true
+    optional.metric:
+      enabled: true
+  resource_attributes:
+    string.resource.attr:
+      enabled: true
+    optional.resource.attr:
+      enabled: true
+
+```
+
+### Minimal Configuration
+
+A minimal configuration suitable for testing environments with only essential metrics.
+
+```yaml
+sample:
+  metrics:
+    metric.input_type:
+      enabled: true
+
+```
+
 ## Default Metrics
 
 The following metrics are emitted by default. Each of them can be disabled by applying the following configuration:

cmd/mdatagen/internal/samplereceiver/metadata.yaml

@@ -26,8 +26,8 @@ status:
     deprecated: [profiles]
   deprecation:
     profiles:
-      migration: "no migration needed"
-      date: "2025-02-05"
+      migration: 'no migration needed'
+      date: '2025-02-05'
   distributions: []
   unsupported_platforms: [freebsd, illumos]
   codeowners:
@@ -156,7 +156,7 @@ events:
 
   default.event.to_be_removed:
     enabled: true
-    description: "[DEPRECATED] Example to-be-removed event enabled by default."
+    description: '[DEPRECATED] Example to-be-removed event enabled by default.'
     extended_documentation: The event will be removed soon.
     warnings:
       if_enabled: This event is deprecated and will be removed soon.
@@ -165,9 +165,10 @@ events:
 
   default.event.to_be_renamed:
     enabled: false
-    description: "[DEPRECATED] Example event disabled by default."
+    description: '[DEPRECATED] Example event disabled by default.'
     extended_documentation: The event will be renamed soon.
-    attributes: [string_attr, boolean_attr, boolean_attr2, conditional_string_attr]
+    attributes:
+      [string_attr, boolean_attr, boolean_attr2, conditional_string_attr]
     warnings:
       if_configured: This event is deprecated and will be renamed soon.
 
@@ -199,7 +200,7 @@ metrics:
 
   default.metric.to_be_removed:
     enabled: true
-    description: "[DEPRECATED] Non-monotonic delta sum double metric enabled by default."
+    description: '[DEPRECATED] Non-monotonic delta sum double metric enabled by default.'
     extended_documentation: The metric will be removed soon.
     stability:
       level: deprecated
@@ -227,22 +228,23 @@ metrics:
 
   optional.metric:
     enabled: false
-    description: "[DEPRECATED] Gauge double metric disabled by default."
+    description: '[DEPRECATED] Gauge double metric disabled by default.'
     stability:
       level: deprecated
-    unit: "1"
+    unit: '1'
     gauge:
       value_type: double
-    attributes: [string_attr, boolean_attr, boolean_attr2, conditional_string_attr]
+    attributes:
+      [string_attr, boolean_attr, boolean_attr2, conditional_string_attr]
     warnings:
       if_configured: This metric is deprecated and will be removed soon.
 
   optional.metric.empty_unit:
     enabled: false
-    description: "[DEPRECATED] Gauge double metric disabled by default."
+    description: '[DEPRECATED] Gauge double metric disabled by default.'
     stability:
       level: deprecated
-    unit: ""
+    unit: ''
     gauge:
       value_type: double
     attributes: [string_attr, boolean_attr]
@@ -291,7 +293,7 @@ telemetry:
         level: deprecated
         from: v0.110.0
       description: Number of times the batch was sent due to a size trigger
-      unit: "{times}"
+      unit: '{times}'
       sum:
         value_type: int
         monotonic: true
@@ -310,7 +312,7 @@ telemetry:
       description: Queue capacity - sync gauge example.
       stability:
         level: development
-      unit: "{items}"
+      unit: '{items}'
       gauge:
         value_type: int
     queue_length:
@@ -319,7 +321,7 @@ telemetry:
         level: alpha
       description: This metric is optional and therefore not initialized in NewTelemetryBuilder.
       extended_documentation: For example this metric only exists if feature A is enabled.
-      unit: "{items}"
+      unit: '{items}'
       optional: true
       gauge:
         async: true

cmd/mdatagen/internal/samplescraper/documentation.md

@@ -2,6 +2,18 @@
 
 # sample
 
+## Example Configurations
+
+### Default Configuration
+
+Basic configuration for the sample scraper with default metrics enabled.
+
+```yaml
+sample:
+  collection_interval: 30s
+
+```
+
 ## Default Metrics
 
 The following metrics are emitted by default. Each of them can be disabled by applying the following configuration:

cmd/mdatagen/internal/samplescraper/metadata.yaml

@@ -8,6 +8,13 @@ github_project: open-telemetry/opentelemetry-collector
 
 sem_conv_version: 1.38.0
 
+example_configs:
+  - name: Default Configuration
+    description: Basic configuration for the sample scraper with default metrics enabled.
+    config: |
+      sample:
+        collection_interval: 30s
+
 status:
   disable_codecov_badge: true
   class: scraper
@@ -121,7 +128,7 @@ metrics:
 
   default.metric.to_be_removed:
     enabled: true
-    description: "[DEPRECATED] Non-monotonic delta sum double metric enabled by default."
+    description: '[DEPRECATED] Non-monotonic delta sum double metric enabled by default.'
     extended_documentation: The metric will be removed soon.
     stability:
       level: deprecated
@@ -149,10 +156,10 @@ metrics:
 
   optional.metric:
     enabled: false
-    description: "[DEPRECATED] Gauge double metric disabled by default."
+    description: '[DEPRECATED] Gauge double metric disabled by default.'
     stability:
       level: deprecated
-    unit: "1"
+    unit: '1'
     gauge:
       value_type: double
     attributes: [string_attr, boolean_attr, boolean_attr2]
@@ -161,10 +168,10 @@ metrics:
 
   optional.metric.empty_unit:
     enabled: false
-    description: "[DEPRECATED] Gauge double metric disabled by default."
+    description: '[DEPRECATED] Gauge double metric disabled by default.'
     stability:
       level: deprecated
-    unit: ""
+    unit: ''
     gauge:
       value_type: double
     attributes: [string_attr, boolean_attr]