Exporter¶
The exporter exposes router metrics in Prometheus format on port 9101.
Only a sample of metrics are currently implemented - contributions are welcome!
It needs the router password (IB_PASSWORD, see Environment variables), and stops straight away if it's missing or the router refuses it. If the router can't be reached, e.g. while it restarts, the exporter keeps trying.
Running it¶
with uv / pip:
with Docker Compose:
Set environment variables in docker-compose.yml, then:
Images are published to Docker Hub as oregonpillow/pyinternetbox:
| Tag | Contents |
|---|---|
latest |
Most recent release |
X.Y.Z, X.Y |
A specific release / the latest patch of a minor |
edge |
Latest commit on master (may be unstable) |
Metrics will be available at http://localhost:9101/metrics.
example Prometheus config:
scrape_configs:
- job_name: "pyinternetbox"
scrape_interval: 30s
metrics_path: /metrics
static_configs:
- targets: ["localhost:9101"]
Traffic metrics: which one to use¶
The router exposes several traffic figures that look similar but measure different things. rx/tx are always from the
router's point of view: rx is what the router received on that interface, tx is what it sent.
| Metric | Interface | What it counts | rx means |
tx means |
Type | Includes wired devices | Includes traffic between home devices |
|---|---|---|---|---|---|---|---|
internetbox_wan_rx_bytes_total / internetbox_wan_tx_bytes_total |
veip0 (XGS-PON fibre, WAN) |
All traffic between your home and the internet, from every device | Downloaded from the internet | Uploaded to the internet | Counter (bytes since router boot) | ✅ | ❌ |
internetbox_wifi_rx_bytes_total / internetbox_wifi_tx_bytes_total |
wl0 (5 GHz), wl1 (2.4 GHz) |
All traffic over each Wi-Fi radio, to the internet and to other devices at home | Sent by Wi-Fi devices (their upload) | Sent to Wi-Fi devices (their download) | Counter (bytes since router boot) | ❌ | ✅ (Wi-Fi devices only) |
internetbox_device_rx_bandwidth_last{day,week,month}_bytes / …_tx_… |
Per device (router device list) | The router's own per-device usage over a rolling window (last 24 h / 7 d / 30 d), recalculated about hourly | Received from the device | Sent to the device | Gauge (rolling total, goes up & down) | ❌ (Wi-Fi devices only) | ❓ not verified |
internetbox_veip_downstream_curr_rate_kbps / internetbox_veip_upstream_curr_rate_kbps |
veip0 (XGS-PON fibre, WAN) |
The link speed the fibre connection is synced at (capacity), not traffic. Constant unless the link resyncs | – | – | Gauge (kbps) | – | – |
Notes:
- "How much did I download today?" →
increase(internetbox_wan_rx_bytes_total[<seconds since midnight>s]). - "How fast am I downloading right now?" →
rate(internetbox_wan_rx_bytes_total[5m]) * 8(bits per second). Theveip_*_curr_rate_kbpsmetrics stay at the line speed (e.g. ~10 Gbit/s) no matter how much you download. - Wired traffic between home devices is not measured anywhere: it is switched by the router's Ethernet switch and
never counted, and per-port Ethernet counters (
eth0-eth4) are not accessible with theadminuser (HTTP 401). - The router's
bridgeinterface is not exported: it only sees traffic routed through the router (i.e. internet traffic, counted again from the LAN side withrx/txswapped), so it duplicates the WAN counters. - Counters restart from zero when the Internet Box reboots; Prometheus'
rate()andincrease()handle this. - The per-device rolling totals are only reported for Wi-Fi devices. The direction of their
rx/txfollows the router's naming and has not been independently verified.
DNS query metrics¶
The router answers the DNS queries of devices that use it as their DNS server (the default). It answers some itself and
passes the rest on to its DNS servers (your provider's, or those set with ibox dns set-upstream-servers). All of these
are counters that count since the router last booted.
| Metric | Labels | What it counts |
|---|---|---|
internetbox_dns_local_answered_total |
Queries the router answered itself, from its cache or its own records | |
internetbox_dns_queries_forwarded_total |
Queries the router passed on to a DNS server | |
internetbox_dns_cache_inserted_total |
Answers added to the router's DNS cache | |
internetbox_dns_cache_live_freed_total |
Answers dropped from the cache before they expired, to make room | |
internetbox_dns_queries_sent_total |
server |
Queries sent to that DNS server |
internetbox_dns_queries_failed_total |
server |
Queries to that DNS server that failed |
internetbox_dns_queries_retried_total |
server |
Queries to that DNS server that were retried |
- "Is my DNS server failing?" →
increase(internetbox_dns_queries_failed_total[1h]) > 0. - The two cache counters stay at 0 while the router's DNS cache is off (see
ibox dns cache). - The router also reports
dns_auth_answered,fallbackanddns_queries_failed_or_retried. They aren't exported: the first two are unclear (always 0 so far), and the last is just failed + retried.
Restart metric¶
internetbox_boots_total counts how often the router has started: after a restart, a firmware upgrade or a power cut.
- "Did the router restart in the last day?" →
increase(internetbox_boots_total[1d]) > 0. ibox nmc reboot-historyshows when and why it started the last 10 times.
Grafana dashboards¶
Dashboards can be found in the Grafana folder.
