dnscrypt-proxy-logs-analyzer 1.0.0

Converts dnscrypt-proxy query_log TSV values to Prometheus-compatible metrics.

dnscrypt-proxy-logs-analyzer

Converts the dnscrypt-proxy query log into Prometheus metrics, suitable for the node_exporter textfile collector.

This is particularly useful on Debian 13 and similar distros, where dnscrypt-proxy is shipped without built-in Prometheus metrics and without the old --analyze-logs tool.

This script restores observability without replacing packages or running additional daemons.

Target audience: mostly me, probably future me, and maybe you.

Features

• Designed for dnscrypt-proxy 2.1.x (as packaged by Debian/Ubuntu).
• No daemon / no exporter HTTP listener — works via textfile collector.
• Tracks per-qtype and per-upstream query stats.
• Persists statistics across restarts (does not reset per run).
• Requires zero logrotate configuration — logs are truncated automatically.
• Zero external dependencies besides prometheus_client (and optionally argcomplete).

Install

pip install dnscrypt_proxy_logs_analyzer

Optinally, for CLI completion, install argcomplete package.

Requirements

Your dnscrypt-proxy must be configured to log TSV format, which this script parses.

Add to /etc/dnscrypt-proxy/dnscrypt-proxy.toml:

[query_log]
file = '/var/log/dnscrypt-proxy/query.log'
format = 'tsv' # REQUIRED

If you enable log rotation externally, disable truncation in this script with --no-trunc flag. By default the script truncates log file after processing.

Usage

dnscrypt-proxy-logs-analyzer \
  --query-log /var/log/dnscrypt-proxy/query.log \
  --output /var/lib/node_exporter/textfile_collector/dnscrypt-proxy.prom

After each run:

• Metrics get updated.
• The query log is truncated.

This makes it safe to run frequently, e.g., every 30 seconds.

systemd timer example

/etc/systemd/system/dnscrypt-proxy-logs-analyzer.service:

[Unit]
Description=Convert dnscrypt-proxy logs to Prometheus metrics
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/dnscrypt-proxy-logs-analyzer

/etc/systemd/system/dnscrypt-proxy-logs-analyzer.timer:

[Unit]
Description=Run dnscrypt-proxy log analyzer periodically

[Timer]
OnBootSec=30s
OnUnitActiveSec=1m
AccuracySec=10s
Unit=dnscrypt-proxy-logs-analyzer.service

[Install]
WantedBy=timers.target

Enable:

systemctl daemon-reload
systemctl enable --now dnscrypt-proxy-logs-analyzer.timer

Check logs for errors (no output by default):

journalctl -u dnscrypt-proxy-logs-analyzer.service -f

Output metrics

Query count

dnscrypt_proxy_queries_total{qtype="A",result="PASS",upstream="scaleway-fr-ipv6"} 42

Latency histogram in seconds

dnscrypt_proxy_latency_seconds_bucket{le="0.1",qtype="A",result="PASS",upstream="scaleway-fr-ipv6"} 18
dnscrypt_proxy_latency_seconds_sum{qtype="A",result="PASS",upstream="scaleway-fr-ipv6"} 0.283
dnscrypt_proxy_latency_seconds_count{qtype="A",result="PASS",upstream="scaleway-fr-ipv6"} 18

Query results tracked include: PASS, NXDOMAIN, NODATA, SERVFAIL, NETWORK_ERROR, TIMEOUT, etc.

Buckets are 0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0.

Self-health metrics

dnscrypt_proxy_logs_analyzer_last_run_timestamp 1.7614262632420218e+09
dnscrypt_proxy_logs_analyzer_last_run_success 1.0

Why this instead of built-in Prometheus metrics?

Because Debian’s dnscrypt-proxy build disables them.

This script provides:

• Observability without replacing the resolver.
• Persistent metrics (survive daemon restarts).
• No running HTTP endpoint.
• No daemon, no background process — runs on a schedule.

Philosophy

“Small, deterministic, zero-maintenance tools beat large monitoring stacks.”

License

MIT License.