[cmd/mdatagen]: Add feature gates support to metadata-schema.yaml

cmd/mdatagen/internal/command.go

@@ -120,6 +120,10 @@
 		toGenerate[filepath.Join(tmplDir, "documentation.md.tmpl")] = filepath.Join(ymlDir, "documentation.md")
 	}
 
+	if len(md.FeatureGates) != 0 {
+		toGenerate[filepath.Join(tmplDir, "feature_gates.go.tmpl")] = filepath.Join(ymlDir, "generated_feature_gates.go")
+	}
+
 	for tmpl, dst := range toGenerate {
 		if err = generateFile(tmpl, dst, md, "metadata"); err != nil {
 			return err
@@ -376,7 +380,7 @@
 		return err
 	}
 
-	var re = regexp.MustCompile(fmt.Sprintf("%s[\\s\\S]*%s", start, end))
+	re := regexp.MustCompile(fmt.Sprintf("%s[\\s\\S]*%s", start, end))
 	if !re.Match(readmeContents) {
 		return nil
 	}

cmd/mdatagen/internal/embedded_templates_test.go

@@ -24,6 +24,7 @@ func TestEnsureTemplatesLoaded(t *testing.T) {
 			path.Join(rootDir, "component_test.go.tmpl"):           {},
 			path.Join(rootDir, "component_telemetry_test.go.tmpl"): {},
 			path.Join(rootDir, "documentation.md.tmpl"):            {},
+			path.Join(rootDir, "feature_gates.go.tmpl"):            {},
 			path.Join(rootDir, "metrics.go.tmpl"):                  {},
 			path.Join(rootDir, "metrics_test.go.tmpl"):             {},
 			path.Join(rootDir, "resource.go.tmpl"):                 {},

cmd/mdatagen/internal/metadata.go

@@ -9,6 +9,7 @@
 	"regexp"
 	"strings"
 
+	"go.opentelemetry.io/collector/confmap"
 	"go.opentelemetry.io/collector/filter"
 	"go.opentelemetry.io/collector/pdata/pcommon"
 )
@@ -40,6 +41,8 @@
 	ShortFolderName string `mapstructure:"-"`
 	// Tests is the set of tests generated with the component
 	Tests Tests `mapstructure:"tests"`
+	// FeatureGates that can be used for the component.
+	FeatureGates map[featureGateName]featureGate `mapstructure:"feature_gates"`
 }
 
 func (md *Metadata) Validate() error {
@@ -156,6 +159,70 @@
 	return errs
 }
 
+var (
+	// idRegexp is used to validate the ID of a Gate.
+	// IDs' characters must be alphanumeric or dots.
+	idRegexp           = regexp.MustCompile(`^[0-9a-zA-Z\.]*$`)
+	versionRegexp      = regexp.MustCompile(`^v(\d+)\.(\d+)\.(\d+)$`)
+	referenceURLRegexp = regexp.MustCompile(`^(https?:\/\/)?([a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+)(\/[^\s]*)?$`)
+	validStages        = map[string]bool{
+		"StageAlpha":      true,
+		"StageBeta":       true,
+		"StageStable":     true,
+		"StageDeprecated": true,
+	}
+)
+
+type featureGate struct {
+	// Required.
+	ID string `mapstructure:"id"`
+	// Description describes the purpose of the attribute.
+	Description string `mapstructure:"description"`
+	// Stage current stage at which the feature gate is in the development lifecyle
+	Stage string `mapstructure:"stage"`
+	// ReferenceURL can optionally give the url of the feature_gate
+	ReferenceURL string `mapstructure:"reference_url"`
+	// FromVersion optional field which gives the release version from which the gate has been given the current stage
+	FromVersion string `mapstructure:"from_version"`
+	// ToVersion optional field which gives the release version till which the gate the gate had the given lifecycle stage
+	ToVersion string `mapstructure:"to_version"`
+	// FeatureGateName name of the feature gate
+	FeatureGateName featureGateName `mapstructure:"-"`
+}
+
+func validateFeatureGate(parser *confmap.Conf) error {
+	var err []error
+	if !parser.IsSet("id") {
+		err = append(err, errors.New("missing required field: `id`"))
+	} else if !idRegexp.MatchString(fmt.Sprintf("%v", parser.Get("id"))) {
+		err = append(err, fmt.Errorf("invalid character(s) in ID"))
+	}
+
+	if !parser.IsSet("stage") {
+		err = append(err, errors.New("missing required field: `stage`"))
+	} else if _, ok := validStages[fmt.Sprintf("%v", parser.Get("stage"))]; !ok {
+		err = append(err, fmt.Errorf("invalid stage"))
+	}
+
+	if parser.IsSet("from_version") && !versionRegexp.MatchString(fmt.Sprintf("%v", parser.Get("from_version"))) {
+		err = append(err, fmt.Errorf("invalid character(s) in from_version"))
+	}
+	if parser.IsSet("to_version") && !versionRegexp.MatchString(fmt.Sprintf("%v", parser.Get("to_version"))) {
+		err = append(err, fmt.Errorf("invalid character(s) in to_version"))
+	}
+	if parser.IsSet("reference_url") && !referenceURLRegexp.MatchString(fmt.Sprintf("%v", parser.Get("reference_url"))) {
+		err = append(err, fmt.Errorf("invalid character(s) in reference_url"))
+	}
+	return errors.Join(err...)
+}
+
+func (f *featureGate) Unmarshal(parser *confmap.Conf) error {
+	if err := validateFeatureGate(parser); err != nil {
+		return err
+	}
+	return parser.Unmarshal(f)
+}
+
 type AttributeName string
 
 func (mn AttributeName) Render() (string, error) {
@@ -166,6 +233,16 @@
 	return FormatIdentifier(string(mn), false)
 }
 
+type featureGateName string
+
+func (mn featureGateName) Render() (string, error) {
+	return FormatIdentifier(string(mn), true)
+}
+
+func (mn featureGateName) RenderUnexported() (string, error) {
+	return FormatIdentifier(string(mn), false)
+}
+
 // ValueType defines an attribute value type.
 type ValueType struct {
 	// ValueType is type of the attribute value.

cmd/mdatagen/internal/metadata_test.go

@@ -10,6 +10,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"go.opentelemetry.io/collector/confmap"
 )
 
 func TestValidate(t *testing.T) {
@@ -142,6 +144,72 @@ func TestValidateMetricDuplicates(t *testing.T) {
 	}
 }
 
+func TestFeatureGateValidate(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   map[string]interface{}
+		wantErr string
+	}{
+		{
+			name: "missing id",
+			input: map[string]interface{}{
+				"stage": "StageAlpha",
+			},
+			wantErr: "missing required field: `id`",
+		},
+		{
+			name: "invalid id",
+			input: map[string]interface{}{
+				"id":    "invalid@id",
+				"stage": "StageAlpha",
+			},
+			wantErr: "invalid character(s) in ID",
+		},
+		{
+			name: "missing stage",
+			input: map[string]interface{}{
+				"id": "valid.id",
+			},
+			wantErr: "missing required field: `stage`",
+		},
+		{
+			name: "invalid stage",
+			input: map[string]interface{}{
+				"id":    "valid.id",
+				"stage": "InvalidStage",
+			},
+			wantErr: "invalid stage",
+		},
+		{
+			name: "invalid from_version",
+			input: map[string]interface{}{
+				"id":           "valid.id",
+				"stage":        "StageAlpha",
+				"from_version": "v1.2.a",
+			},
+			wantErr: "invalid character(s) in from_version",
+		},
+		{
+			name: "invalid reference_url",
+			input: map[string]interface{}{
+				"id":            "valid.id",
+				"stage":         "StageAlpha",
+				"reference_url": "invalid-url",
+			},
+			wantErr: "invalid character(s) in reference_url",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parser := confmap.NewFromStringMap(tt.input)
+			err := validateFeatureGate(parser)
+			require.Error(t, err)
+			require.EqualError(t, err, tt.wantErr)
+		})
+	}
+}
+
 func contains(r string, rs []string) bool {
 	for _, s := range rs {
 		if s == r {

cmd/mdatagen/internal/sampleprocessor/metadata.yaml

@@ -66,3 +66,23 @@ resource_attributes:
     enabled: true
     warnings:
       if_enabled: This resource_attribute is deprecated and will be removed soon.
+
+feature_gates:
+  useOTTLBridge:
+    id: useOTTLBridgeGate
+    stage: StageAlpha
+    description: When enabled, filterlog will convert filterlog configuration to OTTL and use filterottl evaluation
+    from_version: v1.0.0
+    reference_url: https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/18642
+    to_version: v2.0.0
+
+  allowFileDeletion:
+    id: allowFileDeletionGate
+    stage: StageStable
+    description: When enabled, allows usage of the `delete_after_read` setting.
+    from_version: v1.5.0
+    reference_url: https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/16314
+
+  allowFileCreation:
+    id: allowFileCreationGate
+    stage: StageStable

cmd/mdatagen/internal/templates/feature_gates.go.tmpl

@@ -0,0 +1,22 @@
+// Code generated by mdatagen. DO NOT EDIT.
+
+package {{ .Package }}
+
+import (
+	"go.opentelemetry.io/collector/featuregate"
+)
+
+func init() {
+{{- range $name, $fg := .FeatureGates }}
+    {
+        var opts []featuregate.RegisterOption
+        opts = append(opts
+            {{- if $fg.FromVersion }}, featuregate.WithRegisterFromVersion("{{ $fg.FromVersion }}") {{- end }}
+            {{- if $fg.Description }}, featuregate.WithRegisterDescription("{{ $fg.Description }}") {{- end }}
+            {{- if $fg.ReferenceURL }}, featuregate.WithRegisterReferenceURL("{{ $fg.ReferenceURL }}") {{- end }}
+            {{- if $fg.ToVersion }}, featuregate.WithRegisterToVersion("{{ $fg.ToVersion }}") {{- end }})
+        _ = featuregate.GlobalRegistry().MustRegister("{{ $fg.ID }}", featuregate.{{ $fg.Stage }}, opts...)
+    }
+{{- end }}
+
+}

cmd/mdatagen/metadata-schema.yaml

@@ -175,3 +175,20 @@ telemetry:
       # Optional: array of attributes that were defined in the attributes section that are emitted by this metric.
       # Note: Only the following attribute types are supported: <string|int|double|bool>
       attributes: [string]
+
+#Optional: Gate is an immutable object that is owned by the Registry and represents an individual feature that
+# may be enabled or disabled based on the lifecycle state of the feature and CLI flags specified by the user.
+feature_gates:
+  <feature_gate.name>:
+    #Required: id of the feature gate
+    id:
+    #Optional: description of the gate
+    description:
+    #Required: current stage at which the feature gate is in the development lifecyle
+    stage:
+    #Optional: link to the issue where the gate has been discussed
+    reference_url:
+    #Optional: the release version from which the gate has been given the current stage
+    from_version:
+    #Optional: the release version till which the gate had the given lifecycle stage
+    to_version: