varnish_exporter/README.md

Varnish Prometheus Business Exporter

Lightweight Python exporter for Varnish. It exposes /metrics for Prometheus and focuses on per-domain business/operational statistics rather than only raw counters.

Requirements

• Python 3
• varnishstat
• varnishlog
• Access to Varnish shared memory/logs, usually by running as root or with proper permissions

No external Python dependencies are required.

Quick start

Only varnishstat:

python3 varnish_exporter.py --modules core,stat

Test VSL without sampling:

sudo python3 varnish_exporter.py --enable-vsl --vsl-sample 1 --profile full

Recommended production mode:

sudo python3 varnish_exporter.py \
  --port 9131 \
  --enable-vsl \
  --profile standard \
  --vsl-sample 0.001

Then check:

curl -s http://127.0.0.1:9131/metrics | grep varnish_domain

Profiles

• minimal: rps, hit ratio, backend ratio, 5xx ratio, p95 latency
• standard: recommended business-oriented domain statistics
• full: more detailed derived statistics
• raw: full plus raw HTTP counters/histograms

Modules

• core: exporter self metrics
• stat: varnishstat -1 -j
• vsl: varnishlog -g request
• domain: derived per-domain statistics
• raw: raw request counters/histograms

Example:

sudo python3 varnish_exporter.py --modules core,stat,vsl,domain --profile standard

Domain grouping

Use config.example.json as a template:

sudo python3 varnish_exporter.py \
  --config ./config.example.json \
  --enable-vsl \
  --profile standard

If no config is provided, the exporter uses the real Host header as the site label.

Important notes

• Varnish cannot measure real browser render time such as LCP/FCP/DOMContentLoaded.
• Latency here means server-side response time as observed by Varnish.
• For high traffic, avoid --vsl-sample 1 in production.
• Start production with --vsl-sample 0.001 or 0.0001.