Feature Request
Add network topology metrics from the /topology endpoint to enable network visualization and connectivity monitoring.
Available API Endpoint
GET /proxy/network/v2/api/site/{site}/topology
Sample Response
{
"edges": [
{
"channel": 40,
"downlinkMac": "aa:bb:cc:dd:ee:ff",
"essid": "Home",
"experienceScore": 100,
"networkId": "6711e729be659a441ec8e57d",
"protocol": "ax",
"radioBand": "na",
"type": "WIRELESS",
"uplinkMac": "f4:e2:c6:f7:c3:49"
},
{
"downlinkMac": "11:22:33:44:55:66",
"downlinkPortNumber": 1,
"duplex": "FULL_DUPLEX",
"networkId": "6711e729be659a441ec8e57d",
"rateMbps": 100,
"type": "WIRED",
"uplinkMac": "28:70:4e:85:a9:e9",
"uplinkPortNumber": 2
}
],
"has_unknown_switch": false,
"vertices": [
{
"allowedInVisualProgramming": false,
"default": false,
"mac": "f4:e2:c6:f7:c3:49",
"model": "UAPL6",
"name": "U6+",
"state": 1,
"type": "DEVICE",
"wifiRadios": [
{"channel": 6, "protocol": "ax", "radioBand": "ng"},
{"channel": 40, "protocol": "ax", "radioBand": "na"}
]
},
{
"allowedInVisualProgramming": true,
"mac": "aa:bb:cc:dd:ee:ff",
"name": "Client Device",
"type": "CLIENT",
"unifiDevice": false
}
]
}Proposed Metrics
Topology Summary Metrics
| Metric |
Type |
Description |
Labels |
topology_vertices_total |
Gauge |
Total vertices in topology |
site_name |
topology_edges_total |
Gauge |
Total edges/connections |
site_name |
topology_devices_total |
Gauge |
UniFi devices in topology |
site_name |
topology_clients_total |
Gauge |
Clients in topology |
site_name |
topology_has_unknown_switch |
Gauge |
Unknown switch detected (1/0) |
site_name |
Connection Type Metrics
| Metric |
Type |
Description |
Labels |
topology_connections_wired |
Gauge |
Wired connections count |
site_name |
topology_connections_wireless |
Gauge |
Wireless connections count |
site_name |
topology_connections_by_protocol |
Gauge |
Connections by WiFi protocol |
site_name, protocol (ax/ac/n/g) |
topology_connections_by_band |
Gauge |
Connections by radio band |
site_name, band (2.4GHz/5GHz/6GHz) |
Link Quality Metrics
| Metric |
Type |
Description |
Labels |
topology_link_experience_score |
Gauge |
Link experience score (0-100) |
site_name, uplink_mac, downlink_mac |
topology_link_rate_mbps |
Gauge |
Link rate in Mbps |
site_name, uplink_mac, downlink_mac, type |
topology_wired_full_duplex |
Gauge |
Full duplex links count |
site_name |
Device Connectivity Metrics
| Metric |
Type |
Description |
Labels |
topology_device_connections |
Gauge |
Connections per device |
site_name, device_mac, device_name, device_type |
topology_device_state |
Gauge |
Device state in topology |
site_name, device_mac, device_name |
Wireless Topology Metrics
| Metric |
Type |
Description |
Labels |
topology_ap_clients |
Gauge |
Clients connected to AP |
site_name, ap_mac, ap_name, essid |
topology_ap_channel |
Gauge |
AP channel |
site_name, ap_mac, ap_name, band |
Use Cases
- Network visualization - Build topology maps in Grafana
- Connectivity monitoring - Track device connections
- WiFi distribution - Monitor client distribution across APs
- Link quality - Track experience scores across links
- Change detection - Alert on topology changes
- Capacity planning - Identify overloaded APs/switches
Example Alerting
# Alert on unknown switch detected
unpoller_topology_has_unknown_switch == 1
# Alert on low experience score
unpoller_topology_link_experience_score < 50
# Alert on topology changes
changes(unpoller_topology_edges_total[1h]) > 0
# Alert on AP overload (too many clients)
unpoller_topology_ap_clients > 30
Implementation Notes
- Vertices can be DEVICE or CLIENT type
- Edges represent connections between vertices
- Experience score is 0-100 (higher is better)
- WiFi protocol indicates ax/ac/n/g standard
- Radio bands: ng (2.4GHz), na (5GHz), 6e (6GHz)
