The pursuit of total network visibility within a Ubiquiti UniFi ecosystem necessitates moving beyond the standard operational dashboard provided by the UniFi Controller. While the native interface offers essential management capabilities for gateways, switches, and access points, it lacks the historical depth and granular analytical power required for professional-grade troubleshooting and long-term trend analysis. To bridge this gap, engineers and enthusiasts utilize a sophisticated telemetry stack consisting of UnPoller, a specialized Go-based collector, paired with time-series databases like Prometheus or InfluxDB, and the industry-standard visualization engine, Grafana. This architecture allows for the transformation of raw, ephemeral network events into actionable, longitudinal data, enabling the detection of subtle performance degradations, client roaming issues, and interface saturation before they manifest as critical outages.
The Architectural Foundation of UniFi Telemetry
Achieving deep observability requires a multi-layered software stack designed to poll, store, and visualize data. At the heart of this ecosystem lies the UniFi Controller itself, which serves as the primary source of truth for all network hardware, including CloudKeys, Dream Machines, and various UniFi-branded switches and access points.
The UnPoller component acts as the critical intermediary. It is a lightweight application, written in Golang, designed to execute periodic polls against the UniFi Controller API. This polling process typically occurs at 30-second intervals, extracting a massive volume of metrics. A relatively modest network environment—for instance, a setup consisting of two access points, a single switch, a gateway, and approximately 40 connected clients—can generate upwardsore than 3,000 individual metric fields. These fields encompass everything from port-level throughput and client signal strength to complex Deep Packet Inspection (DPI) data.
The secondary layer involves a time-series database, which provides the persistence required for historical analysis. Two primary methodologies exist within the community:
- Prometheus-based architecture: This utilizes a pull-based mechanism where Prometheus scrapes metrics from UnPollar. This setup is ideal for users already integrated into the Prometheus/Grafana ecosystem, often deployed via Docker Compose.
- InfluxDB-based architecture: This involves writing metrics to a structured bucket within InfluxDB. This method is highly effective for users managing larger, more complex datasets through the Flux query language, particularly when using Proxmox or Unraid environments.
The final layer is the visualization layer, provided by Grafana. Grafana queries the underlying database to render interactive dashboards. These dashboards are not merely static charts; they are dynamic interfaces capable of showing real-time status, historical comparisons, and alerting thresholds.
Deployment Strategies via Docker Compose
For modern DevOps-centric environments, deploying the observability stack via Docker Compose is the most efficient and reproducible method. This approach encapsulates all necessary services—UnPoller, Prometheus, Grafana, and Dozzle—into a single, manageable unit.
The deployment process begins with cloning the specialized repository designed for this configuration:
git clone https://github.com/timothystewart6/unpoller-unifi.git
cd unpoller-UniFi
Once the repository is local, the configuration phase is paramount. The integrity of the telemetry depends entirely on the accuracy of the environment variables provided to each container.
Configuring UnPoller Credentials
The unpoller/.env file must be meticulously edited to point to the UniFi Controller. For security reasons, it is highly recommended to create a dedicated local UniFi user account specifically for UnPollar. This account should be granted "read-only" or "view-only" permissions to the network controller to adhere to the principle of least privilege.
The following variables must be defined:
UP_UniFi_CONTROLLER_0_URL: The IP address or hostname of your UniFi Controller (e.g.,https://192.168.10.1).UP_UniFi_CONTROLLER_0_USER: The username of the dedicated UnPoller account.UP_UniFi_CONTROLLER_0_PASS: The password for the dedicated UnPoller account.UP_UniFi_CONTROLLER_0_SITE: The specific site ID (usuallydefault).
Configuring Grafana and Global Settings
Security for the visualization layer must also be addressed. The grafana/.env file contains the administrative credentials for the Grafana web interface.
GF_SECURITY_ADMIN_USER: The desired administrator username.GF_SECURITY_ADMIN_PASSWORD: The desired administrator password.
Furthermore, to ensure that all time-stamped data aligns correctly across logs and metrics, the time zone should be standardized. This can be configured in the .env files for Dozzle, Grafana, Prometheus, and UnPoller using the TZ variable:
TZ=Your/Timezone
Orchestrating the Stack
After all configurations are validated, the stack can be initialized with a single command:
docker-compose up -d
Once the containers are running, the following service endpoints become accessible:
| Service | Access URL | Function |
|---|---|---|
| Grafana | http://localhost:3000 |
Data Visualization and Dashboards |
| Prometheus | http://localhost:9090 |
Metrics Storage and Querying |
| Dozzle | http://localhost:8080 |
Real-time Docker Container Log Viewer |
The default login for Grafana in this specific stack is admin / admin123, though this should be changed immediately via the .env configuration.
Advanced InfluxDB Configuration and Proxmox Integration
In environments utilizing Proxmox or Unraid, a different approach involving InfluxDB is often preferred. This is particularly useful when users want to leverage Proxm/LXC scripts for a more decoupled architecture.
InfluxDB Setup on Proxmox
For users running Proxmox, a streamlined installation of InfluxDB can be achieved using community scripts. This executes a bash command on the Proxmox node to provision a Container (LXC) with InfluxDB pre-installed:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/influxdb.sh)"
Once InfluxDB is operational, the user must perform critical database management tasks:
- Create a new Bucket: A bucket acts as an isolated database instance. Creating a dedicated bucket (e.g.,
unifi) ensures that UniFi telemetry does not mix with other application data. - Generate API Tokens: To allow UnPoller or other services to write to the database, a custom API token must be generated. Within the InfluxDB UI, navigate to API Tokens -> Generate API Token -> Custom API Token.
- Set Permissions: Under the Resources section of the token configuration, both "Read" and "Write" permissions must be enabled for the newly created bucket.
Configuring the Grafana Data Source
Connecting Grafana to InfluxDB requires precise configuration of the Data Source settings. Within the Grafana interface, navigate to Connections -> Data Sources -> Add new data source and select InfluxDB.
The following configuration parameters must be accurately entered:
Name:
influxdb-unifiQuery Language:
Flux(Note: Ensure the dashboard you are using is compatible with Flux; older dashboards may require InfluxQL).- HTTP URL: The IP address and port of your InfluxDB instance (e.g.,
http://10.1.1.32:8086). - Organization: The organization name defined during your InfluxDB setup (e.g.,
thetechcorner). - Token: The custom API token generated in the previous step.
- Default Bucket: The name of your telemetry bucket (e.g.,
unifi).
Dashboard Ecosystem and Metric Deep Dives
The true power of this setup is realized through the deployment of pre-configured Grafana dashboards. These dashboards are mapped to specific UniFi hardware classes, ensuring that the visualization logic matches the available metrics.
Network Sites Dashboard
The "Network Sites" dashboard is the foundational layer of UniFi observability. Since every controller manages at least one site, this should be the first dashboard installed. It provides a high-level overview of the controller's health, including the number of active sites, gateways, and overall connectivity status.
USW Insights Dashboard
For environments utilizing UniFi Switches (USW), the "USW Insights" dashboard provides granular, port-level visibility. This dashboard is essential for monitoring uplink saturation, identifying faulty cables through error rate tracking, and observing PoE (Power over Ethernet) consumption across the switch fabric. It generates a significant amount of data, as it tracks metrics for every individual port on every switch in the network.
Available Dashboard Categories
The ecosystem extends beyond basic site and switch monitoring. Users can find specialized dashboards for:
- Access Points (UAP): Monitoring signal strength (RSSI), client counts, and frequency utilization.
- Gateways: Tracking WAN throughput, VPN tunnels, and firewall hits.
- Clients: Deep dives into individual device behavior, including connection duration and data usage.
- DPI (Deep Packet Inspection): Analyzing application-layer traffic to understand network composition.
- PDU (Power Distribution Units): Monitoring power draw and environmental metrics if applicable.
Troubleshooting and Operational Maintenance
Maintaining a high-performance telemetry stack requires proactive monitoring of the monitoring stack itself.
Log Analysis and Debugging
If metrics are not appearing in Grafana, the first step is to inspect the logs of the UnPoller service. This can be done via the terminal using:
docker-compose logs unpoller
Alternatively, if the Dozzle container is running, the user can access http://localhost:8080 to view a real-time, interactive stream of all container logs, which is significantly more user-friendly for identifying rapid-fire errors.
Handling Rate Limiting and 429 Errors
In larger networks, the sheer volume of requests from UnPoller to the UniFi Controller can occasionally trigger HTTP 429 (Too Many Requests) errors. This occurs when the Controller's API rate-limiting mechanisms are breached. To resolve this, the scraping interval must be increased. This is achieved by modifying the Prometheus configuration file:
prometheus/config/prometheus.yml
Increasing the scrape_interval reduces the frequency of polling, thereby lowering the load on the UniFi Controller at the cost of slightly lower temporal resolution in the charts.
Verification of Connectivity
A common failure point in Docker-based deployments is the inability of the UnPoller container to reach the UniFi Controller over the Docker network. Users must ensure that the UP_UniFi_CONTROLLER_0_URL is reachable from within the container environment and that no firewall rules on the host or the controller are blocking the polling traffic.
Analytical Conclusion
The implementation of a UniFi-Grafana telemetry stack represents a transition from reactive network management to proactive network engineering. By leveraging UnPoller to bridge the gap between the UniFi Controller's API and time-series databases like Prometheus or InfluxDB, administrators gain the ability to perform forensic analysis on network events. The architecture described—utilizing Docker Compose for orchestration, Dozzle for log observability, and specialized Grafana dashboards for hardware-specific insights—provides a scalable framework that can grow from a single-gateway home lab to a multi-site enterprise deployment. While the complexity of managing API tokens, Flux queries, and containerized environments is higher than using native tools, the resulting depth of visibility into port metrics, client roaming, and traffic patterns is indispensable for maintaining high-availability network infrastructures.