Prometheus exporter for HomeHub 4000 router

README.md

@@ -0,0 +1,93 @@
+# HomeHub 4000 Prometheus Exporter
+
+Prometheus exporter for the [Virgin Plus Vincent](https://www.virginplus.ca/en/support/internet/modem-info-vincent.html) / [Bell HomeHub 4000](https://support.bell.ca/internet/products/home-hub-4000-modem) router. Uses Playwright to scrape the admin UI and expose metrics for Prometheus. Device events are stored in SQLite so other tools can query them independently of Prometheus.
+
+<details>
+<summary><strong>Grafana dashboard (included)</strong></summary>
+
+![Grafana Dashboard](docs/grafana-dashboard.png)
+</details>
+
+<details>
+<summary><strong>Architecture diagram</strong></summary>
+
+```mermaid
+flowchart LR
+    subgraph exporter.py
+        direction TB
+        prom[Prometheus Server]
+        scraper[router_scraper.py]
+        poller[router_log_fetcher.py]
+    end
+
+    subgraph Router["HomeHub 4000"]
+        mon["/monitoring"]
+        stats["/statistics"]
+        logs["/logs"]
+    end
+
+    scraper --> mon
+    scraper --> stats
+    poller --> logs
+    poller --> db[(SQLite)]
+```
+</details>
+
+## Quick Start
+
+```bash
+# Install
+uv sync
+uv run playwright install chromium
+
+# Run
+ROUTER_PASSWORD="your_password" uv run python src/exporter.py
+
+# Check
+curl http://localhost:9100/metrics | grep homehub_
+```
+
+## Docker
+
+```bash
+cd deploy
+echo "ROUTER_PASSWORD=your_password" > .env
+docker-compose up -d
+```
+
+Services:
+- Exporter: http://localhost:9100/metrics
+- Prometheus: http://localhost:9090
+- Grafana: http://localhost:3000 (pre-configured dashboard included)
+
+Default Grafana credentials are `admin/admin`. Override with `GRAFANA_ADMIN_USER` and `GRAFANA_ADMIN_PASSWORD` in `.env`.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ROUTER_PASSWORD` | (required) | Router admin password |
+| `ROUTER_IP` | 192.168.2.1 | Router IP address |
+| `EXPORTER_PORT` | 9100 | Metrics port |
+| `SCRAPE_INTERVAL` | 60 | Seconds between scrapes |
+| `LOG_POLL_INTERVAL` | 75 | Seconds between log polls |
+| `HEADLESS_BROWSER` | true | Run browser headless |
+
+## Metrics
+
+All metrics prefixed with `homehub_`. Covers system health (CPU, memory, load), network interfaces (status, throughput, errors), connected devices, router uptime, and log statistics. See the Grafana dashboard screenshot above or query `curl localhost:9100/metrics | grep homehub_` for the full list.
+
+## Development
+
+```bash
+uv sync        # includes dev dependencies
+uv run pytest
+uv run ruff check src/
+```
+
+## Troubleshooting
+
+- Set `HEADLESS_BROWSER=false` to watch the browser and debug scraping issues
+- Delete `virgin_monitor.db` to reset device history
+
+Tested on Virgin Plus Vincent (Bell HomeHub 4000), firmware 2.13, UI 7.3.29.