Monitoring a MacOS Host with Prometheus Node Exporter - Revision history

Gyurci08: Gyurci08 moved page Monitoring a macOS Host with Prometheus Node Exporter to Monitoring a MacOS Host with Prometheus Node Exporter

2025-08-29T11:08:45Z

Gyurci08 moved page Monitoring a macOS Host with Prometheus Node Exporter to Monitoring a MacOS Host with Prometheus Node Exporter

← Older revision	Revision as of 11:08, 29 August 2025
(No difference)

Gyurci08 at 11:08, 29 August 2025

2025-08-29T11:08:31Z

Gyurci08 at 10:45, 29 August 2025

2025-08-29T10:45:43Z

← Older revision		Revision as of 10:45, 29 August 2025
Line 1:		Line 1:
	[[Category:MacOS]]		[[Category:MacOS]]
	[[Category:Prometheus]]		[[Category:Prometheus]]
	[[Category:~~Observability~~]]		[[Category:Guides & Tutorials]]

	= Monitoring a macOS Host with Prometheus Node Exporter =		= Monitoring a macOS Host with Prometheus Node Exporter =

Gyurci08 at 10:44, 29 August 2025

2025-08-29T10:44:59Z

← Older revision		Revision as of 10:44, 29 August 2025
Line 1:		Line 1:
	[[Category:MacOS]]		[[Category:MacOS]]
	[[Category:Prometheus]]		[[Category:Prometheus]]
	[[Category:~~Monitoring~~]]		[[Category:Observability]]

	= Monitoring a macOS Host with Prometheus Node Exporter =		= Monitoring a macOS Host with Prometheus Node Exporter =

Gyurci08: Created page with "Category:MacOS Category:Prometheus Category:Monitoring = Monitoring a macOS Host with Prometheus Node Exporter = This guide details the process of installing and configuring the Prometheus Node Exporter on a macOS machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring macOS is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive a..."

2025-08-29T10:39:57Z

Created page with "Category:MacOS Category:Prometheus Category:Monitoring = Monitoring a macOS Host with Prometheus Node Exporter = This guide details the process of installing and configuring the Prometheus Node Exporter on a macOS machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring macOS is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive a..."

New page

[[Category:MacOS]]
[[Category:Prometheus]]
[[Category:Monitoring]]

= Monitoring a macOS Host with Prometheus Node Exporter =

This guide details the process of installing and configuring the Prometheus Node Exporter on a macOS machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring macOS is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive alerts for high disk usage.

h2. Initial Setup and Problem Diagnosis
h3. Installation with Homebrew
The standard method for installing Node Exporter on macOS is via the [https://brew.sh/ Homebrew] package manager.

<syntaxhighlight lang="bash">
brew install node_exporter
</syntaxhighlight>

h3. The Problem: False Positive Alerts
After a default installation, Node Exporter will scrape metrics from all mounted filesystems. On macOS, this includes many volumes that are nearly full by design, leading to persistent, non-actionable alerts.

Common sources of these false positives include:
* '''Xcode Simulator Runtimes:''' Mounted under ''/Library/Developer/CoreSimulator/''.
* '''Virtual Filesystems:''' Such as ''/dev'' (devfs).
* '''Automounter Filesystems:''' Such as ''/System/Volumes/Data/home'' (autofs).
* '''Read-only System Snapshots:''' The main ''/'' volume is a sealed, read-only snapshot of the OS.

The goal is to filter these out and only monitor user-managed volumes where disk space is a real concern, primarily ''/System/Volumes/Data''.

h2. Configuration and Troubleshooting
The solution involves a two-part strategy: configuring Node Exporter to exclude noisy filesystems at the source, and writing a precise PromQL alert that only targets the user-managed data volume.

h3. Step 1: Configure Node Exporter Exclusions
Node Exporter can be configured to ignore specific mount points using a command-line flag. When installed with Homebrew, these flags should be placed in a dedicated arguments file.

# '''Create or Edit the Arguments File:''' This file is read by the `brew services` launch agent. It should contain one argument per line, '''without quotes'''.
<syntaxhighlight lang="bash">
nano /opt/homebrew/etc/node_exporter.args
</syntaxhighlight>

# '''Add the Exclusion Rule:''' To comprehensively filter out all known OS-managed, virtual, and temporary filesystems, add the following line to the file.
<syntaxhighlight lang="text">
--collector.filesystem.mount-points-exclude=^/(dev|private/var/folders|System/Volumes/(Preboot|Update|VM|Recovery|Hardware|xarts|iSCPreboot)|Library/Developer/CoreSimulator/.*)$
</syntaxhighlight>
This regular expression tells Node Exporter to ignore any filesystem whose mount point matches these patterns.

# '''Restart the Service:''' Apply the new configuration by restarting the Node Exporter service.
<syntaxhighlight lang="bash">
brew services restart node_exporter
</syntaxhighlight>

h3. Step 2: Validate the Configuration
After restarting, verify that the noisy filesystems are no longer being exported. The following command queries the metrics endpoint and greps for the excluded patterns.

<syntaxhighlight lang="bash">
curl -s http://localhost:9100/metrics | grep -E 'mountpoint="/(dev|private/var/folders|System/Volumes/(Preboot|Update|VM|Recovery)|Library/Developer/CoreSimulator/.*)"'
</syntaxhighlight>

'''A successful configuration will result in no output from this command.'''

h3. Step 3: Create a Precise PromQL Alert
With the metrics now clean, the final step is to create an alerting rule in Prometheus that is both simple and impossible to trigger with a false positive. Instead of excluding filesystems in the query, you should explicitly ''include'' only the volume you care about.

The most critical user-managed filesystem on macOS is ''/System/Volumes/Data''.

'''Recommended PromQL Alerting Rule:'''
This query calculates the percentage of used space for the '''Data''' volume and will fire only if it exceeds 90%.

<syntaxhighlight lang="promql">
100 - (node_filesystem_avail_bytes{mountpoint="/System/Volumes/Data"} / node_filesystem_size_bytes{mountpoint="/System/Volumes/Data"}) * 100 > 90
</syntaxhighlight>

By following this guide, you achieve a robust monitoring setup for macOS that provides clean data and generates alerts that are always actionable.

← Older revision		Revision as of 11:08, 29 August 2025
Line 3:		Line 3:
	[[Category:Guides & Tutorials]]		[[Category:Guides & Tutorials]]

	= Monitoring a ~~macOS~~ Host with Prometheus Node Exporter =		= Monitoring a MacOS Host with Prometheus Node Exporter =

	This guide details the process of installing and configuring the Prometheus Node Exporter on a ~~macOS~~ machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring ~~macOS~~ is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive alerts for high disk usage.		This guide details the process of installing and configuring the Prometheus Node Exporter on a MacOS machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring MacOS is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive alerts for high disk usage.

	h2. Initial Setup and Problem Diagnosis		h2. Initial Setup and Problem Diagnosis
	h3. Installation with Homebrew		h3. Installation with Homebrew
	The standard method for installing Node Exporter on ~~macOS~~ is via the [https://brew.sh/ Homebrew] package manager.		The standard method for installing Node Exporter on MacOS is via the [https://brew.sh/ Homebrew] package manager.

	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
Line 16:		Line 16:

	h3. The Problem: False Positive Alerts		h3. The Problem: False Positive Alerts
	After a default installation, Node Exporter will scrape metrics from all mounted filesystems. On ~~macOS~~, this includes many volumes that are nearly full by design, leading to persistent, non-actionable alerts.		After a default installation, Node Exporter will scrape metrics from all mounted filesystems. On MacOS, this includes many volumes that are nearly full by design, leading to persistent, non-actionable alerts.

	Common sources of these false positives include:		Common sources of these false positives include:
Line 60:		Line 60:
	With the metrics now clean, the final step is to create an alerting rule in Prometheus that is both simple and impossible to trigger with a false positive. Instead of excluding filesystems in the query, you should explicitly ''include'' only the volume you care about.		With the metrics now clean, the final step is to create an alerting rule in Prometheus that is both simple and impossible to trigger with a false positive. Instead of excluding filesystems in the query, you should explicitly ''include'' only the volume you care about.

	The most critical user-managed filesystem on ~~macOS~~ is ''/System/Volumes/Data''.		The most critical user-managed filesystem on MacOS is ''/System/Volumes/Data''.

	'''Recommended PromQL Alerting Rule:'''		'''Recommended PromQL Alerting Rule:'''
Line 69:		Line 69:
	</syntaxhighlight>		</syntaxhighlight>

	By following this guide, you achieve a robust monitoring setup for ~~macOS~~ that provides clean data and generates alerts that are always actionable.		By following this guide, you achieve a robust monitoring setup for MacOS that provides clean data and generates alerts that are always actionable.