macOS Process Exporter is a lightweight Prometheus exporter for macOS. It exposes per-process
metrics on a /metrics endpoint for easy scraping by Prometheus, including CPU usage, memory,
threads, start time, and open file descriptors. Processes are filtered by exact name, PID, or
command-line regex to keep cardinality manageable.
This project was created because macOS does not use /proc so the standard linux process-exporter
does not work. I build this implementation to allow monitoring process running on my mac servers.
This exporter goes further then other implementations by including process filtering options to
reduce junk data flowing into your Prometheus database.
- Go 1.24+ (if you intend to build from source)
- A macOS host with permission to inspect target processes
go install github.com/Digital-Shane/macos-process-exporter@latestmacos-process-exporter \
--listen-address 127.0.0.1:9105 \
--collection-interval 15s \
--include-name postgresFor local debugging, collect once and print metrics directly:
macos-process-exporter --once| Flag | Description | Default |
|---|---|---|
| --listen-address | HTTP bind address for the exporter. | 127.0.0.1:9105 |
| --collection-interval | Background collection interval. | 15s |
| --include-name | Repeatable or comma-separated exact-name allowlist. | none |
| --exclude-name | Repeatable or comma-separated exact-name denylist. | none |
| --include-pid | Repeatable or comma-separated PID allowlist. | none |
| --include-cmdline-regex | Repeatable or comma-separated regex allowlist for full command lines. | none |
| --min-cpu-percent | Only include processes whose sampled CPU percent meets this minimum. | 0 |
| --min-memory-mb | Only include processes whose resident memory meets this minimum in decimal MB. | 0 |
| --log-level | Process scanner log level: debug, info, warn, error. |
info |
| --once | Collect once, print metrics, and exit. | false |
An example launchd plist is provided at deployments/launchd/com.example.macos-process-exporter.plist.
go install places the binary in your $GOPATH/bin (typically ~/go/bin). Copy it to a
system-wide location so launchd can find it:
sudo cp "$(go env GOPATH)/bin/macos-process-exporter" /usr/local/bin/Review the plist and adjust any flags to your needs (listen address, collection interval,
include/exclude filters, etc.). The provided example monitors all processes on 127.0.0.1:9105
with a 15-second collection interval.
Copy the plist into ~/Library/LaunchAgents (current user) or /Library/LaunchDaemons
(system-wide):
# Current user (runs when you log in)
cp deployments/launchd/com.example.macos-process-exporter.plist ~/Library/LaunchAgents/
# Or system-wide (runs at boot, requires sudo)
sudo cp deployments/launchd/com.example.macos-process-exporter.plist /Library/LaunchDaemons/# Current user
launchctl load ~/Library/LaunchAgents/com.example.macos-process-exporter.plist
# Or system-wide
sudo launchctl load /Library/LaunchDaemons/com.example.macos-process-exporter.plist# Check the service is running
launchctl list | grep macos-process-exporter
# Confirm metrics are being served
curl http://127.0.0.1:9105/metrics# Stop
launchctl unload ~/Library/LaunchAgents/com.example.macos-process-exporter.plist
# Restart (unload then load)
launchctl unload ~/Library/LaunchAgents/com.example.macos-process-exporter.plist
launchctl load ~/Library/LaunchAgents/com.example.macos-process-exporter.plist
# View logs
tail -f /tmp/macos-process-exporter.stdout.log
tail -f /tmp/macos-process-exporter.stderr.logAll per-process metrics are gauges keyed by pid and process_name. Collector metrics have no labels.
| Metric | Description |
|---|---|
macos_process_cpu_percent |
CPU usage percentage over the most recent collection interval. Values may exceed 100 on multicore systems. |
macos_process_resident_memory_bytes |
Resident set size in bytes. |
macos_process_virtual_memory_bytes |
Virtual memory size in bytes. |
macos_process_collector_duration_seconds |
Duration of the most recent collection pass. |
macos_process_collector_success |
1 if the last collection pass completed successfully, else 0. |
macos_processes_observed |
Number of processes seen during the most recent collection pass. |
Example output:
macos_process_cpu_percent{pid="123",process_name="postgres"} 14.2
macos_process_resident_memory_bytes{pid="123",process_name="postgres"} 9.6155648e+07
macos_process_threads{pid="123",process_name="postgres"} 19
macos_process_collector_duration_seconds 0.041
macos_process_collector_success 1
macos_processes_observed 184
A detailed list of changes and release notes is maintained in CHANGELOG.md.
Project uses MIT License, view the full details in the LICENSE file.