Skip to content

About

Prometheus exporter for process level metrics running on macOS.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

macOS Process Exporter

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.


Table of Contents

  1. Getting Started
    1. Prerequisites
    2. Installation
    3. Run the Exporter
  2. Configuration
  3. Deployment
  4. Available Metrics
  5. Contributing
  6. Changelog
  7. License

Getting Started

Prerequisites

  • Go 1.24+ (if you intend to build from source)
  • A macOS host with permission to inspect target processes

Installation

go install github.com/Digital-Shane/macos-process-exporter@latest

Run the Exporter

macos-process-exporter \
  --listen-address 127.0.0.1:9105 \
  --collection-interval 15s \
  --include-name postgres

For local debugging, collect once and print metrics directly:

macos-process-exporter --once

Configuration

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

Deployment

An example launchd plist is provided at deployments/launchd/com.example.macos-process-exporter.plist.

1. Copy the binary to a stable location

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/

2. Edit the plist (optional)

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.

3. Install the plist

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/

4. Load and start the service

# 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

5. Verify

# Check the service is running
launchctl list | grep macos-process-exporter

# Confirm metrics are being served
curl http://127.0.0.1:9105/metrics

Managing the service

# 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.log

Available Metrics

All 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

Changelog

A detailed list of changes and release notes is maintained in CHANGELOG.md.


License

Project uses MIT License, view the full details in the LICENSE file.


Happy monitoring!

About

Prometheus exporter for process level metrics running on macOS.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages