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

README.md

DNS Probe

Prometheus probe to monitor DNS zones.

Installation

Simple setup

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

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 127.0.0.1:8953 --workers 4 'dns_probe:make_app()'

Usage

Examples

# Let the probe find the nameserver list
curl '127.0.0.1:8953/probe?zone=bksp.space'

# Disable IPv6 (both IPv4 and IPv6 are enabled by default)
curl '127.0.0.1:8953/probe?zone=bksp.space&ipv6=no'

# Specify a custom list of nameservers
curl '127.0.0.1:8953/probe?zone=bksp.space&nameservers[]=9.9.9.9&nameservers[]=2620:fe::fe'

API

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

scrape_configs:
  - job_name: dns-probe
    scrape_interval: 1m
    metrics_path: /probe
    static_configs:
    - targets:
      - bksp.space
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_zone
      - source_labels: [__param_zone]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:8953