[mdatagen] Add events in generated documentation (#13037)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
Add events in generated documentation

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

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

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

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

---------

Co-authored-by: Dmitry Anoshin <[email protected]>

Author: sincejune

.chloggen/mdatagen-events-doc.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 events in generated documentation
+
+# 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

@@ -158,7 +158,7 @@ func run(ymlPath string) error {
 		}
 	}
 
-	if len(md.Metrics) != 0 || len(md.Telemetry.Metrics) != 0 || len(md.ResourceAttributes) != 0 { // if there's metrics or internal metrics, generate documentation for them
+	if len(md.Metrics) != 0 || len(md.Telemetry.Metrics) != 0 || len(md.ResourceAttributes) != 0 || len(md.Events) != 0 { // if there's metrics or internal metrics or events, generate documentation for them
 		toGenerate[filepath.Join(tmplDir, "documentation.md.tmpl")] = filepath.Join(ymlDir, "documentation.md")
 	}
 
@@ -220,6 +220,9 @@ func templatize(tmplFile string, md Metadata) *template.Template {
 				"metricInfo": func(mn MetricName) Metric {
 					return md.Metrics[mn]
 				},
+				"eventInfo": func(en EventName) Event {
+					return md.Events[en]
+				},
 				"telemetryInfo": func(mn MetricName) Metric {
 					return md.Telemetry.Metrics[mn]
 				},

cmd/mdatagen/internal/command_test.go

@@ -31,8 +31,10 @@ func TestNewCommand(t *testing.T) {
 
 func TestRunContents(t *testing.T) {
 	tests := []struct {
-		yml                             string
-		wantMetricsGenerated            bool
+		yml                  string
+		wantMetricsGenerated bool
+		// TODO: we should add one more flag for logs builder
+		wantEventsGenerated             bool
 		wantMetricsContext              bool
 		wantConfigGenerated             bool
 		wantTelemetryGenerated          bool
@@ -179,6 +181,14 @@ func TestRunContents(t *testing.T) {
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
 		},
+		{
+			yml:                        "events/basic_event.yaml",
+			wantStatusGenerated:        true,
+			wantReadmeGenerated:        true,
+			wantComponentTestGenerated: true,
+			wantConfigGenerated:        true,
+			wantEventsGenerated:        true,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.yml, func(t *testing.T) {
@@ -255,7 +265,7 @@ foo
 				require.NoFileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_telemetry.go"))
 			}
 
-			if !tt.wantMetricsGenerated && !tt.wantTelemetryGenerated && !tt.wantResourceAttributesGenerated {
+			if !tt.wantMetricsGenerated && !tt.wantTelemetryGenerated && !tt.wantResourceAttributesGenerated && !tt.wantEventsGenerated {
 				require.NoFileExists(t, filepath.Join(tmpdir, "documentation.md"))
 			}
 

cmd/mdatagen/internal/samplereceiver/documentation.md

@@ -101,6 +101,46 @@ metrics:
 | string_attr | Attribute with any string value. | Any Str |
 | boolean_attr | Attribute with a boolean value. | Any Bool |
 
+## Default Events
+
+The following events are emitted by default. Each of them can be disabled by applying the following configuration:
+
+```yaml
+events:
+  <event_name>:
+    enabled: false
+```
+
+### default.event
+
+Example event 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 |
+
+### default.event.to_be_removed
+
+[DEPRECATED] Example to-be-removed event enabled by default.
+
+The event will be will be removed 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 |
+
 ## Resource Attributes
 
 | Name | Description | Values | Enabled |

cmd/mdatagen/internal/templates/documentation.md.tmpl

@@ -34,6 +34,36 @@
 
 {{- end -}}
 
+{{- define "event-documentation" -}}
+{{- $eventName := . }}
+{{- $event := $eventName | eventInfo -}}
+
+### {{ $eventName }}
+
+{{ $event.Description }}
+
+{{- if $event.ExtendedDocumentation }}
+
+{{ $event.ExtendedDocumentation }}
+
+{{- end }}
+
+{{- if $event.Attributes }}
+
+#### Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+{{- range $event.Attributes }}
+{{- $attribute := . | attributeInfo }}
+| {{ $attribute.Name }} | {{ $attribute.Description }} |
+{{- if $attribute.Enum }} {{ $attribute.Type }}: ``{{ stringsJoin $attribute.Enum "``, ``" }}``{{ else }} Any {{ $attribute.Type }}{{ end }} |
+{{- end }}
+
+{{- end }}
+
+{{- end -}}
+
 {{- define "telemetry-documentation" -}}
 {{- $metricName := . }}
 {{- $metric := $metricName | telemetryInfo -}}
@@ -123,6 +153,27 @@ metrics:
 {{- end }}
 {{- end }}
 
+{{- if .Events }}
+
+## Default Events
+
+The following events are emitted by default. Each of them can be disabled by applying the following configuration:
+
+```yaml
+events:
+  <event_name>:
+    enabled: false
+```
+
+{{- range $eventName, $event := .Events }}
+{{- if $event.Enabled }}
+
+{{ template "event-documentation" $eventName }}
+
+{{- end }}
+{{- end }}
+{{- end }}
+
 {{- if .ResourceAttributes }}
 
 ## Resource Attributes

cmd/mdatagen/internal/testdata/events/basic_event.yaml

@@ -0,0 +1,14 @@
+type: receiver
+
+status:
+  class: receiver
+  stability:
+    development: [logs]
+  distributions: [contrib]
+  warnings:
+    - Any additional information that should be brought to the consumer's attention
+
+events:
+  event:
+    enabled: true
+    description: Description.