[mdatagen] Add event type definition (#12822)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
This PR added type definition needed for supporting structured events in
mdatagen.

Note: the NewLogsBuilder function signature is generated dynamically
according to logs config:
```
func NewLogsBuilder({{ if .Events }}lbc LogsBuilderConfig, {{ end }}settings {{ .Status.Class }}.Settings) *LogsBuilder {}
```
<!-- Issue number if applicable -->
#### Link to tracking issue
Part of #12571 

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

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

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

Author: sincejune

.chloggen/mdatagen-event-definition.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 type definition for events in mdatagen
+
+# 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

@@ -162,7 +162,7 @@ func run(ymlPath string) error {
 		toGenerate[filepath.Join(tmplDir, "documentation.md.tmpl")] = filepath.Join(ymlDir, "documentation.md")
 	}
 
-	if len(md.Metrics) > 0 || len(md.ResourceAttributes) > 0 {
+	if len(md.Metrics) > 0 || len(md.Events) > 0 || len(md.ResourceAttributes) > 0 {
 		testdataDir := filepath.Join(codeDir, "testdata")
 		if err = os.MkdirAll(filepath.Join(codeDir, "testdata"), 0o700); err != nil {
 			return fmt.Errorf("unable to create output directory %q: %w", testdataDir, err)

cmd/mdatagen/internal/event.go

@@ -0,0 +1,57 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package internal // import "go.opentelemetry.io/collector/cmd/mdatagen/internal"
+
+import (
+	"errors"
+
+	"go.opentelemetry.io/collector/confmap"
+)
+
+type (
+	EventName string
+)
+
+func (ln EventName) Render() (string, error) {
+	return FormatIdentifier(string(ln), true)
+}
+
+func (ln EventName) RenderUnexported() (string, error) {
+	return FormatIdentifier(string(ln), false)
+}
+
+type Event struct {
+	// Enabled defines whether the event is enabled by default.
+	Enabled bool `mapstructure:"enabled"`
+
+	// Warnings that will be shown to user under specified conditions.
+	Warnings Warnings `mapstructure:"warnings"`
+
+	// Description of the event.
+	Description string `mapstructure:"description"`
+
+	// The stability level of the event.
+	Stability Stability `mapstructure:"stability"`
+
+	// Extended documentation of the event. If specified, this will be appended to the description used in generated documentation.
+	ExtendedDocumentation string `mapstructure:"extended_documentation"`
+
+	// Attributes is the list of attributes that the event emits.
+	Attributes []AttributeName `mapstructure:"attributes"`
+}
+
+func (l *Event) validate() error {
+	var errs error
+	if l.Description == "" {
+		errs = errors.Join(errs, errors.New(`missing event description`))
+	}
+	return errs
+}
+
+func (l *Event) Unmarshal(parser *confmap.Conf) error {
+	if !parser.IsSet("enabled") {
+		return errors.New("missing required field: `enabled`")
+	}
+	return parser.Unmarshal(l)
+}

cmd/mdatagen/internal/event_test.go

@@ -0,0 +1,40 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package internal
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEventNameRender(t *testing.T) {
+	for _, tt := range []struct {
+		name               EventName
+		success            bool
+		expectedExported   string
+		expectedUnExported string
+	}{
+		{"", false, "", ""},
+		{"otel.val", true, "OtelVal", "otelVal"},
+		{"otel_val_2", true, "OtelVal2", "otelVal2"},
+	} {
+		exported, err := tt.name.Render()
+		if tt.success {
+			require.NoError(t, err)
+			assert.Equal(t, tt.expectedExported, exported)
+		} else {
+			require.Error(t, err)
+		}
+
+		unexported, err := tt.name.RenderUnexported()
+		if tt.success {
+			require.NoError(t, err)
+			assert.Equal(t, tt.expectedUnExported, unexported)
+		} else {
+			require.Error(t, err)
+		}
+	}
+}

cmd/mdatagen/internal/loader_test.go

@@ -247,6 +247,17 @@ func TestLoadMetadata(t *testing.T) {
 						Attributes: []AttributeName{"string_attr", "overridden_int_attr", "enum_attr", "slice_attr", "map_attr"},
 					},
 				},
+				Events: map[EventName]Event{
+					"default.event": {
+						Enabled:               true,
+						Description:           "Example event enabled by default.",
+						ExtendedDocumentation: "The event will be renamed soon.",
+						Warnings: Warnings{
+							IfEnabledNotSet: "This event will be disabled by default soon.",
+						},
+						Attributes: []AttributeName{"string_attr", "boolean_attr"},
+					},
+				},
 				Telemetry: Telemetry{
 					Metrics: map[MetricName]Metric{
 						"batch_size_trigger_send": {
@@ -352,6 +363,11 @@ func TestLoadMetadata(t *testing.T) {
 			want:    Metadata{},
 			wantErr: "decoding failed due to the following error(s):\n\nerror decoding 'metrics[system.cpu.time]': missing required field: `enabled`",
 		},
+		{
+			name:    "testdata/events/no_enabled.yaml",
+			want:    Metadata{},
+			wantErr: "decoding failed due to the following error(s):\n\nerror decoding 'events[system.event]': missing required field: `enabled`",
+		},
 		{
 			name: "testdata/no_value_type.yaml",
 			want: Metadata{},

cmd/mdatagen/internal/metadata.go

@@ -33,6 +33,8 @@ type Metadata struct {
 	Attributes map[AttributeName]Attribute `mapstructure:"attributes"`
 	// Metrics that can be emitted by the component.
 	Metrics map[MetricName]Metric `mapstructure:"metrics"`
+	// Events that can be emitted by the component.
+	Events map[EventName]Event `mapstructure:"events"`
 	// GithubProject is the project where the component README lives in the format of org/repo, defaults to open-telemetry/opentelemetry-collector-contrib
 	GithubProject string `mapstructure:"github_project"`
 	// ScopeName of the metrics emitted by the component.
@@ -62,9 +64,10 @@ func (md *Metadata) Validate() error {
 		errs = errors.Join(errs, err)
 	}
 
-	if err := md.validateMetrics(); err != nil {
+	if err := md.validateMetricsAndEvents(); err != nil {
 		errs = errors.Join(errs, err)
 	}
+
 	return errs
 }
 
@@ -105,11 +108,13 @@ func (md *Metadata) validateResourceAttributes() error {
 	return errs
 }
 
-func (md *Metadata) validateMetrics() error {
+func (md *Metadata) validateMetricsAndEvents() error {
 	var errs error
 	usedAttrs := map[AttributeName]bool{}
-	errs = errors.Join(errs, validateMetrics(md.Metrics, md.Attributes, usedAttrs),
+	errs = errors.Join(errs,
+		validateMetrics(md.Metrics, md.Attributes, usedAttrs),
 		validateMetrics(md.Telemetry.Metrics, md.Attributes, usedAttrs),
+		validateEvents(md.Events, md.Attributes, usedAttrs),
 		md.validateAttributes(usedAttrs))
 	return errs
 }
@@ -173,6 +178,28 @@ func validateMetrics(metrics map[MetricName]Metric, attributes map[AttributeName
 	return errs
 }
 
+func validateEvents(events map[EventName]Event, attributes map[AttributeName]Attribute, usedAttrs map[AttributeName]bool) error {
+	var errs error
+	for en, e := range events {
+		if err := e.validate(); err != nil {
+			errs = errors.Join(errs, fmt.Errorf(`event "%v": %w`, en, err))
+			continue
+		}
+		unknownAttrs := make([]AttributeName, 0, len(e.Attributes))
+		for _, attr := range e.Attributes {
+			if _, ok := attributes[attr]; ok {
+				usedAttrs[attr] = true
+			} else {
+				unknownAttrs = append(unknownAttrs, attr)
+			}
+		}
+		if len(unknownAttrs) > 0 {
+			errs = errors.Join(errs, fmt.Errorf(`event "%v" refers to undefined attributes: %v`, en, unknownAttrs))
+		}
+	}
+	return errs
+}
+
 type AttributeName string
 
 func (mn AttributeName) Render() (string, error) {

cmd/mdatagen/internal/metadata_test.go

@@ -77,6 +77,10 @@ func TestValidate(t *testing.T) {
 			name:    "testdata/no_metric_description.yaml",
 			wantErr: "metric \"default.metric\": missing metric description",
 		},
+		{
+			name:    "testdata/events/no_description.yaml",
+			wantErr: "event \"default.event\": missing event description",
+		},
 		{
 			name:    "testdata/no_metric_unit.yaml",
 			wantErr: "metric \"default.metric\": missing metric unit",
@@ -99,6 +103,10 @@ func TestValidate(t *testing.T) {
 			name:    "testdata/unknown_metric_attribute.yaml",
 			wantErr: "metric \"system.cpu.time\" refers to undefined attributes: [missing]",
 		},
+		{
+			name:    "testdata/events/unknown_attribute.yaml",
+			wantErr: "event \"system.event\" refers to undefined attributes: [missing]",
+		},
 		{
 			name:    "testdata/unused_attribute.yaml",
 			wantErr: "unused attributes: [unused_attr]",