pcp-pmda-unifi 1.0.0a0

PCP PMDA for Ubiquiti UniFi network infrastructure monitoring

pcp-pmda-unifi

A Performance Co-Pilot PMDA that exports Ubiquiti UniFi network infrastructure metrics — switch ports, devices, gateways, APs, clients, and more — through the standard PCP toolchain.

Why

PCP already monitors your hosts. This PMDA extends that to your network infrastructure so you can correlate switch port saturation with application latency, track PoE power budgets, and spot flapping clients — all from pmrep, pmlogger, or Grafana via pmproxy.

What You Get

• Per-port switch counters — bytes, packets, errors, drops, PoE power
• Device inventory — model, firmware, uptime, temperature, adoption state
• Gateway metrics — WAN traffic, latency, CPU, memory
• AP radio stats — channel, client count, retries, satisfaction
• Client tracking — hostname, IP, signal, connected port (cardinality-capped)
• Site aggregates — station counts, WAN/LAN/WLAN traffic totals
• Controller health — poll duration, error counts, software version
• DPI categories — optional per-category traffic breakdowns
• Topology graphs — unifi2dot companion tool exports DOT/JSON network maps

Quick Start

Linux

# Install PCP (if not already present)
sudo dnf install pcp python3-pcp          # RHEL/Fedora
sudo apt install pcp python3-pcp          # Debian/Ubuntu

# Install the PMDA
pip install pcp-pmda-unifi
sudo pcp-pmda-unifi-setup install

# Run the interactive installer
cd /var/lib/pcp/pmdas/unifi
sudo ./Install

# Verify
pminfo -f unifi.switch.port.rx_bytes
pmrep -t 5 unifi.switch.port.rx_bytes unifi.switch.port.tx_bytes

macOS (Homebrew)

macOS restricts direct pip install into the system Python. Use a virtual environment instead — the setup script automatically records the venv's site-packages path so PCP's pmpython can find the module at runtime.

# Install PCP
brew install pcp

# Install the PMDA into a venv
python3 -m venv /opt/pcp-pmda-unifi
/opt/pcp-pmda-unifi/bin/pip install pcp-pmda-unifi
sudo /opt/pcp-pmda-unifi/bin/pcp-pmda-unifi-setup install

# Run the interactive installer
cd /var/lib/pcp/pmdas/unifi
sudo ./Install

# Verify
pminfo -f unifi.switch.port.rx_bytes

Documentation

Full documentation is published via GitHub Pages at tallpsmith.github.io/pmunifi — built automatically from the docs/ directory on every push to main using MkDocs Material.

• Getting Started — install and verify in 5 minutes
• Configuration — config file reference
• Metrics Reference — every metric with type and semantics
• Grafana Dashboards — pre-built dashboards for pmproxy
• Architecture — design decisions and internals
• Troubleshooting — common problems and fixes

Grafana Dashboards

Four pre-built dashboards ship in dashboards/ for use with pmproxy as a Grafana datasource. See the Grafana guide.

License

GPL-2.0-or-later — same as PCP itself.