doc: add automated metrics documentation generator

.gitattributes

@@ -0,0 +1,12 @@
+* text=auto eol=lf
+*.go text eol=lf
+*.md text eol=lf
+*.sh text eol=lf
+*.prom text eol=lf
+*.out text eol=lf
+*.txt text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+Makefile text eol=lf
+VERSION text eol=lf
+ttar text eol=lf

Makefile

@@ -116,8 +116,8 @@ update_fixtures:
 
 .PHONY: tools
 tools:
-	@rm ./tools/tools >/dev/null 2>&1 || true
-	@$(GO) build -o tools ./tools/...
+	@rm -f ./tools/tools
+	@$(GO) build -o tools/tools ./tools/main.go
 
 .PHONY: test-e2e
 test-e2e: build collector/fixtures/sys/.unpacked collector/fixtures/udev/.unpacked tools
@@ -139,6 +139,11 @@ checkrules: $(PROMTOOL)
 	@echo ">> checking rules for correctness"
 	find . -name "*rules*.yml" | xargs -I {} $(PROMTOOL) check rules {}
 
+.PHONY: generate-metrics-doc
+generate-metrics-doc:
+	@echo ">> generating metrics documentation"
+	$(GO) run tools/doc_generator/main.go > docs/METRICS.md
+
 .PHONY: test-docker
 test-docker:
 	@echo ">> testing docker image"

README.md

@@ -75,6 +75,7 @@ On some systems, the `timex` collector requires an additional Docker flag,
 
 There is varying support for collectors on each operating system. The tables
 below list all existing collectors and the supported systems.
+For a complete list of all metrics exposed by these collectors, see [METRICS.md](docs/METRICS.md).
 
 Collectors are enabled by providing a `--collector.<name>` flag.
 Collectors that are enabled by default can be disabled by providing a `--no-collector.<name>` flag.

collector/cpu_linux.go

@@ -11,7 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//go:build !nocpu
+// Data Sources: /proc/stat, /sys/devices/system/cpu/
+// Platforms: Linux
 
 package collector
 

collector/meminfo_linux.go

@@ -11,7 +11,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//go:build !nomeminfo
+// Data Sources: /proc/meminfo
+// Platforms: Linux
+// Metric: node_memory_Active_bytes - Memory information field Active_bytes.
+// Metric: node_memory_MemTotal_bytes - Memory information field MemTotal_bytes.
+// Metric: node_memory_MemFree_bytes - Memory information field MemFree_bytes.
 
 package collector
 

collector/textfile.go

@@ -175,7 +175,7 @@ func (c *textFileCollector) exportMTimes(mtimes map[string]time.Time, ch chan<-
 		if c.mtime != nil {
 			mtime = *c.mtime
 		}
-		ch <- prometheus.MustNewConstMetric(mtimeDesc, prometheus.GaugeValue, mtime, path)
+		ch <- prometheus.MustNewConstMetric(mtimeDesc, prometheus.GaugeValue, mtime, filepath.ToSlash(path))
 	}
 }
 
@@ -208,12 +208,11 @@ func (c *textFileCollector) Update(ch chan<- prometheus.Metric) error {
 		}
 
 		for _, f := range files {
-			metricsFilePath := filepath.Join(path, f.Name())
 			if !strings.HasSuffix(f.Name(), ".prom") {
 				continue
 			}
-
 			mtime, families, err := c.processFile(path, f.Name(), ch)
+			metricsFilePath := filepath.ToSlash(filepath.Join(path, f.Name()))
 
 			for _, mf := range families {
 				// Check for metrics with inconsistent help texts and take the first help text occurrence.

docs/collectors/arp.md

@@ -0,0 +1,17 @@
+# arp collector
+
+The arp collector exposes metrics about arp.
+
+## Configuration Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| collector.arp.device-exclude | Regexp of arp devices to exclude (mutually exclusive to device-include). |  |
+| collector.arp.device-include | Regexp of arp devices to include (mutually exclusive to device-exclude). |  |
+| collector.arp.netlink | Use netlink to gather stats instead of /proc/net/arp. | true |
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_arp_entries | ARP entries by device | device |

docs/collectors/bcache.md

@@ -0,0 +1,10 @@
+# bcache collector
+
+The bcache collector exposes metrics about bcache.
+
+## Configuration Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| collector.bcache.priorityStats | Expose expensive priority stats. |  |
+

docs/collectors/bcachefs.md

@@ -0,0 +1,21 @@
+# bcachefs collector
+
+The bcachefs collector exposes metrics about bcachefs.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_bcachefs_btree_cache_size_bytes | Btree cache memory usage in bytes. | uuid |
+| node_bcachefs_btree_write_average_size_bytes | Average btree write size by type. | uuid, type |
+| node_bcachefs_btree_writes_total | Number of btree writes by type. | uuid, type |
+| node_bcachefs_compression_compressed_bytes | Compressed size by algorithm. | uuid, algorithm |
+| node_bcachefs_compression_uncompressed_bytes | Uncompressed size by algorithm. | uuid, algorithm |
+| node_bcachefs_device_bucket_size_bytes | Bucket size in bytes. | uuid, device |
+| node_bcachefs_device_buckets | Total number of buckets. | uuid, device |
+| node_bcachefs_device_durability | Device durability setting. | uuid, device |
+| node_bcachefs_device_info | Device information. | uuid, device, label, state |
+| node_bcachefs_device_io_done_bytes_total | IO bytes by operation type and data type. | uuid, device, operation, data_type |
+| node_bcachefs_device_io_errors_total | IO errors by error type. | uuid, device, type |
+| node_bcachefs_errors_total | Error count by error type. | uuid, error_type |
+| node_bcachefs_info | Filesystem information. | uuid |

docs/collectors/bonding.md

@@ -0,0 +1,10 @@
+# bonding collector
+
+The bonding collector exposes metrics about bonding.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_bonding_active | Number of active slaves per bonding interface. | master |
+| node_bonding_slaves | Number of configured slaves per bonding interface. | master |

docs/collectors/boot.md

@@ -0,0 +1,9 @@
+# boot collector
+
+The boot collector exposes metrics about boot.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_boot_time_seconds | Unix time of last boot, including microseconds. | n/a |

docs/collectors/btrfs.md

@@ -0,0 +1,4 @@
+# btrfs collector
+
+The btrfs collector exposes metrics about btrfs.
+

docs/collectors/buddyinfo.md

@@ -0,0 +1,9 @@
+# buddyinfo collector
+
+The buddyinfo collector exposes metrics about buddyinfo.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_buddyinfo_blocks | Count of free blocks according to size. | node, zone, size |

docs/collectors/cgroups.md

@@ -0,0 +1,10 @@
+# cgroups collector
+
+The cgroups collector exposes metrics about cgroups.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_cgroups_cgroups | Current cgroup number of the subsystem. | subsys_name |
+| node_cgroups_enabled | Current cgroup number of the subsystem. | subsys_name |

docs/collectors/collector.md

@@ -0,0 +1,10 @@
+# collector collector
+
+The collector collector exposes metrics about collector.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_scrape_collector_duration_seconds | node_exporter: Duration of a collector scrape. | collector |
+| node_scrape_collector_success | node_exporter: Whether a collector succeeded. | collector |

docs/collectors/conntrack.md

@@ -0,0 +1,18 @@
+# conntrack collector
+
+The conntrack collector exposes metrics about conntrack.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_nf_conntrack_entries | Number of currently allocated flow entries for connection tracking. | n/a |
+| node_nf_conntrack_entries_limit | Maximum size of connection tracking table. | n/a |
+| node_nf_conntrack_stat_drop | Number of packets dropped due to conntrack failure. | n/a |
+| node_nf_conntrack_stat_early_drop | Number of dropped conntrack entries to make room for new ones, if maximum table size was reached. | n/a |
+| node_nf_conntrack_stat_found | Number of searched entries which were successful. | n/a |
+| node_nf_conntrack_stat_ignore | Number of packets seen which are already connected to a conntrack entry. | n/a |
+| node_nf_conntrack_stat_insert | Number of entries inserted into the list. | n/a |
+| node_nf_conntrack_stat_insert_failed | Number of entries for which list insertion was attempted but failed. | n/a |
+| node_nf_conntrack_stat_invalid | Number of packets seen which can not be tracked. | n/a |
+| node_nf_conntrack_stat_search_restart | Number of conntrack table lookups which had to be restarted due to hashtable resizes. | n/a |

docs/collectors/cpu.md

@@ -0,0 +1,42 @@
+# cpu collector
+
+The cpu collector exposes metrics about cpu.
+
+## Supported Platforms
+
+- Linux
+
+## Data Sources
+
+- /proc/stat
+- /sys/devices/system/cpu/
+
+## Configuration Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| collector.cpu.guest | Enables metric node_cpu_guest_seconds_total | true |
+| collector.cpu.info | Enables metric cpu_info |  |
+| collector.cpu.info.bugs-include | Filter the `bugs` field in cpuInfo with a value that must be a regular expression |  |
+| collector.cpu.info.flags-include | Filter the `flags` field in cpuInfo with a value that must be a regular expression |  |
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_bug_info | The `bugs` field of CPU information from /proc/cpuinfo taken from the first core. | bug |
+| node_context_switches_total | Number of context switches. | cpu |
+| node_core_throttles_total | Number of times this CPU core has been throttled. | package, core |
+| node_cpu_seconds_total | Seconds the CPUs spent in each mode. | cpu, mode |
+| node_cpu_vulnerabilities_info | Details of each CPU vulnerability reported by sysfs. The value of the series is an int encoded state of the vulnerability. The same state is stored as a string in the label | codename, state, mitigation |
+| node_flag_info | The `flags` field of CPU information from /proc/cpuinfo taken from the first core. | flag |
+| node_flags | CPU flags. | cpu, flag |
+| node_frequency_hertz | CPU frequency in hertz from /proc/cpuinfo. | package, core, cpu |
+| node_guest_seconds_total | Seconds the CPUs spent in guests (VMs) for each mode. | cpu, mode |
+| node_info | CPU information from /proc/cpuinfo. | package, core, cpu, vendor, family, model, model_name, microcode, stepping, cachesize |
+| node_isolated | Whether each core is isolated, information from /sys/devices/system/cpu/isolated. | cpu |
+| node_online | CPUs that are online and being scheduled. | cpu |
+| node_package_throttles_total | Number of times this CPU package has been throttled. | package |
+| node_physical_seconds_total | Seconds the physical CPUs spent in each mode. | cpu, mode |
+| node_runqueue | Length of the run queue. | cpu |
+| node_temperature_celsius | CPU temperature | cpu |

docs/collectors/cpufreq.md

@@ -0,0 +1,15 @@
+# cpufreq collector
+
+The cpufreq collector exposes metrics about cpufreq.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_frequency_hertz | Current CPU thread frequency in hertz. | cpu |
+| node_frequency_max_hertz | Maximum CPU thread frequency in hertz. | cpu |
+| node_frequency_min_hertz | Minimum CPU thread frequency in hertz. | cpu |
+| node_scaling_frequency_hertz | Current scaled CPU thread frequency in hertz. | cpu |
+| node_scaling_frequency_max_hertz | Maximum scaled CPU thread frequency in hertz. | cpu |
+| node_scaling_frequency_min_hertz | Minimum scaled CPU thread frequency in hertz. | cpu |
+| node_scaling_governor | Current enabled CPU frequency governor. | cpu, governor |

docs/collectors/device.md

@@ -0,0 +1,4 @@
+# device collector
+
+The device collector exposes metrics about device.
+

docs/collectors/devstat.md

@@ -0,0 +1,14 @@
+# devstat collector
+
+The devstat collector exposes metrics about devstat.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_devstat_blocks_total | The total number of bytes given in terms of the devices blocksize. | device |
+| node_devstat_blocks_transferred_total | The total number of blocks transferred. | device |
+| node_devstat_busy_time_seconds_total | Total time the device had one or more transactions outstanding in seconds. | device |
+| node_devstat_bytes_total | The total number of bytes transferred for reads and writes on the device. | device |
+| node_devstat_duration_seconds_total | The total duration of transactions in seconds. | device, type |
+| node_devstat_transfers_total | The total number of transactions completed. | device |

docs/collectors/diskstats.md

@@ -0,0 +1,51 @@
+# diskstats collector
+
+The diskstats collector exposes metrics about diskstats.
+
+## Configuration Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| collector.diskstats.device-exclude | Regexp of diskstats devices to exclude (mutually exclusive to device-include). |  |
+| collector.diskstats.device-include | Regexp of diskstats devices to include (mutually exclusive to device-exclude). |  |
+| collector.diskstats.ignored-devices | DEPRECATED: Use collector.diskstats.device-exclude |  |
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_ata_rotation_rate_rpm | ATA disk rotation rate in RPMs (0 for SSDs). | device |
+| node_ata_write_cache | ATA disk has a write cache. | device |
+| node_ata_write_cache_enabled | ATA disk has its write cache enabled. | device |
+| node_block_size_bytes | Size of the block device in bytes. | n/a |
+| node_device_mapper_info | Info about disk device mapper. | device, name, uuid, vg_name, lv_name, lv_layer |
+| node_discard_time_seconds_total | This is the total number of seconds spent by all discards. | n/a |
+| node_discarded_sectors_total | The total number of sectors discarded successfully. | n/a |
+| node_discards_completed_total | The total number of discards completed successfully. | n/a |
+| node_discards_merged_total | The total number of discards merged. | n/a |
+| node_disk_io_time_seconds_total | Total seconds spent doing I/Os. | n/a |
+| node_disk_read_bytes_total | The total number of bytes read successfully. | n/a |
+| node_disk_read_time_seconds_total | The total number of seconds spent by all reads. | n/a |
+| node_disk_reads_completed_total | The total number of reads completed successfully. | n/a |
+| node_disk_write_time_seconds_total | This is the total number of seconds spent by all writes. | n/a |
+| node_disk_writes_completed_total | The total number of writes completed successfully. | n/a |
+| node_disk_written_bytes_total | The total number of bytes written successfully. | n/a |
+| node_filesystem_info | Info about disk filesystem. | device, type, usage, uuid, version |
+| node_flush_requests_time_seconds_total | This is the total number of seconds spent by all flush requests. | n/a |
+| node_flush_requests_total | The total number of flush requests completed successfully | n/a |
+| node_info | Info of /sys/block/<block_device>. | device, major, minor, path, wwn, model, serial, revision, rotational |
+| node_io_now | The number of I/Os currently in progress. | n/a |
+| node_io_time_weighted_seconds_total | The weighted # of seconds spent doing I/Os. | n/a |
+| node_queue_depth | Number of requests in the queue. | n/a |
+| node_read_errors_total | The total number of read errors. | n/a |
+| node_read_retries_total | The total number of read retries. | n/a |
+| node_read_sectors_total | The total number of sectors read successfully. | n/a |
+| node_read_time_seconds_total | The total time spent servicing read requests. | n/a |
+| node_reads_merged_total | The total number of reads merged. | n/a |
+| node_transfers_to_disk_total | The total number of transfers from disk. | n/a |
+| node_transfers_total | The total number of transfers to/from disk. | n/a |
+| node_write_errors_total | The total number of write errors. | n/a |
+| node_write_retries_total | The total number of write retries. | n/a |
+| node_write_time_seconds_total | The total time spent servicing write requests. | n/a |
+| node_writes_merged_total | The number of writes merged. | n/a |
+| node_written_sectors_total | The total number of sectors written successfully. | n/a |

docs/collectors/dmi.md

@@ -0,0 +1,4 @@
+# dmi collector
+
+The dmi collector exposes metrics about dmi.
+

docs/collectors/drbd.md

@@ -0,0 +1,9 @@
+# drbd collector
+
+The drbd collector exposes metrics about drbd.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_drbd_connected | Whether DRBD is connected to the peer. | device |

docs/collectors/drm.md

@@ -0,0 +1,16 @@
+# drm collector
+
+The drm collector exposes metrics about drm.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_drm_card_info | Card information | card, memory_vendor, power_performance_level, unique_id, vendor |
+| node_drm_gpu_busy_percent | How busy the GPU is as a percentage. | card |
+| node_drm_memory_gtt_size_bytes | The size of the graphics translation table (GTT) block in bytes. | card |
+| node_drm_memory_gtt_used_bytes | The used amount of the graphics translation table (GTT) block in bytes. | card |
+| node_drm_memory_vis_vram_size_bytes | The size of visible VRAM in bytes. | card |
+| node_drm_memory_vis_vram_used_bytes | The used amount of visible VRAM in bytes. | card |
+| node_drm_memory_vram_size_bytes | The size of VRAM in bytes. | card |
+| node_drm_memory_vram_used_bytes | The used amount of VRAM in bytes. | card |

docs/collectors/edac.md

@@ -0,0 +1,12 @@
+# edac collector
+
+The edac collector exposes metrics about edac.
+
+## Metrics
+
+| Metric | Description | Labels |
+| --- | --- | --- |
+| node_edac_correctable_errors_total | Total correctable memory errors. | controller |
+| node_edac_csrow_correctable_errors_total | Total correctable memory errors for this csrow. | controller, csrow |
+| node_edac_csrow_uncorrectable_errors_total | Total uncorrectable memory errors for this csrow. | controller, csrow |
+| node_edac_uncorrectable_errors_total | Total uncorrectable memory errors. | controller |