macOS

Plugin: macos.plugin Module: mach_smi

Overview

Monitor macOS metrics for efficient operating system performance, power sources, thermal pressure, sensors, fans, storage, and networking.

The plugin uses eight different methods to collect data:

• The function sysctlbyname is called to collect network, swap, loadavg, and boot time.
• The function host_statistics is called to collect CPU and virtual memory data.
• The function IOServiceGetMatchingServices is called to collect storage information.
• The function IOPSCopyPowerSourcesInfo is called to collect battery and UPS power source data.
• The private Apple IOReport framework is loaded at runtime to collect Apple Silicon GPU utilization, performance-state residency, clock frequency, and power draw without root privileges when macOS exposes the required channels.
• AppleSMC and IOHID are sampled directly to collect hardware temperature, fan, voltage, current, and power sensors without requiring powermetrics.
• The native Apple powermetrics command is sampled in continuous loop mode to collect thermal pressure, plus fallback SMC temperatures, fan speed, and fallback GPU power when the macOS sampler is available.
• The native IOKit NVMe SMART user client is sampled to collect NVMe health data when macOS exposes readable SMART-capable NVMe services.

This collector is only supported on the following platforms:

• macOS

This collector only supports collecting metrics from a single instance of this integration.

Battery, UPS power-source, native Apple Silicon GPU, direct AppleSMC/IOHID hardware sensors, and native NVMe SMART metrics do not require external tools. Apple Silicon GPU metrics use the private IOReport framework loaded at runtime and gracefully disappear when unavailable. Exact thermal pressure and fallback GPU-power readings use the native Apple powermetrics command, which requires netdata to run with sufficient macOS privileges. The default sampler falls back through available sampler sets; without required privileges, the thermal sampler disables itself after repeated startup probe failures.

Default Behavior

Auto-Detection

The collector auto-detects macOS power sources, Apple Silicon IOReport GPU channels, AppleSMC/IOHID hardware sensors, and readable NVMe SMART-capable services, and only creates charts for values exposed by the hardware and operating system.

Limits

Power-source, AppleSMC, IOHID, and NVMe SMART enumeration are capped internally to avoid unexpected chart cardinality. IOReport GPU sampling is in-process and single-device. The powermetrics sampler runs as one long-lived loop process and only publishes newly received samples.

Performance Impact

Power-source, direct IOHID sensor, and IOReport GPU collection are lightweight. AppleSMC sensor key discovery is rate-limited, and AppleSMC sensor values default to a ten-second cadence because AppleSMC reads can generate macOS CoreAnalytics log traffic. Native NVMe SMART reads default to the same ten-second cadence as the existing NVMe collector, while device discovery is rate-limited. Thermal pressure collection keeps one powermetrics process running in loop mode at a configurable output interval, defaulting to once per second.

Setup

Prerequisites

No action required.

Configuration

Options

There are eight sections in the file which you can configure:

• [plugin:macos:sysctl] - Enable or disable monitoring for network, swap, loadavg, and boot time.
• [plugin:macos:mach_smi] - Enable or disable monitoring for CPU and Virtual memory.
• [plugin:macos:iokit] - Enable or disable monitoring for storage device.
• [plugin:macos:power_sources] - Enable or disable battery and UPS power-source metrics.
• [plugin:macos:gpu] - Enable or disable Apple Silicon IOReport GPU monitoring.
• [plugin:macos:sensors] - Configure direct AppleSMC and IOHID hardware sensor monitoring.
• [plugin:macos:powermetrics] - Configure thermal and fan sampling through native Apple powermetrics.
• [plugin:macos:nvme_smart] - Configure native IOKit NVMe SMART sampling.

via File

The configuration file name for this integration is netdata.conf.

The file format is a modified INI syntax. The general structure is:

[section1]
    option1 = some value
    option2 = some other value

[section2]
    option3 = some third value

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config netdata.conf

Examples

Disable swap monitoring

A basic example that discards swap monitoring

[plugin:macos:sysctl]
  system swap = no
[plugin:macos:mach_smi]
  swap i/o = no

Disable complete Machine SMI section

A basic example that discards swap monitoring

[plugin:macos:mach_smi]
  cpu utilization = no
  system ram = no
  swap i/o = no
  memory page faults = no
  disk i/o = no

Disable thermal and fan sampling

Disable the privileged powermetrics sampler while keeping the rest of macos.plugin enabled.

[plugin:macos]
  powermetrics = no

Disable Apple Silicon GPU monitoring

Disable IOReport GPU monitoring while keeping other macOS metrics enabled.

[plugin:macos]
  gpu = no

Disable direct hardware sensor monitoring

Disable direct AppleSMC and IOHID hardware sensor monitoring while keeping the rest of macos.plugin enabled.

[plugin:macos]
  sensors = no

Disable native NVMe SMART sampling

Disable native IOKit NVMe SMART health monitoring while keeping generic disk I/O monitoring enabled.

[plugin:macos]
  nvme smart = no

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per macOS instance

These metrics refer to hardware and network monitoring.

This scope has no labels.

Metrics:

Per gpu

These metrics refer to macOS GPU monitoring.

Labels:

Metrics:

Per power source

These metrics refer to macOS battery and UPS power sources.

Labels:

Metrics:

Per sensor

These metrics refer to macOS battery, CPU, GPU, fan, voltage, current, power, and thermal sensors.

Labels:

Metrics:

Per nvme device

These metrics refer to native macOS NVMe SMART-capable devices.

Labels:

Metrics:

Per disk

This scope has no labels.

Metrics:

Per mount point

This scope has no labels.

Metrics:

Per network device

This scope has no labels.

Metrics:

Alerts

The following alerts are available:

Troubleshooting

GPU charts are missing

Apple Silicon GPU utilization, performance-state residency, clock frequency, and power draw charts require IOReport GPU channels. These channels are exposed by Apple Silicon GPU drivers and are not available on Intel Macs. The collector loads IOReport at runtime and disables the GPU module cleanly when the framework, DVFS table, or GPU channels are unavailable.

GPU power may still appear from powermetrics on systems where the gpu_power sampler exposes a plist gpu_power value and IOReport GPU power is unavailable. GPU temperature uses direct SMC/IOHID reads from the GPU module when available; otherwise, the powermetrics SMC path can still provide the same GPU temperature metric.

Thermal and fan charts are missing

Direct AppleSMC and IOHID hardware sensor charts do not depend on powermetrics. If temperature, fan, voltage, current, or power sensor charts are missing, the hardware or macOS driver may not expose readable AppleSMC or IOHID sensor values, or the [plugin:macos:sensors] module may be disabled.

The thermal pressure state chart depends on the native Apple powermetrics command. On macOS, powermetrics requires superuser privileges, so the default installation runs it through Netdata’s setuid ndsudo helper with hard-coded allow-list entries for the probed sampler sets. Some Macs expose hardware sensors through AppleSMC while refusing powermetrics; in that case, hardware sensor charts can still appear while thermal pressure remains absent. If ndsudo is missing, not setuid root, or the allow-list rejects all startup probe commands, the sampler disables itself after repeated startup failures to avoid log noise. If the running loop exits later, Netdata probes again and restarts loop mode.

Battery, UPS power-source, and IOReport GPU charts do not depend on powermetrics and should still appear when macOS exposes their data.

NVMe health charts are missing

Native NVMe health charts appear only when macOS exposes NVMe SMART-capable services through IOKit and allows the native SMART user client to open them. The collector does not use nvme-cli or any external NVMe tool on macOS.

If generic disk I/O charts are present but NVMe health charts are absent, the device, controller, or macOS driver may not expose a readable native NVMe SMART user client. Some Apple internal Apple Fabric SSDs expose disk I/O and filesystem metrics but not detailed public NVMe health fields.