[mdatagen] Replace attributes optional field with requirement_level

metadata.yaml schema change for attributes: boolean `optional` field replaced with enum `requirement_level` field with the following options:
    - `required`: attribute is always included and cannot be excluded
    - `conditionally_required`: attribute is included by default when certain conditions are met (replaces `optional: true`)
    - `recommended`: attribute is included by default but can be disabled via configuration (replaces `optional: false`)
    - `opt_in`: attribute is not included unless explicitly enabled in user config

The `recommended` option is assumed when requirement_level isn't specified explicitly which is the case for the vast majority use cases.

metadata.yaml files upgrade guideline: Replace `optional: true` with `requirement_level: conditionally_required` and `optional: false` with `requirement_level: recommended` (or omit for default) in metadata files.
8b0990

Author: dmitryax

.chloggen/mdatagen-availability-field.yaml

@@ -0,0 +1,31 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# 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: "Replace `optional` field with `requirement_level` field for attributes in metadata schema"
+
+# One or more tracking issues or pull requests related to the change
+issues: [13913]
+
+# (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: |
+  The `optional` boolean field for attributes has been replaced with a `requirement_level` field that accepts enum values: `required`, `conditionally_required`, `recommended`, or `opt_in`.
+  - `required`: attribute is always included and cannot be excluded
+  - `conditionally_required`: attribute is included by default when certain conditions are met (replaces `optional: true`)
+  - `recommended`: attribute is included by default but can be disabled via configuration (replaces `optional: false`)
+  - `opt_in`: attribute is not included unless explicitly enabled in user config
+  When `requirement_level` is not specified, it defaults to `recommended`.
+
+# 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: [user]

cmd/mdatagen/internal/command.go

@@ -231,14 +231,14 @@ func templatize(tmplFile string, md Metadata) *template.Template {
 				"attributeInfo": func(an AttributeName) Attribute {
 					return md.Attributes[an]
 				},
-				"getEventOptionalAttributes": func(attrs map[AttributeName]Attribute) []AttributeName {
+				"getEventConditionalAttributes": 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] {
+							if exists && v.IsConditional() && !seen[attribute] {
 								used = append(used, attribute)
 								seen[attribute] = true
 							}
@@ -248,14 +248,14 @@ func templatize(tmplFile string, md Metadata) *template.Template {
 
 					return used
 				},
-				"getMetricOptionalAttributes": func(attrs map[AttributeName]Attribute) []AttributeName {
+				"getMetricConditionalAttributes": 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] {
+							if exists && v.IsConditional() && !seen[attribute] {
 								used = append(used, attribute)
 								seen[attribute] = true
 							}

cmd/mdatagen/internal/command_test.go

@@ -193,7 +193,7 @@ func TestRunContents(t *testing.T) {
 			wantLogsGenerated:          true,
 		},
 		{
-			yml:                        "with_optional_attribute.yaml",
+			yml:                        "with_conditional_attribute.yaml",
 			wantStatusGenerated:        true,
 			wantReadmeGenerated:        true,
 			wantMetricsGenerated:       true,

cmd/mdatagen/internal/loader.go

@@ -15,9 +15,12 @@ import (
 	"go.opentelemetry.io/collector/confmap/provider/fileprovider"
 )
 
-func setAttributesFullName(attrs map[AttributeName]Attribute) {
+func setAttributeDefaultFields(attrs map[AttributeName]Attribute) {
 	for k, v := range attrs {
 		v.FullName = k
+		if v.RequirementLevel == "" {
+			v.RequirementLevel = AttributeRequirementLevelRecommended
+		}
 		attrs[k] = v
 	}
 }
@@ -61,8 +64,8 @@ func LoadMetadata(filePath string) (Metadata, error) {
 		return md, err
 	}
 
-	setAttributesFullName(md.Attributes)
-	setAttributesFullName(md.ResourceAttributes)
+	setAttributeDefaultFields(md.Attributes)
+	setAttributeDefaultFields(md.ResourceAttributes)
 
 	return md, nil
 }

cmd/mdatagen/internal/loader_test.go

@@ -78,7 +78,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr",
+						FullName:         "string.resource.attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"string.enum.resource.attr": {
 						Description: "Resource attribute with a known set of string values.",
@@ -87,31 +88,35 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.enum.resource.attr",
+						FullName:         "string.enum.resource.attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"optional.resource.attr": {
 						Description: "Explicitly disabled ResourceAttribute.",
 						EnabledPtr:  boolPtr(false),
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "optional.resource.attr",
+						FullName:         "optional.resource.attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"slice.resource.attr": {
 						Description: "Resource attribute with a slice value.",
 						EnabledPtr:  boolPtr(true),
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeSlice,
 						},
-						FullName: "slice.resource.attr",
+						FullName:         "slice.resource.attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"map.resource.attr": {
 						Description: "Resource attribute with a map value.",
 						EnabledPtr:  boolPtr(true),
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeMap,
 						},
-						FullName: "map.resource.attr",
+						FullName:         "map.resource.attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"string.resource.attr_disable_warning": {
 						Description: "Resource attribute with any string value.",
@@ -122,7 +127,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr_disable_warning",
+						FullName:         "string.resource.attr_disable_warning",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"string.resource.attr_remove_warning": {
 						Description: "Resource attribute with any string value.",
@@ -133,7 +139,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr_remove_warning",
+						FullName:         "string.resource.attr_remove_warning",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"string.resource.attr_to_be_removed": {
 						Description: "Resource attribute with any string value.",
@@ -144,7 +151,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr_to_be_removed",
+						FullName:         "string.resource.attr_to_be_removed",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 				},
 
@@ -156,67 +164,82 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "enum_attr",
+						FullName:         "enum_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"string_attr": {
 						Description:  "Attribute with any string value.",
 						NameOverride: "",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string_attr",
+						FullName:         "string_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"overridden_int_attr": {
 						Description:  "Integer attribute with overridden name.",
 						NameOverride: "state",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeInt,
 						},
-						FullName: "overridden_int_attr",
+						FullName:         "overridden_int_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"boolean_attr": {
 						Description: "Attribute with a boolean value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeBool,
 						},
-						FullName: "boolean_attr",
+						FullName:         "boolean_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"boolean_attr2": {
 						Description: "Another attribute with a boolean value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeBool,
 						},
-						FullName: "boolean_attr2",
+						FullName:         "boolean_attr2",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"slice_attr": {
 						Description: "Attribute with a slice value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeSlice,
 						},
-						FullName: "slice_attr",
+						FullName:         "slice_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
 					"map_attr": {
 						Description: "Attribute with a map value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeMap,
 						},
-						FullName: "map_attr",
+						FullName:         "map_attr",
+						RequirementLevel: AttributeRequirementLevelRecommended,
 					},
-					"optional_int_attr": {
-						Description: "An optional attribute with an integer value",
+					"conditional_int_attr": {
+						Description: "A conditional attribute with an integer value",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeInt,
 						},
-						FullName: "optional_int_attr",
-						Optional: true,
+						FullName:         "conditional_int_attr",
+						RequirementLevel: AttributeRequirementLevelConditionallyRequired,
 					},
-					"optional_string_attr": {
-						Description: "An optional attribute with any string value",
+					"conditional_string_attr": {
+						Description: "A conditional attribute with any string value",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "optional_string_attr",
-						Optional: true,
+						FullName:         "conditional_string_attr",
+						RequirementLevel: AttributeRequirementLevelConditionallyRequired,
+					},
+					"opt_in_bool_attr": {
+						Description: "An opt-in attribute with a boolean value",
+						Type: ValueType{
+							ValueType: pcommon.ValueTypeBool,
+						},
+						FullName:         "opt_in_bool_attr",
+						RequirementLevel: AttributeRequirementLevelOptIn,
 					},
 				},
 				Metrics: map[MetricName]Metric{
@@ -228,7 +251,7 @@ func TestLoadMetadata(t *testing.T) {
 							Warnings: Warnings{
 								IfEnabledNotSet: "This metric will be disabled by default soon.",
 							},
-							Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr", "optional_int_attr", "optional_string_attr"},
+							Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr", "conditional_int_attr", "conditional_string_attr", "opt_in_bool_attr"},
 						},
 						Unit: strPtr("s"),
 						Sum: &Sum{
@@ -244,7 +267,7 @@ func TestLoadMetadata(t *testing.T) {
 							Warnings: Warnings{
 								IfConfigured: "This metric is deprecated and will be removed soon.",
 							},
-							Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "optional_string_attr"},
+							Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "conditional_string_attr"},
 						},
 						Unit: strPtr("1"),
 						Gauge: &Gauge{
@@ -305,7 +328,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", "optional_int_attr", "optional_string_attr"},
+							Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr", "conditional_int_attr", "conditional_string_attr", "opt_in_bool_attr"},
 						},
 					},
 					"default.event.to_be_renamed": {
@@ -316,7 +339,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", "optional_string_attr"},
+							Attributes: []AttributeName{"string_attr", "boolean_attr", "boolean_attr2", "conditional_string_attr"},
 						},
 					},
 					"default.event.to_be_removed": {

cmd/mdatagen/internal/metadata.go

@@ -217,6 +217,35 @@ func validateEvents(events map[EventName]Event, attributes map[AttributeName]Att
 
 type AttributeName string
 
+// AttributeRequirementLevel defines the requirement level of an attribute.
+type AttributeRequirementLevel string
+
+const (
+	// AttributeRequirementLevelRequired means the attribute is always included and cannot be excluded.
+	AttributeRequirementLevelRequired AttributeRequirementLevel = "required"
+	// AttributeRequirementLevelConditionallyRequired means the attribute is included by default when certain conditions are met.
+	AttributeRequirementLevelConditionallyRequired AttributeRequirementLevel = "conditionally_required"
+	// AttributeRequirementLevelRecommended means the attribute is included by default but can be disabled via configuration.
+	AttributeRequirementLevelRecommended AttributeRequirementLevel = "recommended"
+	// AttributeRequirementLevelOptIn means the attribute is not included unless explicitly enabled in user config.
+	AttributeRequirementLevelOptIn AttributeRequirementLevel = "opt_in"
+)
+
+// String returns capitalized display name of the requirement level for documentation.
+func (rl AttributeRequirementLevel) String() string {
+	switch rl {
+	case AttributeRequirementLevelRequired:
+		return "Required"
+	case AttributeRequirementLevelConditionallyRequired:
+		return "Conditionally Required"
+	case AttributeRequirementLevelRecommended:
+		return "Recommended"
+	case AttributeRequirementLevelOptIn:
+		return "Opt-In"
+	}
+	return ""
+}
+
 func (mn AttributeName) Render() (string, error) {
 	return FormatIdentifier(string(mn), true)
 }
@@ -311,8 +340,32 @@ 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"`
+	// RequirementLevel defines the requirement level of the attribute.
+	RequirementLevel AttributeRequirementLevel `mapstructure:"requirement_level"`
+}
+
+// IsConditional returns true if the attribute is conditionally required.
+func (a Attribute) IsConditional() bool {
+	return a.RequirementLevel == AttributeRequirementLevelConditionallyRequired
+}
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+func (rl *AttributeRequirementLevel) UnmarshalText(text []byte) error {
+	switch string(text) {
+	case "required":
+		*rl = AttributeRequirementLevelRequired
+	case "conditionally_required":
+		*rl = AttributeRequirementLevelConditionallyRequired
+	case "recommended":
+		*rl = AttributeRequirementLevelRecommended
+	case "opt_in":
+		*rl = AttributeRequirementLevelOptIn
+	case "":
+		*rl = AttributeRequirementLevelRecommended
+	default:
+		return fmt.Errorf("invalid requirement_level %q", string(text))
+	}
+	return nil
 }
 
 // Enabled returns the boolean value of EnabledPtr.
@@ -380,9 +433,9 @@ type Signal struct {
 	Attributes []AttributeName `mapstructure:"attributes"`
 }
 
-func (s Signal) HasOptionalAttribute(attrs map[AttributeName]Attribute) bool {
+func (s Signal) HasConditionalAttributes(attrs map[AttributeName]Attribute) bool {
 	for _, attr := range s.Attributes {
-		if v, exists := attrs[attr]; exists && v.Optional {
+		if v, exists := attrs[attr]; exists && v.IsConditional() {
 			return true
 		}
 	}