powersupply: standardize units to SI base units (#1817)

.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.
@@ -189,6 +190,7 @@ Name     | Description | OS
 ---------|-------------|----
 buddyinfo | Exposes statistics of memory fragments as reported by /proc/buddyinfo. | Linux
 cgroups | A summary of the number of active and enabled cgroups | Linux
+cifs | Exposes CIFS client statistics from `/proc/fs/cifs/Stats`. | Linux
 cpu\_vulnerabilities | Exposes CPU vulnerability information from sysfs. | Linux
 devstat | Exposes device statistics | Dragonfly, FreeBSD
 drm | Expose GPU metrics using sysfs / DRM, `amdgpu` is the only driver which exposes this information through DRM | Linux

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/powersupplyclass.go

@@ -25,11 +25,13 @@ import (
 
 var (
 	powerSupplyClassIgnoredPowerSupplies = kingpin.Flag("collector.powersupply.ignored-supplies", "Regexp of power supplies to ignore for powersupplyclass collector.").Default("^$").String()
+	powerSupplyClassUseNewNames          = kingpin.Flag("collector.powersupply.use-new-names", "Use new metric names for powersupplyclass collector.").Bool()
 )
 
 type powerSupplyClassCollector struct {
 	subsystem      string
 	ignoredPattern *regexp.Regexp
+	useNewNames    bool
 	metricDescs    map[string]*prometheus.Desc
 	logger         *slog.Logger
 }
@@ -43,6 +45,7 @@ func NewPowerSupplyClassCollector(logger *slog.Logger) (Collector, error) {
 	return &powerSupplyClassCollector{
 		subsystem:      "power_supply",
 		ignoredPattern: pattern,
+		useNewNames:    *powerSupplyClassUseNewNames,
 		metricDescs:    map[string]*prometheus.Desc{},
 		logger:         logger,
 	}, nil

collector/powersupplyclass_darwin.go

@@ -214,6 +214,48 @@ func (c *powerSupplyClassCollector) Update(ch chan<- prometheus.Metric) error {
 				),
 				prometheus.GaugeValue, *value, powerSupplyName,
 			)
+
+			if c.useNewNames {
+				newValue := *value
+				newName := name
+				switch {
+				case name == "voltage_volt":
+					newName = "voltage_volts"
+				case name == "current_ampere":
+					newName = "current_amperes"
+				case strings.HasSuffix(name, "_capacity"):
+					newName = strings.TrimSuffix(name, "_capacity") + "_capacity_coulombs"
+					newValue *= 3.6 // 1 mAh = 3.6 Coulombs
+				case name == "charging":
+				}
+
+				if newName != name {
+					ch <- prometheus.MustNewConstMetric(
+						prometheus.NewDesc(
+							prometheus.BuildFQName(namespace, c.subsystem, newName),
+							fmt.Sprintf("IOKit Power Source information field %s for <power_supply>.", newName),
+							[]string{"power_supply"}, nil,
+						),
+						prometheus.GaugeValue, newValue, powerSupplyName,
+					)
+				}
+			}
+		}
+
+		if c.useNewNames {
+			// Add capacity_ratio for consistency with Linux
+			data := getPowerSourceDescriptorMap(info)
+			if data["current_capacity"] != nil && data["max_capacity"] != nil && *data["max_capacity"] > 0 {
+				ratio := *data["current_capacity"] / *data["max_capacity"]
+				ch <- prometheus.MustNewConstMetric(
+					prometheus.NewDesc(
+						prometheus.BuildFQName(namespace, c.subsystem, "capacity_ratio"),
+						"IOKit Power Source capacity ratio for <power_supply>.",
+						[]string{"power_supply"}, nil,
+					),
+					prometheus.GaugeValue, ratio, powerSupplyName,
+				)
+			}
 		}
 
 		pushEnumMetric(

collector/powersupplyclass_linux.go

@@ -50,6 +50,24 @@ func (c *powerSupplyClassCollector) Update(ch chan<- prometheus.Metric) error {
 		} {
 			if value != nil {
 				pushPowerSupplyMetric(ch, c.subsystem, name, float64(*value), powerSupply.Name, prometheus.GaugeValue)
+				if c.useNewNames {
+					newValue := float64(*value)
+					newName := name
+					switch name {
+					case "capacity":
+						newName = "capacity_ratio"
+						newValue /= 100
+					case "capacity_alert_max":
+						newName = "capacity_alert_max_ratio"
+						newValue /= 100
+					case "capacity_alert_min":
+						newName = "capacity_alert_min_ratio"
+						newValue /= 100
+					}
+					if newName != name {
+						pushPowerSupplyMetric(ch, c.subsystem, newName, newValue, powerSupply.Name, prometheus.GaugeValue)
+					}
+				}
 			}
 		}
 
@@ -88,6 +106,37 @@ func (c *powerSupplyClassCollector) Update(ch chan<- prometheus.Metric) error {
 		} {
 			if value != nil {
 				pushPowerSupplyMetric(ch, c.subsystem, name, float64(*value)/1e6, powerSupply.Name, prometheus.GaugeValue)
+				if c.useNewNames {
+					newValue := float64(*value) / 1e6
+					newName := name
+					switch {
+					case strings.Contains(name, "current"):
+						if !strings.HasSuffix(name, "_amperes") {
+							newName = strings.TrimSuffix(name, "_ampere") + "_amperes"
+						}
+					case strings.Contains(name, "voltage"):
+						if !strings.HasSuffix(name, "_volts") {
+							newName = strings.TrimSuffix(name, "_volt") + "_volts"
+						}
+					case strings.Contains(name, "energy"):
+						if !strings.HasSuffix(name, "_joules") {
+							newName = strings.TrimSuffix(name, "_watthour") + "_joules"
+							newValue *= 3600
+						}
+					case strings.Contains(name, "charge"):
+						if !strings.HasSuffix(name, "_coulombs") {
+							newName = strings.TrimSuffix(name, "_ampere") + "_coulombs"
+							newValue *= 3600
+						}
+					case strings.Contains(name, "power"):
+						if !strings.HasSuffix(name, "_watts") {
+							newName = strings.TrimSuffix(name, "_watt") + "_watts"
+						}
+					}
+					if newName != name {
+						pushPowerSupplyMetric(ch, c.subsystem, newName, newValue, powerSupply.Name, prometheus.GaugeValue)
+					}
+				}
 			}
 		}
 
@@ -132,7 +181,7 @@ func (c *powerSupplyClassCollector) Update(ch chan<- prometheus.Metric) error {
 
 		fieldDesc := prometheus.NewDesc(
 			prometheus.BuildFQName(namespace, c.subsystem, "info"),
-			"info of /sys/class/power_supply/<power_supply>.",
+			"Power supply information from /sys/class/power_supply.",
 			keys,
 			nil,
 		)
@@ -146,7 +195,7 @@ func (c *powerSupplyClassCollector) Update(ch chan<- prometheus.Metric) error {
 func pushPowerSupplyMetric(ch chan<- prometheus.Metric, subsystem string, name string, value float64, powerSupplyName string, valueType prometheus.ValueType) {
 	fieldDesc := prometheus.NewDesc(
 		prometheus.BuildFQName(namespace, subsystem, name),
-		fmt.Sprintf("%s value of /sys/class/power_supply/<power_supply>.", name),
+		fmt.Sprintf("The %s value of /sys/class/power_supply/<power_supply>.", name),
 		[]string{"power_supply"},
 		nil,
 	)

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)
+			mtime, families, err := c.processFile(path, f.Name())
+			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.
@@ -285,7 +284,7 @@ func (c *textFileCollector) Update(ch chan<- prometheus.Metric) error {
 }
 
 // processFile processes a single file, returning its modification time on success.
-func (c *textFileCollector) processFile(dir, name string, ch chan<- prometheus.Metric) (*time.Time, map[string]*dto.MetricFamily, error) {
+func (c *textFileCollector) processFile(dir, name string) (*time.Time, map[string]*dto.MetricFamily, error) {
 	path := filepath.Join(dir, name)
 	f, err := os.Open(path)
 	if err != nil {