Orchestrating Ubiquiti Network Observability via UniFi Poller, Prometheus, and Grafana

The pursuit of absolute visibility within a software-defined network ecosystem requires more than just basic uptime monitoring; it necessitates a granular, time-series approach to telemetry. For administrators managing Ubiquiti UniFi environments, the challenge often lies in extracting actionable intelligence from the vast stream of data generated by switches, gateways, and access points. The integration of UniFi Poller—a specialized collector—with powerful observability backends like Prometheus or In

DB, and the visualization powerhouse Grafana, transforms raw network logs into high-fidelity, actionable dashboards. This architectural pattern allows for the monitoring of deep packet inspection (DPI) metrics, client density, and hardware-specific performance metrics across a distributed infrastructure. Whether running on a dedicated Unraid server, a Dockerized Ubuntu instance, or a lightweight LXC container, the deployment of this stack provides a centralized pane of glass for network health, enabling proactive troubleshooting of client roaming, throughput bottlenecks, and interface utilization.

The Architectural Foundation of UniFi Telemetry

The Ubiquiti UniFi ecosystem is built upon a controller-based architecture designed to simplify the configuration and management of diverse networking hardware. This controller acts as the central intelligence, maintaining statistics and managing device states across the network. The flexibility of this controller is significant, as it can be deployed across various operating systems, including Windows, macOS, Linux, and FreeBSD. For more integrated, hardware-centric deployments, Ubiquiti offers the CloudKey, a dedicated hardware device purpose-built to host the controller software.

In modern DevOps and home-lab environments, the emergence of the UniFi Dream Machine (UDM) has expanded the scope of what can be monitored. Despite its recent development status, the UniFi Poller is capable of collecting data from these newer gateway architectures, ensuring that even cutting-edge hardware is included in the observability pipeline.

The core of the monitoring strategy involves three distinct layers:

1. The Collector Layer (UniFi Poller): This component serves as the bridge between the UniFi Controller API and the time-series database. It actively polls the controller for metrics and pushes them to a storage backend.
2. The Storage Layer (Prometheus or InfluxDB): This is the persistent repository for all intercepted network metrics. Prometheus utilizes a pull-based model, while InfluxDB serves as a high-performance time-series database capable of handling massive write volumes from the poller.
3. The Visualization Layer (Grafana): This layer queries the storage backend to render complex, interactive dashboards that represent the network state in real time.

Pre-Deployment Security and User Configuration

Before initiating any automated polling, the security posture of the UniFiOS environment must be addressed. It is a critical best practice to adhere to the principle of least privilege. Directing a third-party poller to use administrative credentials poses an unnecessary risk to the network's integrity.

The configuration process must begin within the UniFiOS interface:

• Navigate to the user management section of the UniFi Controller.
• Create a dedicated service account specifically for the UniFi Poller.
• Assign the "View Only" role to this new user.

By implementing this specific role, the poller can retrieve all necessary telemetry—such as client counts, throughput, and device status—without possessing the permissions required to modify network configurations, delete networks, or alter security settings. This isolation ensures that even if the monitoring stack is compromised, the underlying network infrastructure remains shielded from unauthorized configuration changes.

Implementing the UniFi Pollar Collector

The deployment of the UniFi Poller can be executed within various containerized environments, such as Docker under Ubuntu or within an Unraid ecosystem. A common and efficient deployment pattern involves hosting the poller on the same LXC container or Docker host that is already running other exporters, such as the prometheus-pve-exporter. This consolidation reduces resource overhead and simplifies the network topology.

The installation and configuration process follows a rigorous sequence of steps to ensure the data pipeline remains unbroken.

Configuration of the Poller Environment

Once the container is running, the configuration file must be meticulously edited to point to the correct data sources and credentials.

1. Access the container environment:
   Log in to the specific container where the UniFi Poller is hosted.
2. Modify the InfluxDB parameters:
   If utilizing InfluxDB as the backend, navigate to the InfluxDB section of the configuration file.
   Locate the disable parameter and ensure it is set to false (to enable writing to InfluxDB).
   Update the url in the [unifi] section to reflect the IP address of your UniFiOS instance. It is vital to remove the colon and port number from this specific field, providing only the base IP (e.g., 192.168.X.X).
3. Update Authentication:
   Replace the default credentials with the username of the "View Only" user created during the pre-deployment phase.
4. Commit changes:
   Save the configuration file and exit the editor to ensure the poller can reload the new parameters upon restart.

Integrating with Prometheus

For users opting for a Prometheus-centric architecture, the workflow shifts from a push-based mechanism to a scrape-based mechanism. In this setup, Prometheus is responsible for actively reaching out to the Poller to pull the latest metrics.

The configuration steps for Prometheus are as' follows:

• Access the Prometheus container environment.
• Locate the prometheus.yml configuration file.
• Navigate to the scrape_configs section.
• Add a new entry at the end of the list specifically for the UniFi metrics.
• This entry must define the target (the IP and port of the Poller) and the job name.
• Restart the Prometheus service to apply the new scrape job.

Configuring the InfluxDB Data Source in Grafana

If the architecture utilizes InfluxDB, Grafana must be explicitly configured to communicate with the database. This requires precise entry of the database credentials and the authentication token to prevent connection failures.

The configuration of the InfluxDB data source should be performed via the Grafana web interface using the following parameters:

After entering these details, the "Save & Test" button must be clicked. A successful configuration will trigger a green notification banner stating, "Data Source is Working." Failure to match the Authorization header or the unpollersecret token is a frequent cause of dashboard empty-state errors.

Dashboard Deployment and Specialized Visualization

The true power of this stack is realized through the deployment of pre-built Grafana dashboards. These dashboards are designed to interpret the specific metric tags generated by the UniFi Poller, such as save_dpi or save_sites.

Importing Dashboards via ID

Grafana allows for the rapid deployment of complex visualizations using unique numeric identifiers. To import a dashboard:

• Open the Grafana web interface in your browser.
• Navigate to the "Dashboards" option in the left-hand sidebar.
• Select the "+ Import" button.
• Enter the specific ID for the desired dashboard into the "Import via grafana.com" text field.

Available Dashboard Modules

Depending on the level of detail enabled in your UniFi Controller and the Poller configuration, different dashboards can be utilized. The following table outlines the available modules and their specific requirements:

Dashboard Maintenance and Updates

As the UniFi Poller project evolves, the dashboard JSON files are frequently updated with new features, improved graphing logic, and additional variables. To maintain an optimal monitoring environment, administrators should periodically check for updates.

When an update is available, two strategies exist for implementation:

1. Replacement Method: Import the new version of the dashboard using the same unique identifier. This will overwrite the existing dashboard, which is efficient but will erase any local customizations made to the panels.
2. Parallel Import Method: Import the new version using a different unique identifier. This creates a fresh dashboard alongside the old one. This is the preferred method for advanced users, as it allows for an inspection of the new features and a manual migration of custom-built panels or thresholds before decommissioning the legacy version.

Advanced Troubleshooting and Operational Analysis

The implementation of a monitoring stack is rarely a "set and forget" endeavor. Discrepancies between the UniFi Controller and the Grafana dashboards often stem from configuration mismatches in the poller's ability to scrape specific data points.

If metrics for "Sites" or "DPI" are missing, the investigation should begin at the UniFi Controller configuration level. If the save_dpi flag is not explicitly enabled in the UniFi configuration, the poller will have no data to collect, regardless of how well the Grafana data source is configured. Similarly, if the Prometheus scrape_configs do not correctly target the poller's IP, the "Data Source is Working" status in Grafana might be true, but the actual metric series will be absent from the time-series database.

Furthermore, when managing the InfluxDB Authorization header, any discrepancy in the unpollersecret token will result in an authentication error. This is particularly common in Docker environments where environment variables (such as INFLUXDB_ADMIN_TOKEN) are updated in the container orchestration layer but not reflected in the Grafana dashboard configuration.

Conclusion: The Impact of High-Fidelity Network Observability

The integration of UniFi Poller with Prometheus, InfluxDB, and Grafana represents a significant leap in network management maturity. By moving away from reactive troubleshooting—where an administrator only responds to user complaints about "slow internet"—and toward a proactive, metrics-driven approach, the network becomes a transparent and predictable component of the infrastructure.

The ability to track client DPI allows for the identification of bandwidth-heavy applications before they congest the uplink. Monitoring switch-specific metrics enables the detection of physical layer issues or loop-back conditions in real time. Ultimately, this stack transforms the UniFi controller from a simple management tool into a robust telemetry engine, providing the granular data necessary for maintaining high-availability networks in both professional and enthusiast environments. The complexity of the initial setup is offset by the long-term operational stability and the deep, unprecedented insight into the heartbeat of the network.

Sources

1. Using Prometheus and Grafana to monitor UniFi
2. Grafana Dashboard: UniFi Poller Network Sites InfluxDB
3. Grafana Dashboard: UniFi Poller USW Insights InfluxDB
4. UniFi Network Monitoring using InfluxDB/Grafana on Unraid/Docker
5. UniFi Poller Documentation - Grafana Installation