Add optional query statistics

Off by default (stats in jarl.yaml). When enabled, Jarl adds a loopback
statistics channel and a response log to named's configuration (merged
into existing logging/statistics-channels statements) and switches
response logging with rndc responselog, because the responselog option
only counts when named starts. jarld polls named's counters every minute
and tails the response log (resuming after restarts and across
rotation). It stores aggregates, never individual queries, in a separate
SQLite database: per-minute, hourly and daily counters (queries, result
codes, record types, views, zones, cache hits, upstream latency, DNSSEC)
and hourly/daily top lists (names, clients, NXDOMAIN and SERVFAIL names,
refused clients), each with its own retention. Clients can be anonymized
or excluded.

- Web UI: Statistics page with KPI tiles, queries and failed answers over
  time, a weekday x hour heatmap, top lists and breakdowns; SVG charts
  with hover/keyboard readouts, a table view and light/dark palettes
  validated for colour-vision deficiency.
- CLI: jarl stats status|summary|top|timeline|heatmap|breakdown.
- API: /api/v1/stats/*, behind a new "stats" permission resource.
- jarld brings named's configuration up to date with jarl.yaml at
  startup (engine.SyncConfig), never overwriting hand-edited files.
- resync now refuses to overwrite drifted files without force, as
  documented.
- tmpfiles.d creates /var/log/named (allowed by named's AppArmor profile
  on Debian 13 and Ubuntu).
- The e2e harness runs named with -f like the Debian unit.
- docs/stats.md, plus API, CLI, configuration, permissions and README
  updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
abrown38andClaude Opus 5.5 committed 2026-10-07 20:21:34 +00:00
1 parent 0795a1001e
commit 3b7bee67f8
44 files changed
+4163 -42

No files matched your search

+9
View File
@@ -39,6 +39,11 @@ error: www.adbraun.lol has a CNAME, so it can't have any other records (found A)
argon2id, sessions have CSRF protection, logins are rate limited.
* **Audit log** of every login, change and token, with user, token, IP and
outcome.
* **Query statistics** (optional, off by default): queries over time,
busiest hours of the week, top names and clients, NXDOMAIN and refused
queries, record types, cache hit rate. Shown in the web UI and the CLI,
and exportable as JSON. Stored as aggregates in a separate database with
retention you set.
* **Let's Encrypt DNS-01** built in: `jarl acme` plus certbot and acme.sh
hooks, including CNAME delegation to a dedicated ACME zone.
* **Adopts an existing server**: imports named.conf and zone files
@@ -82,6 +87,7 @@ in `/etc/jarl/jarl.yaml` to reach it from your management network.
| [docs/permissions.md](docs/permissions.md) | Users, tokens, grants and roles |
| [docs/views.md](docs/views.md) | Split DNS: adding views to a server that has none |
| [docs/acme.md](docs/acme.md) | Let's Encrypt DNS-01 with certbot and acme.sh |
| [docs/stats.md](docs/stats.md) | Query statistics: enabling, what is collected, retention |
| [docs/validation.md](docs/validation.md) | Every check Jarl makes |
| [docs/operations.md](docs/operations.md) | Backups, drift, failures, recovery, monitoring |
| [docs/development.md](docs/development.md) | Code layout, tests against real BIND, conventions |
@@ -94,6 +100,9 @@ these pages:
* **Dashboard**: named status, adoption, drift, recent changes, open
problems.
* **Statistics** (when enabled): queries over time, failed answers, a
weekday x hour heatmap, top names and clients, and breakdowns. Every chart
has a table view.
* **Zones**: list, create (fields adapt to the zone type), per-zone records
with inline editing and type-specific hints, settings (SOA, TTL, serial
policy, view), options, the generated zone file, and pasting a zone file