Technical Briefing – unbound‑dashboard Repository: https://github.com/moses-y/unbound-dashboard (clone with git clone https://github.com/moses-y/unbound-dashboard)

The Problem

Operators of the recursive DNS resolver Unbound need a ready‑made Grafana view that surfaces resolver health, query statistics, and log streams without building a custom exporter or dashboard from scratch.

What This Does

The repo supplies only artefacts that let you assemble the monitoring stack:

  • info.md – detailed description of each Grafana panel, metric source, and Loki log query.
  • release.md – change log for each dashboard version; the latest release bundles a trimmed grafana.ini and a pre‑filled prometheus.yml.
  • README.md – step‑by‑step install guide for Grafana OSS, Prometheus, the Go‑based Unbound exporter (external to this repo), and Loki.
  • screenshots/ – PNG of the final dashboard (e.g., dashboard-2.3.png) and a short markdown index.

No source code for the exporter or container definitions lives here; the repository is a documentation‑only package that references the exporter code hosted elsewhere.

How It Is Wired

Because the repository contains no executable files, the internal call graph cannot be derived. The only wiring that can be described is the deployment flow documented in README.md:

  1. Grafana is installed (deb package) and started as grafana-server.
  2. Prometheus reads the bundled prometheus.yml, which scrapes the HTTP endpoint exposed by the external Unbound exporter (default http://<host>:9167/metrics).
  3. Loki is configured separately (outside this repo) to ingest Unbound log files; Grafana panels query Loki directly.
  4. The user imports the JSON dashboard (included in the release assets) into Grafana, which then visualises metrics from Prometheus and logs from Loki.

No code in this repository touches the network, filesystem, or external services; all runtime behaviour resides in the external exporter and the standard Grafana/Prometheus/Loki binaries.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/unbound-dashboard
cd unbound-dashboard

# 2. Follow the README steps (example for Raspberry Pi OS)
wget https://dl.grafana.com/oss/release/grafana_11.1.0_arm64.deb
sudo apt install musl               # required for Grafana ≥10.2.3
sudo dpkg -i grafana_11.1.0_arm64.deb
sudo systemctl daemon-reload
sudo systemctl enable --now grafana-server

sudo apt install prometheus
# replace /etc/prometheus/prometheus.yml with the file from the release assets
sudo cp releases/vX.Y.Z/prometheus.yml /etc/prometheus/prometheus.yml
sudo systemctl restart prometheus

# 3. Deploy the external Unbound exporter (see https://github.com/ar51an/unbound-redis)
#    Ensure it listens on port 9167 and is reachable from Prometheus.

# 4. In Grafana UI (http://<RP‑IP>:3000) import the dashboard JSON
#    (provided in the GitHub release assets).

Configuration files: prometheus.yml (in the release assets) and the optional grafana.ini are the only config artefacts shipped. No environment‑variable list is present in the repo.

Real‑World Use

A typical Raspberry Pi 4 DNS resolver runs Unbound, the Go exporter, Prometheus, Loki, and Grafana on the same host. Grafana dashboards give ops staff a single pane showing query rates, cache hit ratios, and error logs, enabling rapid identification of mis‑configurations or upstream failures.

Code Health & Issues

  • Medium – No test files – repository-wide (static analysis).
  • Medium – No CI/CD pipeline – no .github/ workflows or other CI config.
  • Low – No Dockerfile – container builds must be authored externally.
  • Info – License present – LICENSE file included.
  • Info – No lockfile – dependency versions are not pinned in this repo.
  • Info – No committed secrets – static scan found none.

The repo’s scope is strictly documentation; therefore the usual software‑quality metrics (unit tests, CI) are not applicable but should be added if future code (e.g., exporter updates) is stored here.

The Bottom Line

unbound-dashboard delivers a ready‑made Grafana view and the minimal Prometheus/Loki configuration needed to monitor Unbound, but it contains no executable code. It is suitable for teams that already run the external exporter and want a quick, documented way to import the dashboard. Lack of tests, CI, and container support means the repo is low‑maintenance documentation rather than a production‑ready codebase. Engineers should treat it as a reference bundle and manage the actual exporter and deployment tooling separately.