dnstt_exporter/README.md

dnstt_exporter

Prometheus exporter for DNSTT client/session metrics.

dnstt_exporter observes DNSTT DNS traffic on a local Linux host and exports aggregate Prometheus metrics. It does not proxy, terminate, or configure DNSTT; it passively decodes DNSTT session IDs from DNS query names.

Usage

sudo dnstt_exporter \
  -dnstt.domain tunnel.example.com \
  -dnstt.port 53 \
  -geoip.country-database /path/to/GeoLite2-Country.mmdb \
  -geoip.asn-database /path/to/GeoLite2-ASN.mmdb \
  -web.listen-address :9713

The exporter needs permission to open an AF_PACKET raw socket. Run it as root or grant the binary CAP_NET_RAW.

Metrics are served at http://127.0.0.1:9713/metrics by default.

How It Works

dnstt_exporter opens a Linux AF_PACKET raw socket and passively watches UDP DNS traffic on the configured DNSTT port. It parses IPv4 and IPv6 packets, matches DNS query names against the configured DNSTT domain, and decodes the DNSTT session ID from the query-name prefix.

The exporter treats a session as active when it has seen a query for that session within the last 30 seconds. Peak client counts are the highest active session counts observed since the exporter started.

GeoIP labels are based on the resolver address seen by the server. For incoming queries this is the packet source address; for outgoing responses it is the packet destination address. This may be a recursive resolver such as an ISP DNS server, Cloudflare, Google, or Quad9, not the original DNSTT client.

The exporter does not run dnstt-server, proxy traffic, terminate DNSTT, or decrypt tunnel payloads.

Metrics

All DNSTT metrics use a domain label. If -geoip.country-database is set, metrics also include country. If -geoip.asn-database is set, metrics also include asn. Unmapped countries use ZZ; unmapped ASNs use 0.

• dnstt_active_clients
• dnstt_peak_clients
• dnstt_queries_total
• dnstt_bytes_in_total
• dnstt_bytes_out_total
• dnstt_sessions_total

Development

go test ./...
go build ./cmd/dnstt_exporter