mdatagen - Add support for extended metric descriptions

cmd/mdatagen/documentation.tmpl

@@ -9,7 +9,12 @@ These are the metrics available for this scraper.
 | Name | Description | Unit | Type | Attributes |
 | ---- | ----------- | ---- | ---- | ---------- |
 {{- range $metricName, $metricInfo := .Metrics }}
+{{- if $metricInfo.ExtendedDocumentation }}
+| {{ $metricName }} | {{ $metricInfo.Description }} {{ $metricInfo.ExtendedDocumentation }} | {{ $metricInfo.Unit }} | {{ $metricInfo.Data.Type }} | <ul>
+{{ else }}
 | {{ $metricName }} | {{ $metricInfo.Description }} | {{ $metricInfo.Unit }} | {{ $metricInfo.Data.Type }} | <ul>
+{{- end }}
+
 {{- range $index, $labelName := $metricInfo.Labels }} <li>{{ $labelName }}</li> {{- end }} </ul> |
 {{- end }}
 

cmd/mdatagen/loader.go

@@ -42,6 +42,11 @@ func (mn labelName) Render() (string, error) {
 type metric struct {
 	// Description of the metric.
 	Description string `validate:"required,notblank"`
+
+	// ExtendedDocumentation of the metric. If specified, this will
+	// be appended to the description used in generated documentation.
+	ExtendedDocumentation string `yaml:"extended_documentation"`
+
 	// Unit of the metric.
 	Unit string `yaml:"unit"`
 

cmd/mdatagen/loader_test.go

@@ -38,6 +38,7 @@ labels:
 metrics:
   system.cpu.time:
     description: Total CPU seconds broken down by different states.
+    extended_documentation: Additional information on CPU Time can be found [here](https://en.wikipedia.org/wiki/CPU_time).
     unit: s
     data:
       type: sum
@@ -95,8 +96,9 @@ func Test_loadMetadata(t *testing.T) {
 						Value:       "state"}},
 				Metrics: map[metricName]metric{
 					"system.cpu.time": {
-						Description: "Total CPU seconds broken down by different states.",
-						Unit:        "s",
+						Description:           "Total CPU seconds broken down by different states.",
+						ExtendedDocumentation: "Additional information on CPU Time can be found [here](https://en.wikipedia.org/wiki/CPU_time).",
+						Unit:                  "s",
 						Data: &sum{
 							Aggregated: Aggregated{Aggregation: "cumulative"},
 							Mono:       Mono{Monotonic: true},

cmd/mdatagen/main_test.go

@@ -29,6 +29,7 @@ name: metricreceiver
 metrics:
   system.cpu.time:
     description: Total CPU seconds broken down by different states.
+    extended_description: Additional information on CPU Time can be found [here](https://en.wikipedia.org/wiki/CPU_time).
     unit: s
     data:
       type: sum
@@ -77,6 +78,7 @@ func Test_runContents(t *testing.T) {
 			} else {
 				require.NoError(t, err)
 				require.FileExists(t, path.Join(tmpdir, "internal/metadata/generated_metrics.go"))
+				require.FileExists(t, path.Join(tmpdir, "documentation.md"))
 			}
 		})
 	}

receiver/httpdreceiver/documentation.md

@@ -8,17 +8,19 @@ These are the metrics available for this scraper.
 
 | Name | Description | Unit | Type | Attributes |
 | ---- | ----------- | ---- | ---- | ---------- |
-| httpd.current_connections | The number of active connections currently attached to the HTTP server | connections | Sum | <ul> <li>server_name</li> </ul> |
-| httpd.requests | The number of requests serviced by the HTTP server per second | 1 | Sum | <ul> <li>server_name</li> </ul> |
-| httpd.scoreboard | The number of connections in each state | scoreboard | Sum | <ul> <li>server_name</li> <li>scoreboard_state</li> </ul> |
-| httpd.traffic | Total HTTP server traffic | By | Sum | <ul> <li>server_name</li> </ul> |
-| httpd.uptime | The amount of time that the server has been running in seconds | s | Sum | <ul> <li>server_name</li> </ul> |
-| httpd.workers | The number of workers currently attached to the HTTP server | connections | Sum | <ul> <li>server_name</li> <li>workers_state</li> </ul> |
+| httpd.current_connections | The number of active connections currently attached to the HTTP server. | connections | Sum | <ul> <li>server_name</li> </ul> |
+| httpd.requests | The number of requests serviced by the HTTP server per second. | 1 | Sum | <ul> <li>server_name</li> </ul> |
+| httpd.scoreboard | The number of connections in each state. The apache scoreboard is an encoded representation of the state of all the server's workers. This metric decodes the scoreboard and presents a count of workers in each state. Additional details can be found [here](https://support.cpanel.net/hc/en-us/articles/360052040234-Understanding-the-Apache-scoreboard).
+ | scoreboard | Sum | <ul>
+ <li>server_name</li> <li>scoreboard_state</li> </ul> |
+| httpd.traffic | Total HTTP server traffic. | By | Sum | <ul> <li>server_name</li> </ul> |
+| httpd.uptime | The amount of time that the server has been running in seconds. | s | Sum | <ul> <li>server_name</li> </ul> |
+| httpd.workers | The number of workers currently attached to the HTTP server. | connections | Sum | <ul> <li>server_name</li> <li>workers_state</li> </ul> |
 
 ## Attributes
 
 | Name | Description |
 | ---- | ----------- |
-| scoreboard_state | The state of a connection |
-| server_name | The name of the Apache HTTP server |
-| workers_state | The state of workers |
+| scoreboard_state | The state of a connection. |
+| server_name | The name of the Apache HTTP server. |
+| workers_state | The state of workers. |

receiver/httpdreceiver/metadata.yaml

@@ -2,16 +2,16 @@ name: httpdreceiver
 
 labels:
   server_name:
-    description: The name of the Apache HTTP server
+    description: The name of the Apache HTTP server.
   workers_state:
     value: state
-    description: The state of workers
+    description: The state of workers.
     enum:
       - busy
       - idle
   scoreboard_state:
     value: state
-    description: The state of a connection
+    description: The state of a connection.
     enum:
       - open
       - waiting
@@ -27,47 +27,51 @@ labels:
 
 metrics:
   httpd.uptime:
-    description: The amount of time that the server has been running in seconds
+    description: The amount of time that the server has been running in seconds.
     unit: s
     data:
       type: sum
       monotonic: true
       aggregation: cumulative
     labels: [ server_name ]
   httpd.current_connections:
-    description: The number of active connections currently attached to the HTTP server
+    description: The number of active connections currently attached to the HTTP server.
     unit: connections
     data:
       type: sum
       monotonic: false
       aggregation: cumulative
     labels: [ server_name ]
   httpd.workers:
-    description: The number of workers currently attached to the HTTP server
+    description: The number of workers currently attached to the HTTP server.
     unit: connections
     data:
       type: sum
       monotonic: false
       aggregation: cumulative
     labels: [ server_name, workers_state]
   httpd.requests:
-    description: The number of requests serviced by the HTTP server per second
+    description: The number of requests serviced by the HTTP server per second.
     unit: 1
     data:
       type: sum
       monotonic: true
       aggregation: cumulative
     labels: [ server_name ]
   httpd.traffic:
-    description: Total HTTP server traffic
+    description: Total HTTP server traffic.
     unit: By
     data:
       type: sum
       monotonic: true
       aggregation: cumulative
     labels: [ server_name ]
   httpd.scoreboard:
-    description: The number of connections in each state
+    description: The number of connections in each state.
+    extended_documentation: >
+      The apache scoreboard is an encoded representation of the state of all the server's workers.
+      This metric decodes the scoreboard and presents a count of workers in each state.
+      Additional details can be found [here](https://support.cpanel.net/hc/en-us/articles/360052040234-Understanding-the-Apache-scoreboard).
     unit: scoreboard
     data:
       type: sum

receiver/httpdreceiver/testdata/scraper/expected.json

@@ -10,7 +10,7 @@
           "metrics": [
             {
               "name": "httpd.uptime",
-              "description": "The amount of time that the server has been running in seconds",
+              "description": "The amount of time that the server has been running in seconds.",
               "unit": "s",
               "sum": {
                 "dataPoints": [
@@ -33,7 +33,7 @@
             },
             {
               "name": "httpd.current_connections",
-              "description": "The number of active connections currently attached to the HTTP server",
+              "description": "The number of active connections currently attached to the HTTP server.",
               "unit": "connections",
               "sum": {
                 "dataPoints": [
@@ -56,7 +56,7 @@
             },
             {
               "name": "httpd.workers",
-              "description": "The number of workers currently attached to the HTTP server",
+              "description": "The number of workers currently attached to the HTTP server.",
               "unit": "connections",
               "sum": {
                 "dataPoints": [
@@ -103,7 +103,7 @@
             },
             {
               "name": "httpd.requests",
-              "description": "The number of requests serviced by the HTTP server per second",
+              "description": "The number of requests serviced by the HTTP server per second.",
               "unit": "1",
               "sum": {
                 "dataPoints": [
@@ -126,7 +126,7 @@
             },
             {
               "name": "httpd.traffic",
-              "description": "Total HTTP server traffic",
+              "description": "Total HTTP server traffic.",
               "unit": "By",
               "sum": {
                 "dataPoints": [
@@ -149,7 +149,7 @@
             },
             {
               "name": "httpd.scoreboard",
-              "description": "The number of connections in each state",
+              "description": "The number of connections in each state.",
               "unit": "scoreboard",
               "sum": {
                 "dataPoints": [