77 lines
2.1 KiB
Markdown
77 lines
2.1 KiB
Markdown
# DNS Probe
|
|
|
|
Prometheus probe to monitor DNS zones.
|
|
|
|
## Installation
|
|
### Simple setup
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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
|
|
```sh
|
|
# 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
|
|
|
|
```yml
|
|
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
|
|
```
|