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>

internal/config/config.go

@@ -7,6 +7,7 @@ import (
 	"net/netip"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"time"
 
@@ -27,6 +28,7 @@ type Config struct {
 	Session        Session  `yaml:"session"`
 	BIND           BIND     `yaml:"bind"`
 	Audit          Audit    `yaml:"audit"`
+	Stats          Stats    `yaml:"stats"`
 }
 
 // TLS configures HTTPS.
@@ -69,6 +71,44 @@ type Audit struct {
 	RetentionDays int `yaml:"retention_days"`
 }
 
+// Stats configures query statistics. When enabled, Jarl makes named publish
+// its counters on a local statistics channel and log every response to a
+// file, and jarld aggregates both into a separate database.
+type Stats struct {
+	Enabled bool `yaml:"enabled"`
+	// QueryLog enables per-query data (top names and clients, per-view and
+	// per-zone counts) from named's response log. Without it only named's
+	// own counters are collected.
+	QueryLog bool `yaml:"query_log"`
+	// Database is the statistics database, kept apart from Jarl's
+	// configuration database.
+	Database string `yaml:"database"`
+	// StatisticsChannel is the address named serves its counters on
+	// (only reachable from this host).
+	StatisticsChannel string `yaml:"statistics_channel"`
+	// LogFile is where named logs responses. named's AppArmor profile
+	// allows writing under /var/log/named.
+	LogFile     string         `yaml:"log_file"`
+	LogSize     string         `yaml:"log_size"`
+	LogVersions int            `yaml:"log_versions"`
+	Retention   StatsRetention `yaml:"retention"`
+	// TopN is how many names and clients are kept per hour and per day.
+	TopN int `yaml:"top_n"`
+	// AnonymizeClients stores client networks (IPv4 /24, IPv6 /48)
+	// instead of addresses.
+	AnonymizeClients bool `yaml:"anonymize_clients"`
+	// ExcludeClients are addresses or prefixes whose queries are not
+	// counted per name or client (e.g. monitoring probes).
+	ExcludeClients []string `yaml:"exclude_clients"`
+}
+
+// StatsRetention says how long each resolution of the statistics is kept.
+type StatsRetention struct {
+	Minute Duration `yaml:"minute"`
+	Hour   Duration `yaml:"hour"`
+	Day    Duration `yaml:"day"`
+}
+
 // Duration is a time.Duration written as "15s" or "12h" in YAML. Days
 // ("30d") are accepted too.
 type Duration time.Duration
@@ -122,6 +162,16 @@ func Default() *Config {
 			RNDC:           "/usr/sbin/rndc",
 			ReloadTimeout:  Duration(15 * time.Second),
 		},
+		Stats: Stats{
+			QueryLog:          true,
+			Database:          "/var/lib/jarl/stats.db",
+			StatisticsChannel: "127.0.0.1:8058",
+			LogFile:           "/var/log/named/jarl-responses.log",
+			LogSize:           "20m",
+			LogVersions:       2,
+			Retention:         StatsRetention{Minute: Duration(7 * 24 * time.Hour), Hour: Duration(90 * 24 * time.Hour), Day: Duration(730 * 24 * time.Hour)},
+			TopN:              100,
+		},
 	}
 }
 
@@ -166,6 +216,9 @@ func (c *Config) check() error {
 	default:
 		return fmt.Errorf("session.cookie_secure must be auto, always or never")
 	}
+	if err := c.Stats.check(); err != nil {
+		return fmt.Errorf("stats: %w", err)
+	}
 	switch c.Log.Format {
 	case "text", "json":
 	default:
@@ -174,6 +227,51 @@ func (c *Config) check() error {
 	return nil
 }
 
+func (s *Stats) check() error {
+	if !s.Enabled {
+		return nil
+	}
+	if s.Database == "" || !filepath.IsAbs(s.Database) {
+		return fmt.Errorf("database must be an absolute path")
+	}
+	ap, err := netip.ParseAddrPort(s.StatisticsChannel)
+	if err != nil {
+		return fmt.Errorf("statistics_channel %q must be ADDRESS:PORT, e.g. 127.0.0.1:8058", s.StatisticsChannel)
+	}
+	if !ap.Addr().IsLoopback() {
+		return fmt.Errorf("statistics_channel must be a loopback address (named's counters must not be reachable from the network)")
+	}
+	if s.QueryLog {
+		if !filepath.IsAbs(s.LogFile) {
+			return fmt.Errorf("log_file must be an absolute path")
+		}
+		if strings.ContainsAny(s.LogFile, "\"\n") {
+			return fmt.Errorf("log_file contains invalid characters")
+		}
+		if !logSizeRe.MatchString(s.LogSize) {
+			return fmt.Errorf("log_size %q must be a size such as 20m or 1g", s.LogSize)
+		}
+		if s.LogVersions < 1 || s.LogVersions > 100 {
+			return fmt.Errorf("log_versions must be between 1 and 100")
+		}
+	}
+	r := s.Retention
+	if r.Minute < Duration(time.Hour) || r.Hour < Duration(24*time.Hour) || r.Day < Duration(24*time.Hour) {
+		return fmt.Errorf("retention must keep minutes for at least 1h, hours and days for at least 1d")
+	}
+	if s.TopN < 10 || s.TopN > 10000 {
+		return fmt.Errorf("top_n must be between 10 and 10000")
+	}
+	for _, p := range s.ExcludeClients {
+		if _, err := ParsePrefix(p); err != nil {
+			return fmt.Errorf("exclude_clients: %v", err)
+		}
+	}
+	return nil
+}
+
+var logSizeRe = regexp.MustCompile(`^[0-9]+[kKmMgG]?$`)
+
 // ParsePrefix parses an address or prefix.
 func ParsePrefix(s string) (netip.Prefix, error) {
 	if strings.Contains(s, "/") {
@@ -254,4 +352,26 @@ bind:
 audit:
   # Delete audit events older than this many days (0 keeps them forever).
   retention_days: 0
+
+# Query statistics (docs/stats.md). Off by default. When enabled, Jarl makes
+# named publish its counters on a local statistics channel and log every
+# response, and jarld aggregates both into a separate database. Changing
+# this section takes effect when jarld restarts (it rewrites named.conf).
+stats:
+  enabled: false
+  # Per-query data (top names and clients, per view and zone). false
+  # collects only named's own counters, with no logging overhead.
+  query_log: true
+  database: /var/lib/jarl/stats.db
+  statistics_channel: 127.0.0.1:8058
+  log_file: /var/log/named/jarl-responses.log
+  log_size: 20m
+  log_versions: 2
+  retention:
+    minute: 7d     # per-minute counters
+    hour: 90d      # hourly counters and top lists
+    day: 730d      # daily counters and top lists
+  top_n: 100       # names and clients kept per hour and per day
+  anonymize_clients: false   # store 10.10.0.0/24 instead of 10.10.0.37
+  exclude_clients: []        # e.g. [127.0.0.1] to ignore local monitoring
 `

internal/config/config_test.go

@@ -43,3 +43,31 @@ func TestLoad(t *testing.T) {
 		t.Errorf("missing file with allowMissing: %v", err)
 	}
 }
+
+func TestStatsConfig(t *testing.T) {
+	d := Default()
+	if d.Stats.Enabled || !d.Stats.QueryLog || d.Stats.TopN != 100 || time.Duration(d.Stats.Retention.Hour) != 90*24*time.Hour {
+		t.Errorf("defaults = %+v", d.Stats)
+	}
+	dir := t.TempDir()
+	path := filepath.Join(dir, "jarl.yaml")
+	for _, tc := range []struct {
+		yaml string
+		ok   bool
+	}{
+		{"stats: {enabled: true}", true},
+		{"stats: {enabled: true, query_log: false, retention: {minute: 2d}}", true},
+		{"stats: {enabled: true, statistics_channel: 0.0.0.0:8058}", false}, // must be loopback
+		{"stats: {enabled: true, statistics_channel: localhost}", false},
+		{"stats: {enabled: true, log_size: lots}", false},
+		{"stats: {enabled: true, retention: {minute: 10m}}", false},
+		{"stats: {enabled: true, exclude_clients: [not-an-ip]}", false},
+		{"stats: {enabled: false, statistics_channel: nonsense}", true}, // only checked when enabled
+	} {
+		os.WriteFile(path, []byte(tc.yaml+"\n"), 0o644)
+		_, err := Load(path, false)
+		if (err == nil) != tc.ok {
+			t.Errorf("%s: err = %v, want ok=%v", tc.yaml, err, tc.ok)
+		}
+	}
+}