Monitoring Configuration¶

WireBuddy's monitoring settings are split between Settings → WireGuard, Settings → Logs, interface configuration, and environment paths.

Enable Traffic Analysis¶

Use Settings → WireGuard → Traffic Analysis to enable or disable country and ASN analysis. This controls conntrack-based geographic collection and the Traffic page's analysis views.

Per-peer WireGuard counters and operational peer state remain part of normal WireGuard management.

Select Dashboard Interfaces¶

Each WireGuard interface has a Show on Dashboard option. WireBuddy also tracks relevant host-network interfaces used by the dashboard network charts. Historical network data is available through /api/network/stats/history.

Host Conntrack Accounting¶

Country and ASN byte accounting requires the host kernel setting:

sudo sysctl -w net.netfilter.nf_conntrack_acct=1

Persist it on Debian/Ubuntu-like systems with:

echo "net.netfilter.nf_conntrack_acct = 1" | \
  sudo tee /etc/sysctl.d/99-wirebuddy-conntrack.conf

Verify:

cat /proc/sys/net/netfilter/nf_conntrack_acct

The value must be 1. Without it, WireGuard traffic totals can still exist, but country and ASN byte attribution is unavailable.

Sampling¶

Current fixed scheduler intervals are:

Metric	Interval
WireGuard peer counters and handshakes	30 seconds
Country and ASN conntrack counters	30 seconds
Network-interface counters	30 seconds
TSDB maintenance	6 hours
GeoIP update check	7 days

Sampling intervals are not configurable in the current UI or through supported environment variables.

Storage Paths¶

All persistent paths derive from WIREBUDDY_DATA_DIR:

<data-dir>/
├── wirebuddy.db
├── tsdb/
├── dns/
└── geolite2/

The TSDB uses append-oriented series files and compressed archives. SQLite stores settings and peer connection metadata. Do not edit TSDB files while the application is running.

Retention¶

Manage retention under Settings → Logs.

Series	Default	Choices
Traffic metrics	7 days	0, 7, 30, 90, 180, 365 days
DNS query/trend data	7 days	0, 7, 30, 90, 180, 365 days
Speed-test results	365 days	0, 7, 30, 90, 180, 365 days

0 is presented as No Logs/Off. Maintenance enforces retention regularly; the page also provides immediate purge actions.

GeoIP Databases¶

City and ASN databases are downloaded on first use and checked weekly. Default locations are:

<data-dir>/geolite2/GeoLite2-City.mmdb
<data-dir>/geolite2/GeoLite2-ASN.mmdb

Custom paths and download sources are documented under GeoIP environment variables.

Backups¶

Application backups can include metric history for a selected time range. Configure scheduled backups under Settings → Backup. Large TSDB histories increase archive creation time and size.

For a cold filesystem backup:

docker compose --env-file .env -f docker/docker-compose.yml stop wirebuddy
tar -czf wirebuddy-data-backup.tar.gz docker/data/
docker compose --env-file .env -f docker/docker-compose.yml start wirebuddy

Keep the corresponding WIREBUDDY_SECRET_KEY with the recovery procedure.

API Endpoints¶

Read endpoints:

GET /api/wireguard/stats/traffic
GET /api/wireguard/stats/connections
GET /api/wireguard/stats/traffic-by-country
GET /api/wireguard/stats/traffic-by-asn
GET /api/wireguard/stats/tsdb
GET /api/wireguard/stats/peer-metrics
GET /api/network/stats
GET /api/network/stats/history
GET /api/wireguard/speedtest/history
GET /api/wireguard/speedtest/storage

Administrative maintenance endpoints:

PATCH  /api/wireguard/stats/tsdb/retention
DELETE /api/wireguard/stats/tsdb
POST   /api/wireguard/stats/tsdb/maintenance
DELETE /api/wireguard/stats/peer-logs
PATCH  /api/wireguard/speedtest/storage/retention
DELETE /api/wireguard/speedtest/storage

DNS storage and retention are exposed through /api/dns/config, /api/dns/storage, and /api/dns/logs. See API Endpoints for the complete route list.

External Monitoring¶

WireBuddy currently has no native Prometheus exporter, InfluxDB backend, or alert manager. Integrations should consume authenticated REST endpoints and the /health//ready probes or ingest container logs.

Troubleshooting¶

No Historical Traffic¶

Confirm retention is not Off under Settings → Logs.
Confirm active peers have transferred data.
Inspect container logs for TSDB_SAMPLE or scheduler errors.
Verify the data volume is writable.

No Country or ASN Data¶

Enable traffic analysis under Settings → WireGuard.
Enable conntrack accounting on the host.
Confirm both GeoLite2 files exist and are non-empty.
Check logs for COUNTRY_TRAFFIC or GEOIP errors.

Storage Growth¶

Reduce retention under Settings → Logs, then allow maintenance to run or use the explicit purge controls. Review DNS raw-query retention separately from traffic and speed-test history.