macos-sensor-exporter

A Prometheus exporter for macOS hardware sensors, including temperature, voltage, current, power, battery, and fan metrics from the System Management Controller (SMC).

English | 简体中文

Features

• Exports macOS hardware sensor metrics in Prometheus format
• Support for multiple sensor types:
  • Temperature (°C)
  • Voltage (V)
  • Current (A)
  • Power (W)
  • Fan speed (RPM)
  • Battery information
• Health check endpoint
• Configurable via CLI flags, config file, or environment variables
• Display sensor information directly in terminal (table, JSON, or ASCII format)

Requirements

• macOS (tested on macOS 10.13+)
• Go 1.22+ (for building from source)
• Root/Administrator privileges may be required to access SMC sensors

Installation

Using Homebrew (Recommended)

# Add the tap
brew tap xykong/tap

# Install
brew install macos-sensor-exporter

# Start as a service (auto-start on boot)
brew services start macos-sensor-exporter

# Or run manually
macos-sensor-exporter start

Manage the service:

# Check service status
brew services list

# Stop the service
brew services stop macos-sensor-exporter

# Restart the service
brew services restart macos-sensor-exporter

# View logs
tail -f $(brew --prefix)/var/log/macos-sensor-exporter.log

From Source

git clone https://github.com/xykong/macos-sensor-exporter.git
cd macos-sensor-exporter
go build -o macos-sensor-exporter .

Using Go Install

go install github.com/xykong/macos-sensor-exporter@latest

Usage

Start the Prometheus Exporter

Start the exporter server on the default port (9101):

./macos-sensor-exporter start

With custom port and metrics path:

./macos-sensor-exporter start --port 8080 --pattern /custom-metrics

With verbose logging:

./macos-sensor-exporter start -v

Show Sensor Information

Display sensor information directly in the terminal:

# ASCII format (default)
./macos-sensor-exporter show

# Table format
./macos-sensor-exporter show -o table

# JSON format
./macos-sensor-exporter show -o json

Configuration

The exporter can be configured using:

1. Command-line flags (highest priority)
2. Environment variables (with VIPER_ prefix)
3. Configuration file (lowest priority)

Configuration File

Create a .macos-sensor-exporter.yaml file in your home directory or current directory:

port: 9101
pattern: /metrics

Or specify a custom config file location:

./macos-sensor-exporter start --config /path/to/config.yaml

Prometheus Configuration

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: 'macos-sensors'
    static_configs:
      - targets: ['localhost:9101']

Exported Metrics

The exporter provides metrics in the following format:

sensor_<category>_<description>_<unit>{index="<number>"} <value>

Example metrics:

sensor_temperature_cpu_die_celsius 45.5
sensor_voltage_cpu_core_volts 1.2
sensor_power_cpu_total_watt 15.3
sensor_fans_speed_rpm{index="0"} 1800
sensor_battery_charge_amperes 2.5

Metric Categories

• Temperature: CPU, GPU, and other component temperatures
• Voltage: CPU core, GPU, and system voltages
• Current: Battery and power supply current
• Power: CPU, GPU, and total system power consumption
• Fans: Fan speeds for all installed fans
• Battery: Battery status and metrics

Endpoints

• /metrics - Prometheus metrics endpoint (default, configurable)
• /healthz - Health check endpoint (returns 200 OK)

Development

Build

make build

Run Tests

go test ./...

Run with Verbose Logging

./macos-sensor-exporter start -v

Architecture

The project structure:

.
├── main.go              # Entry point
├── cmd/                 # CLI commands
│   ├── root.go         # Root command and config
│   ├── start.go        # Start exporter server
│   └── show.go         # Show sensor info
└── exporter/           # Prometheus exporter logic
    └── exporter.go     # Collector implementation

Troubleshooting

Permission Denied

If you encounter permission errors accessing SMC sensors, try running with sudo:

sudo ./macos-sensor-exporter start

No Metrics Available

Ensure your Mac supports SMC sensor access. Some virtualized or older Mac models may have limited sensor availability.

Connection Refused

Check if the port is already in use:

lsof -i :9101

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See LICENSE file for details.

Credits

This project uses:

• iSMC for SMC sensor access
• Prometheus client_golang for metrics export
• Cobra for CLI
• Viper for configuration management

Related Projects

• node_exporter - Prometheus exporter for hardware and OS metrics (Linux)
• iSMC - macOS SMC tool and library