From b88ef3472756d12ad4764b494a6b9c22bc83222a Mon Sep 17 00:00:00 2001 From: "Eric D. Schabell" Date: Thu, 27 Aug 2026 14:36:23 +0200 Subject: [PATCH] docs: pipeline: inputs: node_exporter_metrics: document macOS stat and thermal_zone Document macOS support for the stat and thermal_zone collectors added to the node exporter metrics input in fluent-bit 5a1300632 and 8556d0368. - Update the macOS default for the metrics option to include stat and thermal_zone, matching NE_DEFAULT_ENABLED_METRICS - Add stat and thermal_zone to the macOS data source sentence in the same description: stat reads sysctl, thermal_zone reads IOKit - Mark the stat collector as available on macOS and note that only boot time is exposed there, read from the kern.boottime sysctl, while forks and interruptions remain Linux-only - Mark the thermal_zone collector as available on macOS and link it to a new macOS thermal metrics section - Add a macOS thermal metrics section listing the four metrics exposed there, since macOS has no /sys/class/thermal equivalent and the metric set differs from Linux - Note that the three cpu_ metrics only appear once the operating system records a CPU power limit, that they are created individually so some can appear before others, and that the ratios are fractions between 0 and 1 rather than percentages - Note that a sensor without a product name is labeled Unknown #N - Re-pad the collectors table so the pipes stay aligned for MD060 after the wider Version column - Note ARM64-only macOS thermal sensors Signed-off-by: Eric D. Schabell --- pipeline/inputs/node-exporter-metrics.md | 69 +++++++++++++++--------- 1 file changed, 44 insertions(+), 25 deletions(-) diff --git a/pipeline/inputs/node-exporter-metrics.md b/pipeline/inputs/node-exporter-metrics.md index aa4ece995..02e39cea9 100644 --- a/pipeline/inputs/node-exporter-metrics.md +++ b/pipeline/inputs/node-exporter-metrics.md @@ -64,7 +64,7 @@ This helps with down-sampling when collecting metrics. | `diskstats.ignore_device_regex` | Specify the regular expression for the` diskstats` to prevent collection of/ignore. | `^(ram\|loop\|fd\|(h\|s\|v\|xv)d[a-z]\|nvme\\d+n\\d+p)\\d+$` | | `filesystem.ignore_filesystem_type_regex` | Specify the regular expression for the `filesystem` types to prevent collection of or ignore. | `^(autofs\|binfmt_misc\|bpf\|cgroup2?\|configfs\|debugfs\|devpts\|devtmpfs\|fusectl\|hugetlbfs\|iso9660\|mqueue\|nsfs\|overlay\|proc\|procfs\|pstore\|rpc_pipefs\|securityfs\|selinuxfs\|squashfs\|sysfs\|tracefs)$` | | `filesystem.ignore_mount_point_regex` | Specify the regular expression for the `mount` points to prevent collection of/ignore. | `^/(dev\|proc\|run/credentials/.+\|sys\|var/lib/docker/.+\|var/lib/containers/storage/.+)($\|/)` | -| `metrics` | Specify which metrics are collected from the host operating system. The available collectors and their data sources depend on the operating system. On Linux, these metrics depend on `/procfs`, `/sysfs`, systemd, or custom files, and the actual values of metrics will be read from `/proc`, `/sys`, or systemd as needed: `cpu`, `cpufreq`, `meminfo`, `diskstats`, `filesystem`, `stat`, `loadavg`, `vmstat`, `netdev`, `netstat`, `sockstat`, `filefd`, `nvme`, and `processes` depend on `procfs`. `cpufreq`, `hwmon`, `thermal_zone`, and `powersupplyclass` depend on `sysfs`. `systemd` depends on systemd services. `timex` depends on the `adjtimex(2)` system call. `textfile` requires explicit path configuration using `collector.textfile.path`. On macOS, the collectors read from native system interfaces instead of `/proc` and `/sys`: `filesystem` uses `getmntinfo`, `diskstats` and `powersupplyclass` use `IOKit`, and `cpu`, `meminfo`, `netdev`, `loadavg`, and `uname` use `sysctl` and related system calls. The default differs by operating system. | Linux: `"cpu,cpufreq,meminfo,diskstats,filesystem,uname,stat,time,timex,loadavg,vmstat,netdev,netstat,sockstat,filefd,systemd,nvme,thermal_zone,hwmon,powersupplyclass"`. macOS: `"cpu,loadavg,meminfo,diskstats,filesystem,uname,netdev,powersupplyclass"` | +| `metrics` | Specify which metrics are collected from the host operating system. The available collectors and their data sources depend on the operating system. On Linux, these metrics depend on `/procfs`, `/sysfs`, systemd, or custom files, and the actual values of metrics will be read from `/proc`, `/sys`, or systemd as needed: `cpu`, `cpufreq`, `meminfo`, `diskstats`, `filesystem`, `stat`, `loadavg`, `vmstat`, `netdev`, `netstat`, `sockstat`, `filefd`, `nvme`, and `processes` depend on `procfs`. `cpufreq`, `hwmon`, `thermal_zone`, and `powersupplyclass` depend on `sysfs`. `systemd` depends on systemd services. `timex` depends on the `adjtimex(2)` system call. `textfile` requires explicit path configuration using `collector.textfile.path`. On macOS, the collectors read from native system interfaces instead of `/proc` and `/sys`: `filesystem` uses `getmntinfo`, `diskstats`, `powersupplyclass`, and `thermal_zone` use `IOKit`, and `cpu`, `meminfo`, `netdev`, `loadavg`, `stat`, and `uname` use `sysctl` and related system calls. The default differs by operating system. | Linux: `"cpu,cpufreq,meminfo,diskstats,filesystem,uname,stat,time,timex,loadavg,vmstat,netdev,netstat,sockstat,filefd,systemd,nvme,thermal_zone,hwmon,powersupplyclass"`. macOS: `"cpu,loadavg,meminfo,diskstats,filesystem,uname,stat,netdev,thermal_zone,powersupplyclass"` | | `path.procfs` | The mount point used to collect process information and metrics. | `/proc` | | `path.rootfs` | The root filesystem mount point. | `/` | | `path.sysfs` | The path in the filesystem used to collect system metrics. | `/sys` | @@ -83,30 +83,49 @@ Most collectors are enabled by default. The `metrics` parameter lists the exact The Version column specifies the Fluent Bit version where the collector is available. -| Name | Description | Operating system | Version | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------|------------------|--------------------------| -| `cpu` | Exposes CPU statistics. | Linux, macOS | 1.8 | -| `cpufreq` | Exposes CPU frequency statistics. | Linux | 1.8 | -| `diskstats` | Exposes disk I/O statistics. | Linux, macOS | 1.8 | -| `filefd` | Exposes file descriptor statistics from `/proc/sys/fs/file-nr`. | Linux | 1.8.2 | -| `filesystem` | Exposes filesystem statistics from `/proc/*/mounts` on Linux, and from `getmntinfo` on macOS. | Linux, macOS | Linux: 2.0.9, macOS: 5.1 | -| `hwmon` | Exposes hardware monitoring metrics from `/sys/class/hwmon`. | Linux | 2.2.0 | -| `loadavg` | Exposes load average. | Linux, macOS | 1.8 | -| `meminfo` | Exposes memory statistics. | Linux, macOS | 1.8 | -| `netdev` | Exposes network interface statistics such as bytes transferred. | Linux, macOS | 1.8.2 | -| `netstat` | Exposes network statistics from `/proc/net/netstat`, including the `TcpExt` and `IpExt` counters. | Linux | 2.2.0 | -| `nvme` | Exposes `nvme` statistics from `/proc`. | Linux | 2.2.0 | -| `powersupplyclass` | Exposes power supply statistics, such as battery capacity and charge state, from `/sys/class/power_supply` on Linux and from `IOKit` on macOS. | Linux, macOS | 5.1 | -| `processes` | Exposes processes statistics from `/proc`. | Linux | 2.2.0 | -| `sockstat` | Exposes socket statistics from `/proc/net/sockstat`. | Linux | 2.2.0 | -| `stat` | Exposes various statistics from `/proc/stat`. This includes boot time, forks, and interruptions. | Linux | 1.8 | -| `systemd` | Exposes statistics from `systemd`. | Linux | 2.1.3 | -| `textfile` | Exposes custom metrics from text files. Requires `collector.textfile.path` to be set. | Linux | 2.2.0 | -| `thermal_zone` | Exposes thermal statistics from `/sys/class/thermal/thermal_zone/*`. | Linux | 2.2.1 | -| `time` | Exposes the current system time. | Linux | 1.8 | -| `timex` | Exposes selected `adjtimex(2)` system call stats. | Linux | 5.1 | -| `uname` | Exposes system information as provided by the `uname` system call. | Linux, macOS | 1.8 | -| `vmstat` | Exposes statistics from `/proc/vmstat`. | Linux | 1.8.2 | +| Name | Description | Operating system | Version | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------------------------| +| `cpu` | Exposes CPU statistics. | Linux, macOS | 1.8 | +| `cpufreq` | Exposes CPU frequency statistics. | Linux | 1.8 | +| `diskstats` | Exposes disk I/O statistics. | Linux, macOS | 1.8 | +| `filefd` | Exposes file descriptor statistics from `/proc/sys/fs/file-nr`. | Linux | 1.8.2 | +| `filesystem` | Exposes filesystem statistics from `/proc/*/mounts` on Linux, and from `getmntinfo` on macOS. | Linux, macOS | Linux: 2.0.9, macOS: 5.1 | +| `hwmon` | Exposes hardware monitoring metrics from `/sys/class/hwmon`. | Linux | 2.2.0 | +| `loadavg` | Exposes load average. | Linux, macOS | 1.8 | +| `meminfo` | Exposes memory statistics. | Linux, macOS | 1.8 | +| `netdev` | Exposes network interface statistics such as bytes transferred. | Linux, macOS | 1.8.2 | +| `netstat` | Exposes network statistics from `/proc/net/netstat`, including the `TcpExt` and `IpExt` counters. | Linux | 2.2.0 | +| `nvme` | Exposes `nvme` statistics from `/proc`. | Linux | 2.2.0 | +| `powersupplyclass` | Exposes power supply statistics, such as battery capacity and charge state, from `/sys/class/power_supply` on Linux and from `IOKit` on macOS. | Linux, macOS | 5.1 | +| `processes` | Exposes processes statistics from `/proc`. | Linux | 2.2.0 | +| `sockstat` | Exposes socket statistics from `/proc/net/sockstat`. | Linux | 2.2.0 | +| `stat` | Exposes various statistics from `/proc/stat` on Linux, including boot time, forks, and interruptions. On macOS, only boot time is exposed, read from the `kern.boottime` `sysctl`. | Linux, macOS | Linux: 1.8, macOS: 5.1.2 | +| `systemd` | Exposes statistics from `systemd`. | Linux | 2.1.3 | +| `textfile` | Exposes custom metrics from text files. Requires `collector.textfile.path` to be set. | Linux | 2.2.0 | +| `thermal_zone` | Exposes thermal statistics from `/sys/class/thermal/thermal_zone/*` on Linux, and from `IOKit` on macOS. See [macOS thermal metrics](#macos-thermal-metrics). | Linux, macOS | Linux: 2.2.1, macOS: 5.1.2 | +| `time` | Exposes the current system time. | Linux | 1.8 | +| `timex` | Exposes selected `adjtimex(2)` system call stats. | Linux | 5.1 | +| `uname` | Exposes system information as provided by the `uname` system call. | Linux, macOS | 1.8 | +| `vmstat` | Exposes statistics from `/proc/vmstat`. | Linux | 1.8.2 | + +### macOS thermal metrics + +macOS support for the `thermal_zone` collector is available in Fluent Bit version 5.1.2 and greater. + +macOS has no `/sys/class/thermal` equivalent, so the collector reads `IOKit` instead and exposes a different set of metrics than it does on Linux: + +| Metric | Description | +| ------ | ----------- | +| `node_thermal_temperature_celsius` | Temperature of a thermal sensor in Celsius. Carries a `sensor` label holding the sensor's product name. | +| `node_thermal_cpu_scheduler_limit_ratio` | Fraction of CPU time available to the scheduler, where `1` means no limit is applied. | +| `node_thermal_cpu_available_cpu` | Number of processors still online, reflecting how many the system has taken offline. | +| `node_thermal_cpu_speed_limit_ratio` | Fraction of the maximum CPU speed the current speed and voltage limits allow, where `1` means no limit is applied. | + +`node_thermal_temperature_celsius` is only reported on ARM64 (Apple silicon) hardware. The collector doesn't read thermal sensors on Intel-based macOS, so the metric is registered but never produces samples there. + +The three `cpu_` metrics come from the operating system's CPU power status, which macOS only reports when a limit has been recorded. They're absent until then, and each is created individually, so you might see some of the three before the others. The ratios are reported as fractions between `0` and `1` rather than as percentages. + +A sensor that doesn't report a product name is labeled `Unknown #N`, where `N` counts the unnamed sensors found during that scrape. ## Threading