[cmd/mdatagen] Generate more mdatagen attribute documentation (open-t…

…elemetry#8985) * Enhance mdatagen attribute documentation * ensure example has attribute without value/enums * Add changelog entry * Add testing of mdatagen documentation generation * Commit all updated documentation.md files * Satisfy linter
zdelagrange · Apr 11, 2022 · 67a8a8d · 67a8a8d
1 parent c03519a
commit 67a8a8d
Show file tree

Hide file tree

Showing 31 changed files with 245 additions and 172 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,8 @@
 - `splunkheceporter`: Add an option to disable log or profiling data (#9065)
 - `datadogexporter`: Add `host_metadata` configuration section to configure host metadata export (#9100)
 
+- `cmd/mdatagen`: Update documentation generated for attributes to list enumerated values and show the "value" that will be visible on metrics when it is different from the attribute key in metadata.yaml (#8983)
+
 ### 🛑 Breaking changes 🛑
 
 - `filelogreceiver`, `journaldreceiver`, `syslogreceiver`, `tcplogreceiver`, `udplogreceiver`:

diff --git a/cmd/mdatagen/documentation.tmpl b/cmd/mdatagen/documentation.tmpl
@@ -38,8 +38,8 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
 {{- range $attributeName, $attributeInfo := .Attributes }}
-| {{ $attributeName }} | {{ $attributeInfo.Description }} |
+| {{ $attributeName }}{{- if $attributeInfo.Value }} ({{ $attributeInfo.Value }}){{- end}} | {{ $attributeInfo.Description }} | {{ stringsJoin $attributeInfo.Enum ", " }} |
 {{- end }}
diff --git a/cmd/mdatagen/main.go b/cmd/mdatagen/main.go
@@ -130,6 +130,7 @@ func generateDocumentation(ymlDir string, thisDir string, md metadata, useExpGen
  "publicVar": func(s string) (string, error) {
  return formatIdentifier(s, true)
  },
+ "stringsJoin": strings.Join,
  }).ParseFiles(path.Join(thisDir, "documentation.tmpl")))
 
  buf := bytes.Buffer{}

diff --git a/cmd/mdatagen/main_test.go b/cmd/mdatagen/main_test.go
@@ -26,6 +26,16 @@ import (
 const (
  validMetadata = `
 name: metricreceiver
+attributes:
+ cpu_type:
+ value: type
+ description: The type of CPU consumption
+ enum:
+ - user
+ - io_wait
+ - system
+ host:
+ description: The type of CPU consumption
 metrics:
  system.cpu.time:
  enabled: true
@@ -35,7 +45,7 @@ metrics:
  sum:
  aggregation: cumulative
  value_type: double
- attributes: []
+ attributes: [host, cpu_type]
 `
 )
 
@@ -45,20 +55,23 @@ func Test_runContents(t *testing.T) {
  useExpGen bool
  }
  tests := []struct {
- name string
- args args
- want string
- wantErr string
+ name string
+ args args
+ expectedDocumentation string
+ want string
+ wantErr string
  }{
  {
- name: "valid metadata",
- args: args{validMetadata, false},
- want: "",
+ name: "valid metadata",
+ args: args{validMetadata, false},
+ expectedDocumentation: "testdata/documentation_v1.md",
+ want: "",
  },
  {
- name: "valid metadata v2",
- args: args{validMetadata, true},
- want: "",
+ name: "valid metadata v2",
+ args: args{validMetadata, true},
+ expectedDocumentation: "testdata/documentation_v2.md",
+ want: "",
  },
  {
  name: "invalid yaml",
@@ -91,7 +104,17 @@ func Test_runContents(t *testing.T) {
  }
  require.FileExists(t, genFilePath)
 
- require.FileExists(t, filepath.Join(tmpdir, "documentation.md"))
+ actualDocumentation := filepath.Join(tmpdir, "documentation.md")
+ require.FileExists(t, actualDocumentation)
+ if tt.expectedDocumentation != "" {
+ expectedFileBytes, err := ioutil.ReadFile(tt.expectedDocumentation)
+ require.NoError(t, err)
+
+ actualFileBytes, err := ioutil.ReadFile(actualDocumentation)
+ require.NoError(t, err)
+
+ require.Equal(t, expectedFileBytes, actualFileBytes)
+ }
  }
  })
  }

diff --git a/cmd/mdatagen/testdata/documentation_v1.md b/cmd/mdatagen/testdata/documentation_v1.md
@@ -0,0 +1,20 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# metricreceiver
+
+## Metrics
+
+These are the metrics available for this scraper.
+
+| Name | Description | Unit | Type | Attributes |
+| ---- | ----------- | ---- | ---- | ---------- |
+| **system.cpu.time** | Total CPU seconds broken down by different states. Additional information on CPU Time can be found [here](https://en.wikipedia.org/wiki/CPU_time). | s | Sum(Double) | <ul> <li>host</li> <li>cpu_type</li> </ul> |
+
+**Highlighted metrics** are emitted by default.
+
+## Metric attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| cpu_type (type) | The type of CPU consumption | user, io_wait, system |
+| host | The type of CPU consumption | |
diff --git a/cmd/mdatagen/testdata/documentation_v2.md b/cmd/mdatagen/testdata/documentation_v2.md
@@ -0,0 +1,27 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# metricreceiver
+
+## Metrics
+
+These are the metrics available for this scraper.
+
+| Name | Description | Unit | Type | Attributes |
+| ---- | ----------- | ---- | ---- | ---------- |
+| **system.cpu.time** | Total CPU seconds broken down by different states. Additional information on CPU Time can be found [here](https://en.wikipedia.org/wiki/CPU_time). | s | Sum(Double) | <ul> <li>host</li> <li>cpu_type</li> </ul> |
+
+**Highlighted metrics** are emitted by default. Other metrics are optional and not emitted by default.
+Any metric can be enabled or disabled with the following scraper configuration:
+
+```yaml
+metrics:
+ <metric_name>:
+ enabled: <true|false>
+```
+
+## Metric attributes
+
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| cpu_type (type) | The type of CPU consumption | user, io_wait, system |
+| host | The type of CPU consumption | |
diff --git a/receiver/apachereceiver/documentation.md b/receiver/apachereceiver/documentation.md
@@ -26,8 +26,8 @@ metrics:
 
 ## Metric 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. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| scoreboard_state (state) | The state of a connection. | open, waiting, starting, reading, sending, keepalive, dnslookup, closing, logging, finishing, idle_cleanup |
+| server_name | The name of the Apache HTTP server. | |
+| workers_state (state) | The state of workers. | busy, idle |
diff --git a/receiver/couchbasereceiver/documentation.md b/receiver/couchbasereceiver/documentation.md
@@ -20,5 +20,5 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
diff --git a/receiver/couchdbreceiver/documentation.md b/receiver/couchdbreceiver/documentation.md
@@ -34,9 +34,9 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| http.method | An HTTP request method. |
-| http.status_code | An HTTP status code. |
-| operation | The operation type. |
-| view | The view type. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| http.method | An HTTP request method. | COPY, DELETE, GET, HEAD, OPTIONS, POST, PUT |
+| http.status_code | An HTTP status code. | |
+| operation | The operation type. | writes, reads |
+| view | The view type. | temporary_view_reads, view_reads |
diff --git a/receiver/elasticsearchreceiver/documentation.md b/receiver/elasticsearchreceiver/documentation.md
@@ -49,20 +49,20 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| cache_name | The name of cache. |
-| collector_name | The name of the garbage collector. |
-| direction | The direction of network data. |
-| disk_usage_state | The state of a section of space on disk. |
-| document_state | The state of the document. |
-| elasticsearch.cluster.name | The name of the elasticsearch cluster. |
-| elasticsearch.node.name | The name of the elasticsearch node. |
-| fs_direction | The direction of filesystem IO. |
-| health_status | The health status of the cluster. |
-| memory_pool_name | The name of the JVM memory pool. |
-| operation | The type of operation. |
-| shard_state | The state of the shard. |
-| task_state | The state of the task. |
-| thread_pool_name | The name of the thread pool. |
-| thread_state | The state of the thread. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| cache_name | The name of cache. | fielddata, query |
+| collector_name (name) | The name of the garbage collector. |  |
+| direction | The direction of network data. | received, sent |
+| disk_usage_state (state) | The state of a section of space on disk. | used, free |
+| document_state (state) | The state of the document. | active, deleted |
+| elasticsearch.cluster.name | The name of the elasticsearch cluster. | |
+| elasticsearch.node.name | The name of the elasticsearch node. | |
+| fs_direction (direction) | The direction of filesystem IO. | read, write |
+| health_status (status) | The health status of the cluster. | green, yellow, red |
+| memory_pool_name (name) | The name of the JVM memory pool. |  |
+| operation (operation) | The type of operation. | index, delete, get, query, fetch, scroll, suggest, merge, refresh, flush, warmer |
+| shard_state (state) | The state of the shard. | active, relocating, initializing, unassigned |
+| task_state (state) | The state of the task. | rejected, completed |
+| thread_pool_name | The name of the thread pool. | |
+| thread_state (state) | The state of the thread. | active, idle |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/cpuscraper/documentation.md
@@ -22,7 +22,7 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| cpu | CPU number starting at 0. |
-| state | Breakdown of CPU usage by type. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| cpu | CPU number starting at 0. | |
+| state | Breakdown of CPU usage by type. | idle, interrupt, nice, softirq, steal, system, user, wait |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/diskscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/diskscraper/documentation.md
@@ -27,7 +27,7 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| device | Name of the disk. |
-| direction | Direction of flow of bytes/operations (read or write). |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| device | Name of the disk. | |
+| direction | Direction of flow of bytes/operations (read or write). | read, write |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/filesystemscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/filesystemscraper/documentation.md
@@ -23,10 +23,10 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| device | Identifier of the filesystem. |
-| mode | Mountpoint mode such "ro", "rw", etc. |
-| mountpoint | Mountpoint path. |
-| state | Breakdown of filesystem usage by type. |
-| type | Filesystem type, such as, "ext4", "tmpfs", etc. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| device | Identifier of the filesystem. | |
+| mode | Mountpoint mode such "ro", "rw", etc. | |
+| mountpoint | Mountpoint path. | |
+| state | Breakdown of filesystem usage by type. | free, reserved, used |
+| type | Filesystem type, such as, "ext4", "tmpfs", etc. | |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/loadscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/loadscraper/documentation.md
@@ -23,5 +23,5 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/memoryscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/memoryscraper/documentation.md
@@ -22,6 +22,6 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| state | Breakdown of memory usage by type. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| state | Breakdown of memory usage by type. | buffered, cached, inactive, free, slab_reclaimable, slab_unreclaimable, used |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/networkscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/networkscraper/documentation.md
@@ -25,9 +25,9 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| device | Name of the network interface. |
-| direction | Direction of flow of bytes/operations (receive or transmit). |
-| protocol | Network protocol, e.g. TCP or UDP. |
-| state | State of the network connection. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| device | Name of the network interface. | |
+| direction | Direction of flow of bytes/operations (receive or transmit). | receive, transmit |
+| protocol | Network protocol, e.g. TCP or UDP. | tcp |
+| state | State of the network connection. | |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/pagingscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/pagingscraper/documentation.md
@@ -24,9 +24,9 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| device | Name of the page file. |
-| direction | Page In or Page Out. |
-| state | Breakdown of paging usage by type. |
-| type | Type of fault. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| device | Name of the page file. | |
+| direction | Page In or Page Out. | page_in, page_out |
+| state | Breakdown of paging usage by type. | cached, free, used |
+| type | Type of fault. | major, minor |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/processesscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/processesscraper/documentation.md
@@ -22,6 +22,6 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| status | Breakdown status of the processes. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| status | Breakdown status of the processes. | blocked, daemon, detached, idle, locked, orphan, paging, running, sleeping, stopped, system, unknown, zombies |
diff --git a/receiver/hostmetricsreceiver/internal/scraper/processscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/processscraper/documentation.md
@@ -35,7 +35,7 @@ metrics:
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| direction | Direction of flow of bytes (read or write). |
-| state | Breakdown of CPU usage by type. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| direction | Direction of flow of bytes (read or write). | read, write |
+| state | Breakdown of CPU usage by type. | system, user, wait |
diff --git a/receiver/kafkametricsreceiver/documentation.md b/receiver/kafkametricsreceiver/documentation.md
@@ -24,8 +24,8 @@ These are the metrics available for this scraper.
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| group | The ID (string) of a consumer group |
-| partition | The number (integer) of the partition |
-| topic | The ID (integer) of a topic |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| group | The ID (string) of a consumer group | |
+| partition | The number (integer) of the partition | |
+| topic | The ID (integer) of a topic | |
diff --git a/receiver/kubeletstatsreceiver/documentation.md b/receiver/kubeletstatsreceiver/documentation.md
@@ -31,7 +31,7 @@ These are the metrics available for this scraper.
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| direction | Direction of flow of bytes/operations (receive or transmit). |
-| interface | Name of the network interface. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| direction | Direction of flow of bytes/operations (receive or transmit). | receive, transmit |
+| interface | Name of the network interface. | |
diff --git a/receiver/memcachedreceiver/documentation.md b/receiver/memcachedreceiver/documentation.md
@@ -24,10 +24,10 @@ These are the metrics available for this scraper.
 
 ## Metric attributes
 
-| Name | Description |
-| ---- | ----------- |
-| command | The type of command. |
-| direction | Direction of data flow. |
-| operation | The type of operation. |
-| state | The type of CPU usage. |
-| type | Result of cache request. |
+| Name | Description | Values |
+| ---- | ----------- | ------ |
+| command | The type of command. | get, set, flush, touch |
+| direction | Direction of data flow. | sent, received |
+| operation | The type of operation. | increment, decrement, get |
+| state | The type of CPU usage. | system, user |
+| type | Result of cache request. | hit, miss |