[cmd/mdatagen] Add support for optional attribute (#13007)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
Add support for optional attribute, ref: [Conditional Required
Attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md#conditionally-required)

Notes:
- Add `helper.tmpl` for helper templates
- Add `With<AttributeName>EventAttribute` and
`With<AttributeName>MetricAttribute` for optional attributes
- Add some helper functions in go files.

<!-- Issue number if applicable -->
#### Link to tracking issue
Relevant to #12571 

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Updated

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

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

Author: sincejune

.chloggen/optional-attribute.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: 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 optional attribute
+
+# One or more tracking issues or pull requests related to the change
+issues: [12571]
+
+# (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: [api]

cmd/mdatagen/internal/command.go

@@ -14,6 +14,7 @@ import (
 	"regexp"
 	"runtime/debug"
 	"slices"
+	"sort"
 	"strings"
 	"text/template"
 
@@ -217,6 +218,40 @@ func templatize(tmplFile string, md Metadata) *template.Template {
 				"attributeInfo": func(an AttributeName) Attribute {
 					return md.Attributes[an]
 				},
+				"getEventOptionalAttributes": func(attrs map[AttributeName]Attribute) []AttributeName {
+					seen := make(map[AttributeName]bool)
+					used := make([]AttributeName, 0)
+
+					for _, event := range md.Events {
+						for _, attribute := range event.Attributes {
+							v, exists := attrs[attribute]
+							if exists && v.Optional && !seen[attribute] {
+								used = append(used, attribute)
+								seen[attribute] = true
+							}
+						}
+					}
+					sort.Slice(used, func(i, j int) bool { return string(used[i]) < string(used[j]) })
+
+					return used
+				},
+				"getMetricOptionalAttributes": func(attrs map[AttributeName]Attribute) []AttributeName {
+					seen := make(map[AttributeName]bool)
+					used := make([]AttributeName, 0)
+
+					for _, event := range md.Metrics {
+						for _, attribute := range event.Attributes {
+							v, exists := attrs[attribute]
+							if exists && v.Optional && !seen[attribute] {
+								used = append(used, attribute)
+								seen[attribute] = true
+							}
+						}
+					}
+					sort.Slice(used, func(i, j int) bool { return string(used[i]) < string(used[j]) })
+
+					return used
+				},
 				"metricInfo": func(mn MetricName) Metric {
 					return md.Metrics[mn]
 				},
@@ -300,7 +335,7 @@ func templatize(tmplFile string, md Metadata) *template.Template {
 				// which uses the `\` as a special character.
 				// Meaning on windows based machines, the `\` needs to be replaced
 				// with a `/` for it to find the file.
-			}).ParseFS(TemplateFS, strings.ReplaceAll(tmplFile, "\\", "/")))
+			}).ParseFS(TemplateFS, "templates/helper.tmpl", strings.ReplaceAll(tmplFile, "\\", "/")))
 }
 
 func executeTemplate(tmplFile string, md Metadata, goPackage string) ([]byte, error) {

cmd/mdatagen/internal/command_test.go

@@ -36,6 +36,7 @@ func TestRunContents(t *testing.T) {
 		// TODO: we should add one more flag for logs builder
 		wantEventsGenerated             bool
 		wantMetricsContext              bool
+		wantLogsGenerated               bool
 		wantConfigGenerated             bool
 		wantTelemetryGenerated          bool
 		wantResourceAttributesGenerated bool
@@ -66,6 +67,7 @@ func TestRunContents(t *testing.T) {
 			wantStatusGenerated:        true,
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
+			wantLogsGenerated:          true,
 		},
 		{
 			yml:                 "basic_pkg.yaml",
@@ -88,6 +90,7 @@ func TestRunContents(t *testing.T) {
 			wantResourceAttributesGenerated: true,
 			wantReadmeGenerated:             true,
 			wantComponentTestGenerated:      true,
+			wantLogsGenerated:               true,
 		},
 		{
 			yml:                        "status_only.yaml",
@@ -100,6 +103,7 @@ func TestRunContents(t *testing.T) {
 			wantStatusGenerated:        true,
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
+			wantLogsGenerated:          true,
 		},
 		{
 			yml:                        "with_tests_exporter.yaml",
@@ -160,6 +164,7 @@ func TestRunContents(t *testing.T) {
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
 			wantAttributes:             []string{"name"},
+			wantLogsGenerated:          true,
 		},
 		{
 			yml:                        "invalid_telemetry_missing_value_type_for_histogram.yaml",
@@ -180,6 +185,16 @@ func TestRunContents(t *testing.T) {
 			wantStatusGenerated:        true,
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
+			wantLogsGenerated:          true,
+		},
+		{
+			yml:                        "with_optional_attribute.yaml",
+			wantStatusGenerated:        true,
+			wantReadmeGenerated:        true,
+			wantMetricsGenerated:       true,
+			wantLogsGenerated:          true,
+			wantConfigGenerated:        true,
+			wantComponentTestGenerated: true,
 		},
 		{
 			yml:                        "events/basic_event.yaml",
@@ -188,6 +203,7 @@ func TestRunContents(t *testing.T) {
 			wantComponentTestGenerated: true,
 			wantConfigGenerated:        true,
 			wantEventsGenerated:        true,
+			wantLogsGenerated:          true,
 		},
 	}
 	for _, tt := range tests {
@@ -244,6 +260,14 @@ foo
 				require.NoFileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_metrics_test.go"))
 			}
 
+			if tt.wantLogsGenerated {
+				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_logs.go"))
+				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_logs_test.go"))
+			} else {
+				require.NoFileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_logs.go"))
+				require.NoFileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_logs_test.go"))
+			}
+
 			if tt.wantConfigGenerated {
 				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_config.go"))
 				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_config_test.go"))

cmd/mdatagen/internal/embedded_templates_test.go

@@ -39,6 +39,7 @@ func TestEnsureTemplatesLoaded(t *testing.T) {
 			path.Join(rootDir, "testdata", "config.yaml.tmpl"): {},
 			path.Join(rootDir, "telemetrytest.go.tmpl"):        {},
 			path.Join(rootDir, "telemetrytest_test.go.tmpl"):   {},
+			path.Join(rootDir, "helper.tmpl"):                  {},
 		}
 		count = 0
 	)

cmd/mdatagen/internal/event.go

@@ -55,3 +55,12 @@ func (l *Event) Unmarshal(parser *confmap.Conf) error {
 	}
 	return parser.Unmarshal(l)
 }
+
+func (l Event) HasOptionalAttribute(attrs map[AttributeName]Attribute) bool {
+	for _, attr := range l.Attributes {
+		if v, exists := attrs[attr]; exists && v.Optional {
+			return true
+		}
+	}
+	return false
+}

cmd/mdatagen/internal/loader_test.go

@@ -197,6 +197,22 @@ func TestLoadMetadata(t *testing.T) {
 						},
 						FullName: "map_attr",
 					},
+					"optional_int_attr": {
+						Description: "An optional attribute with an integer value",
+						Type: ValueType{
+							ValueType: pcommon.ValueTypeInt,
+						},
+						FullName: "optional_int_attr",
+						Optional: true,
+					},
+					"optional_string_attr": {
+						Description: "An optional attribute with any string value",
+						Type: ValueType{
+							ValueType: pcommon.ValueTypeStr,
+						},
+						FullName: "optional_string_attr",
+						Optional: true,
+					},
 				},
 				Metrics: map[MetricName]Metric{
 					"default.metric": {
@@ -212,7 +228,7 @@ func TestLoadMetadata(t *testing.T) {
 							AggregationTemporality: AggregationTemporality{Aggregation: pmetric.AggregationTemporalityCumulative},
 							Mono:                   Mono{Monotonic: true},
 						},
-						Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr"},
+						Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr", "optional_int_attr", "optional_string_attr"},
 					},
 					"optional.metric": {
 						Enabled:     false,
@@ -224,7 +240,7 @@ func TestLoadMetadata(t *testing.T) {
 						Gauge: &Gauge{
 							MetricValueType: MetricValueType{pmetric.NumberDataPointValueTypeDouble},
 						},
-						Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2"},
+						Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "optional_string_attr"},
 					},
 					"optional.metric.empty_unit": {
 						Enabled:     false,
@@ -273,7 +289,7 @@ func TestLoadMetadata(t *testing.T) {
 						Warnings: Warnings{
 							IfEnabledNotSet: "This event will be disabled by default soon.",
 						},
-						Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr"},
+						Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr", "optional_int_attr", "optional_string_attr"},
 					},
 					"default.event.to_be_renamed": {
 						Enabled:               false,
@@ -282,7 +298,7 @@ func TestLoadMetadata(t *testing.T) {
 						Warnings: Warnings{
 							IfConfigured: "This event is deprecated and will be renamed soon.",
 						},
-						Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2"},
+						Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "optional_string_attr"},
 					},
 					"default.event.to_be_removed": {
 						Enabled:               true,

cmd/mdatagen/internal/metadata.go

@@ -304,6 +304,8 @@ type Attribute struct {
 	FullName AttributeName `mapstructure:"-"`
 	// Warnings that will be shown to user under specified conditions.
 	Warnings Warnings `mapstructure:"warnings"`
+	// Optional defines whether the attribute is required.
+	Optional bool `mapstructure:"optional"`
 }
 
 // Name returns actual name of the attribute that is set on the metric after applying NameOverride.

cmd/mdatagen/internal/metric.go

@@ -124,6 +124,15 @@ func (m Metric) Data() MetricData {
 	return nil
 }
 
+func (m Metric) HasOptionalAttribute(attrs map[AttributeName]Attribute) bool {
+	for _, attr := range m.Attributes {
+		if v, exists := attrs[attr]; exists && v.Optional {
+			return true
+		}
+	}
+	return false
+}
+
 // MetricData is generic interface for all metric datatypes.
 type MetricData interface {
 	Type() string

cmd/mdatagen/internal/sampleconnector/documentation.md

@@ -24,13 +24,13 @@ The metric will be become optional soon.
 
 #### Attributes
 
-| Name | Description | Values |
-| ---- | ----------- | ------ |
-| string_attr | Attribute with any string value. | Any Str |
-| state | Integer attribute with overridden name. | Any Int |
-| enum_attr | Attribute with a known set of string values. | Str: ``red``, ``green``, ``blue`` |
-| slice_attr | Attribute with a slice value. | Any Slice |
-| map_attr | Attribute with a map value. | Any Map |
+| Name | Description | Values | Optional |
+| ---- | ----------- | ------ | -------- |
+| string_attr | Attribute with any string value. | Any Str | false |
+| state | Integer attribute with overridden name. | Any Int | false |
+| enum_attr | Attribute with a known set of string values. | Str: ``red``, ``green``, ``blue`` | false |
+| slice_attr | Attribute with a slice value. | Any Slice | false |
+| map_attr | Attribute with a map value. | Any Map | false |
 
 ### default.metric.to_be_removed
 
@@ -52,13 +52,13 @@ Monotonic cumulative sum int metric with string input_type enabled by default.
 
 #### Attributes
 
-| Name | Description | Values |
-| ---- | ----------- | ------ |
-| string_attr | Attribute with any string value. | Any Str |
-| state | Integer attribute with overridden name. | Any Int |
-| enum_attr | Attribute with a known set of string values. | Str: ``red``, ``green``, ``blue`` |
-| slice_attr | Attribute with a slice value. | Any Slice |
-| map_attr | Attribute with a map value. | Any Map |
+| Name | Description | Values | Optional |
+| ---- | ----------- | ------ | -------- |
+| string_attr | Attribute with any string value. | Any Str | false |
+| state | Integer attribute with overridden name. | Any Int | false |
+| enum_attr | Attribute with a known set of string values. | Str: ``red``, ``green``, ``blue`` | false |
+| slice_attr | Attribute with a slice value. | Any Slice | false |
+| map_attr | Attribute with a map value. | Any Map | false |
 
 ## Optional Metrics
 
@@ -80,11 +80,11 @@ metrics:
 
 #### Attributes
 
-| Name | Description | Values |
-| ---- | ----------- | ------ |
-| string_attr | Attribute with any string value. | Any Str |
-| boolean_attr | Attribute with a boolean value. | Any Bool |
-| boolean_attr2 | Another attribute with a boolean value. | Any Bool |
+| Name | Description | Values | Optional |
+| ---- | ----------- | ------ | -------- |
+| string_attr | Attribute with any string value. | Any Str | false |
+| boolean_attr | Attribute with a boolean value. | Any Bool | false |
+| boolean_attr2 | Another attribute with a boolean value. | Any Bool | false |
 
 ### optional.metric.empty_unit
 
@@ -96,10 +96,10 @@ metrics:
 
 #### Attributes
 
-| Name | Description | Values |
-| ---- | ----------- | ------ |
-| string_attr | Attribute with any string value. | Any Str |
-| boolean_attr | Attribute with a boolean value. | Any Bool |
+| Name | Description | Values | Optional |
+| ---- | ----------- | ------ | -------- |
+| string_attr | Attribute with any string value. | Any Str | false |
+| boolean_attr | Attribute with a boolean value. | Any Bool | false |
 
 ## Resource Attributes