[mdatagen] Replace optional field with availability for attributes

metadata.yaml schema change for attributes: boolean `optional` field replaced with enum `availability` field with the following options:
  - `default`: always available (replaces `optional: false`)
  - `conditional`: available when conditions met (replaces `optional: true`)
  - `opt_in`: requires explicit enablement

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

metadata.yaml files upgrade guideline:  Replace `optional: true` with `availability: conditional` and `optional: false` with `availability: default` in metadata files.

Author: dmitryax

.chloggen/mdatagen-availability-field.yaml

@@ -0,0 +1,30 @@
+# 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 `availability` 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 an `availability` field that accepts enum values: `default`, `conditional`, or `opt_in`.
+  - `default`: attribute is always available unless explicitly disabled (replaces `optional: false`)
+  - `conditional`: attribute is available only when certain conditions are met (replaces `optional: true`)  
+  - `opt_in`: attribute is not available unless explicitly enabled in user config
+  When `availability` is not specified, it defaults to `default`.
+
+# 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

@@ -221,14 +221,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
 							}
@@ -238,14 +238,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

@@ -188,7 +188,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.Availability == "" {
+			v.Availability = AttributeAvailabilityDefault
+		}
 		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

@@ -74,7 +74,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr",
+						FullName:     "string.resource.attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"string.enum.resource.attr": {
 						Description: "Resource attribute with a known set of string values.",
@@ -83,31 +84,35 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.enum.resource.attr",
+						FullName:     "string.enum.resource.attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"optional.resource.attr": {
 						Description: "Explicitly disabled ResourceAttribute.",
 						Enabled:     false,
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "optional.resource.attr",
+						FullName:     "optional.resource.attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"slice.resource.attr": {
 						Description: "Resource attribute with a slice value.",
 						Enabled:     true,
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeSlice,
 						},
-						FullName: "slice.resource.attr",
+						FullName:     "slice.resource.attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"map.resource.attr": {
 						Description: "Resource attribute with a map value.",
 						Enabled:     true,
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeMap,
 						},
-						FullName: "map.resource.attr",
+						FullName:     "map.resource.attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"string.resource.attr_disable_warning": {
 						Description: "Resource attribute with any string value.",
@@ -118,7 +123,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr_disable_warning",
+						FullName:     "string.resource.attr_disable_warning",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"string.resource.attr_remove_warning": {
 						Description: "Resource attribute with any string value.",
@@ -129,7 +135,8 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string.resource.attr_remove_warning",
+						FullName:     "string.resource.attr_remove_warning",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"string.resource.attr_to_be_removed": {
 						Description: "Resource attribute with any string value.",
@@ -140,7 +147,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",
+						Availability: AttributeAvailabilityDefault,
 					},
 				},
 
@@ -152,67 +160,82 @@ func TestLoadMetadata(t *testing.T) {
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "enum_attr",
+						FullName:     "enum_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"string_attr": {
 						Description:  "Attribute with any string value.",
 						NameOverride: "",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeStr,
 						},
-						FullName: "string_attr",
+						FullName:     "string_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"overridden_int_attr": {
 						Description:  "Integer attribute with overridden name.",
 						NameOverride: "state",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeInt,
 						},
-						FullName: "overridden_int_attr",
+						FullName:     "overridden_int_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"boolean_attr": {
 						Description: "Attribute with a boolean value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeBool,
 						},
-						FullName: "boolean_attr",
+						FullName:     "boolean_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"boolean_attr2": {
 						Description: "Another attribute with a boolean value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeBool,
 						},
-						FullName: "boolean_attr2",
+						FullName:     "boolean_attr2",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"slice_attr": {
 						Description: "Attribute with a slice value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeSlice,
 						},
-						FullName: "slice_attr",
+						FullName:     "slice_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
 					"map_attr": {
 						Description: "Attribute with a map value.",
 						Type: ValueType{
 							ValueType: pcommon.ValueTypeMap,
 						},
-						FullName: "map_attr",
+						FullName:     "map_attr",
+						Availability: AttributeAvailabilityDefault,
 					},
-					"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",
+						Availability: AttributeAvailabilityConditional,
 					},
-					"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",
+						Availability: AttributeAvailabilityConditional,
+					},
+					"opt_in_bool_attr": {
+						Description: "An opt-in attribute with a boolean value",
+						Type: ValueType{
+							ValueType: pcommon.ValueTypeBool,
+						},
+						FullName:     "opt_in_bool_attr",
+						Availability: AttributeAvailabilityOptIn,
 					},
 				},
 				Metrics: map[MetricName]Metric{
@@ -224,7 +247,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{
@@ -240,7 +263,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{
@@ -301,7 +324,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": {
@@ -312,7 +335,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

@@ -212,6 +212,18 @@ func validateEvents(events map[EventName]Event, attributes map[AttributeName]Att
 
 type AttributeName string
 
+// AttributeAvailability defines the availability of an attribute.
+type AttributeAvailability string
+
+const (
+	// AttributeAvailabilityDefault means the attribute is always available unless explicitly disabled in user config.
+	AttributeAvailabilityDefault AttributeAvailability = "default"
+	// AttributeAvailabilityConditional means the attribute is available only when certain conditions are met.
+	AttributeAvailabilityConditional AttributeAvailability = "conditional"
+	// AttributeAvailabilityOptIn means the attribute is not available unless explicitly enabled in user config.
+	AttributeAvailabilityOptIn AttributeAvailability = "opt_in"
+)
+
 func (mn AttributeName) Render() (string, error) {
 	return FormatIdentifier(string(mn), true)
 }
@@ -306,8 +318,31 @@ 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"`
+	// Availability defines the availability of the attribute.
+	Availability AttributeAvailability `mapstructure:"availability"`
+}
+
+// IsConditional returns true if the attribute is conditionally available.
+func (a Attribute) IsConditional() bool {
+	return a.Availability == AttributeAvailabilityConditional
+}
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+func (aa *AttributeAvailability) UnmarshalText(text []byte) error {
+	switch string(text) {
+	case "default":
+		*aa = AttributeAvailabilityDefault
+	case "conditional":
+		*aa = AttributeAvailabilityConditional
+	case "opt_in":
+		*aa = AttributeAvailabilityOptIn
+	case "":
+		// Default value when not specified
+		*aa = AttributeAvailabilityDefault
+	default:
+		return fmt.Errorf("invalid availability %q", string(text))
+	}
+	return nil
 }
 
 // Name returns actual name of the attribute that is set on the metric after applying NameOverride.
@@ -363,9 +398,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
 		}
 	}