Go to file
Gaël Berthaud-Müller 940efec42a fix wrong return value 2023-09-20 12:38:26 +02:00
dns_probe fix wrong return value 2023-09-20 12:38:26 +02:00
.gitignore add all files 2021-09-17 22:19:05 +02:00
LICENSE Initial commit 2021-09-17 16:17:04 -04:00
README.md update api documentation 2023-09-20 12:21:47 +02:00
pyproject.toml add pyproject.tom 2021-09-17 22:39:40 +02:00
rules.test.yml add alerts examples 2021-09-18 20:32:52 +02:00
rules.yml add alerts examples 2021-09-18 20:32:52 +02:00
setup.cfg add listen option to command line 2021-10-13 22:15:42 +02:00


DNS Probe

Prometheus probe to monitor DNS zones.


Simple setup

python -m venv env
env/bin/pip install git+https://git.bksp.space/BlackSponge/dns-probe.git
env/bin/dns-probe -l

Using a dedicated WSGI server

python -m venv env
env/bin/pip install 'git+https://git.bksp.space/BlackSponge/dns-probe.git#egg=dns_probe[gunicorn]'
env/bin/gunicorn -b --workers 4 'dns_probe:make_app()'



# Let the probe find the nameserver list
curl ''

# Disable IPv6 (both IPv4 and IPv6 are enabled by default)
curl ''

# Specify a custom list of nameservers
curl '[]=[]=2620:fe::fe'


  • GET /probe

    Probe a zone and output Prometheus metrics

    Query parameters:

    • zone (required) the zone to probe.
    • ipv6 (default: yes) enable IPv6, valid values: yes/no.
    • ipv4 (default: yes) enable IPv4, valid values: yes/no.
    • query_timeout (default: 2) timeout for DNS query in seconds.
    • nameservers[] (optional) a list of nameserver to query for the zone. You can repeat this parameter to query multiple servers, if none are provided the probe will try to resolve the nameservers itself. Valid values: IP addresses.

    List of returned metrics:

    Name Type
    dns_probe_resolve_nameservers_success{zone} Gauge (boolean)
    dns_probe_ns_set{nameserver,target,zone} Gauge (info)
    dns_probe_soa_serial{nameserver,zone} Gauge
    dns_probe_soa_rrsig_expiration{keytag,nameserver,zone} Gauge (timestamp)
    dns_probe_query_success{name,nameserver,type} Gauge (boolean)

Prometheus configuration

  - job_name: dns-probe
    scrape_interval: 1m
    metrics_path: /probe
    - targets:
      - bksp.space
      - source_labels: [__address__]
        target_label: __param_zone
      - source_labels: [__param_zone]
        target_label: instance
      - target_label: __address__