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

+47 -21
View File
@@ -8,29 +8,26 @@ All notable changes to Jarl are documented here. The format follows
The first version, to be released as 0.1.0.
### Fixed
- The negative-caching warning now uses the effective negative TTL, which
is the smaller of the SOA minimum and the zone's default TTL (RFC 2308).
It explains the real effect (new names can stay invisible to resolvers
that already asked) and gives the command that fixes it. Before, it
fired on the SOA minimum alone and wrongly blamed BIND's resolver cap.
- Problems printed by `jarld check` show zone names without the trailing dot.
- `jarl` now shows the warnings a change introduces when it is applied or
staged, not only on dry runs.
- `jarl check` and `jarl resync` no longer print named-checkconf's routine
"loaded serial" lines, only its errors and warnings.
- `jarl zone list` showed only primary zones: `zone create`'s default
`--type primary` leaked into the list filter through a shared variable.
Hint, secondary, forward and other zones are listed again.
- named-checkconf and named-checkzone output is classified by the tools'
exit code. Their warnings (e.g. `both "recursion no;" and "allow-recursion"
active`) were shown as errors. They are now shown as warnings in the
CLI, `jarld check` and the web UI.
- The `zone_outside_view` error says how to fix it (`--adopt-zones`).
### Added
- **Query statistics** (off by default; `stats` in jarl.yaml, docs/stats.md).
When enabled, Jarl adds a loopback statistics channel and a response log to
named's configuration (merged into existing `logging` and
`statistics-channels` statements) and switches response logging with
`rndc responselog`. jarld aggregates named's counters and the log into a
separate SQLite database: per-minute, hourly and daily counters (queries,
result codes, record types, views, zones, cache hits, upstream latency,
DNSSEC) and hourly and daily top lists (names, clients, NXDOMAIN and
SERVFAIL names, refused clients), each with its own retention. Clients can
be anonymized or excluded. It is shown on a new Statistics page in the web
UI (KPI tiles, queries and failed answers over time, a weekday x hour
heatmap, top lists and breakdowns, each chart with a table view), in
`jarl stats status|summary|top|timeline|heatmap|breakdown`, and in the API
under `/api/v1/stats/`, behind the new `stats` permission. Works with the
bind9 packages of Debian 13 and Ubuntu 26.04.
- At startup jarld brings named's configuration up to date with jarl.yaml
settings that affect it (such as statistics), through the usual checked
pipeline. Files changed by hand are never overwritten.
- **jarld daemon**: REST API (`/api/v1`) and embedded web UI, with SQLite as
the source of truth for the whole BIND configuration. Runs under systemd
(`Type=notify`, sandboxed, unprivileged `jarl` user in group `bind`).
@@ -101,3 +98,32 @@ The first version, to be released as 0.1.0.
- **Documentation**: concepts, install and adoption, configuration, CLI,
API, permissions, ACME, validation, operations and development guides, and
a split-DNS guide for adding views to a server that has none.
### Changed
- `jarl resync` / `jarld resync` refuse to overwrite files that were changed
outside Jarl unless `--force` is given, as documented. Before, they always
overwrote them.
### Fixed
- The negative-caching warning now uses the effective negative TTL, which
is the smaller of the SOA minimum and the zone's default TTL (RFC 2308).
It explains the real effect (new names can stay invisible to resolvers
that already asked) and gives the command that fixes it. Before, it
fired on the SOA minimum alone and wrongly blamed BIND's resolver cap.
- Problems printed by `jarld check` show zone names without the trailing dot.
- `jarl` now shows the warnings a change introduces when it is applied or
staged, not only on dry runs.
- `jarl check` and `jarl resync` no longer print named-checkconf's routine
"loaded serial" lines, only its errors and warnings.
- `jarl zone list` showed only primary zones: `zone create`'s default
`--type primary` leaked into the list filter through a shared variable.
Hint, secondary, forward and other zones are listed again.
- named-checkconf and named-checkzone output is classified by the tools'
exit code. Their warnings (e.g. `both "recursion no;" and "allow-recursion"
active`) were shown as errors. They are now shown as warnings in the
CLI, `jarld check` and the web UI.
- The `zone_outside_view` error says how to fix it (`--adopt-zones`).
- The end-to-end test starts named with `-f` like the Debian unit; with `-g`,
named sends all logging to stderr.