[mdatagen] support producing docs for internal telemetry attributes (open-telemetry#12919)

This adds the ability to generate documentation for the internal metrics
attributes.

---------

Signed-off-by: Alex Boten <[email protected]>

Author: codeboten

.chloggen/codeboten_add-attributes-support-telemetry.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: mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add support for attributes for telemetry configuration in metadata.
+
+# One or more tracking issues or pull requests related to the change
+issues: [12919]
+
+# (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: []

cmd/mdatagen/internal/command_test.go

@@ -45,6 +45,7 @@ func TestRunContents(t *testing.T) {
 		wantGoleakSetup                 bool
 		wantGoleakTeardown              bool
 		wantErr                         bool
+		wantAttributes                  []string
 	}{
 		{
 			yml:     "invalid.yaml",
@@ -156,6 +157,7 @@ func TestRunContents(t *testing.T) {
 			wantTelemetryGenerated:     true,
 			wantReadmeGenerated:        true,
 			wantComponentTestGenerated: true,
+			wantAttributes:             []string{"name"},
 		},
 		{
 			yml:                        "invalid_telemetry_missing_value_type_for_histogram.yaml",
@@ -211,6 +213,13 @@ foo
 				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_metrics.go"))
 				require.FileExists(t, filepath.Join(tmpdir, generatedPackageDir, "generated_metrics_test.go"))
 				require.FileExists(t, filepath.Join(tmpdir, "documentation.md"))
+				if len(tt.wantAttributes) > 0 {
+					contents, err = os.ReadFile(filepath.Join(tmpdir, "documentation.md")) //nolint:gosec
+					require.NoError(t, err)
+					for _, attr := range tt.wantAttributes {
+						require.Contains(t, string(contents), attr)
+					}
+				}
 				contents, err = os.ReadFile(filepath.Join(tmpdir, generatedPackageDir, "generated_metrics.go")) //nolint:gosec
 				require.NoError(t, err)
 				if tt.wantMetricsContext {

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

@@ -53,6 +53,19 @@
 | {{ $metric.Unit }} | {{ $metric.Data.Type }} | {{ $metric.Data.MetricValueType }} |
 {{- if $metric.Data.HasMonotonic }} {{ $metric.Data.Monotonic }} |{{ end }}
 
+{{- if $metric.Attributes }}
+
+#### Attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+{{- range $metric.Attributes }}
+{{- $attribute := . | attributeInfo }}
+| {{ $attribute.Name }} | {{ $attribute.Description }} |
+{{- if $attribute.Enum }} {{ $attribute.Type }}: ``{{ stringsJoin $attribute.Enum "``, ``" }}``{{ else }} Any {{ $attribute.Type }}{{ end }} |
+{{- end }}
+
+{{- end }}
 
 {{- end -}}
 

cmd/mdatagen/internal/testdata/with_telemetry.yaml

@@ -4,6 +4,10 @@ status:
   class: receiver
   stability:
     beta: [traces, logs, metrics]
+attributes:
+  name:
+    description: Name of sampling decision
+    type: string
 telemetry:
   metrics:
     sampling_decision_latency:
@@ -14,3 +18,4 @@ telemetry:
         level: alpha
       histogram:
         value_type: int
+      attributes: [name]