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

```sh
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

```sh
go test ./...
go build ./cmd/dnstt_exporter
```