Examples¶
This page is a collection of configuration examples for various dns_exporter
usecases.
Configuring dns_exporter
is done with a config file containing modules and referencing those modules in the params
section of the scrape config in prometheus.yml
.
This means that the examples on this page are made up of two parts, the first part being the dns_exporter.yml
configuration for the exporter itself, and the other part being what goes into the scrape_jobs
section of prometheus.yml
.
The configuration snippets on this page are all actively tested in CI so they should be ready to adapt and use.
Monitoring a list of names¶
Usecase¶
Monitor the MX record for a list of domains.
All settings defined in the module
Target used as
query_name
dns_exporter.yml
¶
The module defines the query_type
, family
and the server
to use:
---
modules:
quad9_mx:
query_type: "MX"
server: "dns.quad9.net"
family: "ipv4"
...
prometheus.yml
¶
The scrape job needs to:
Get the list of targets from SD, in this case a list of names/domains.
In
params
setmodule
to the valuequad9_mx
In
relabel_configs
set thequery_name
scrape param to the targetIn
relabel_configs
set the standard__address__
andinstance
labels.In
relabel_configs
set themonitor
label to the exporter address.Remember to also scrape the internal metrics under
/metrics
---
scrape_configs:
- job_name: "dnsexp_internal"
scrape_interval: "10s"
metrics_path: "/metrics"
relabel_configs:
- target_label: "monitor"
replacement: "127.0.0.1:15353"
static_configs:
- targets:
- "127.0.0.1:15353"
- job_name: "dnsexp_quad9_mx"
scrape_interval: "10s"
metrics_path: "/query"
params:
module:
- "quad9_mx"
relabel_configs:
- source_labels: ["__address__"]
target_label: "__param_query_name"
- source_labels: ["__address__"]
target_label: "instance"
- target_label: "__address__"
replacement: "127.0.0.1:15353"
- target_label: "monitor"
replacement: "127.0.0.1:15353"
static_configs:
- targets:
- "gmail.com"
- "outlook.com"
...
Note
Targets can be from any SD, this example uses static_configs
.
This would make Prometheus scrape the MX
records for gmail.com
and outlook.com
every 10 seconds using dns.quad9.net
.
Example Metrics
¶
Note
These metrics are taken directly from the exporter, so they don’t have the Prometheus added instance
and job
labels yet
Metrics returned for target gmail.com
:
# HELP dnsexp_dns_query_time_seconds DNS query time in seconds.
# TYPE dnsexp_dns_query_time_seconds gauge
dnsexp_dns_query_time_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",server="udp://dns.quad9.net:53",transport="UDP"} 0.03361630439758301
# HELP dnsexp_dns_response_rr_ttl_seconds DNS response RR TTL in seconds.
# TYPE dnsexp_dns_response_rr_ttl_seconds gauge
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="5 gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 5.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="20 alt2.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 5.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="10 alt1.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 5.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="40 alt4.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 5.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res730.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="30 alt3.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 5.0
# HELP dnsexp_dns_query_success Was this DNS query successful or not, 1 for success or 0 for failure.
# TYPE dnsexp_dns_query_success gauge
dnsexp_dns_query_success 1.0
# HELP up The value of this Gauge is always 1 when the dns_exporter is up
# TYPE up gauge
up 1.0
Metrics returned for target outlook.com
:
# HELP dnsexp_dns_query_time_seconds DNS query time in seconds.
# TYPE dnsexp_dns_query_time_seconds gauge
dnsexp_dns_query_time_seconds{additional="0",answer="1",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="outlook.com",query_type="MX",rcode="NOERROR",server="udp://dns.quad9.net:53",transport="UDP"} 0.040697336196899414
# HELP dnsexp_dns_response_rr_ttl_seconds DNS response RR TTL in seconds.
# TYPE dnsexp_dns_response_rr_ttl_seconds gauge
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="1",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="outlook.com",query_type="MX",rcode="NOERROR",rr_name="outlook.com.",rr_section="answer",rr_type="MX",rr_value="5 outlook-com.olc.protection.outlook.com.",server="udp://dns.quad9.net:53",transport="UDP"} 300.0
# HELP dnsexp_dns_query_success Was this DNS query successful or not, 1 for success or 0 for failure.
# TYPE dnsexp_dns_query_success gauge
dnsexp_dns_query_success 1.0
# HELP up The value of this Gauge is always 1 when the dns_exporter is up
# TYPE up gauge
up 1.0
Monitoring a list of servers¶
Usecase¶
Monitor a list of DNS servers. The Prometheus targets are the DNS servers and query_name
and query_type
are defined in the module.
dns_exporter.yml
¶
The module defines the query_type
, query_name
and the family
to use:
---
modules:
gmail_mx_v4:
query_type: "MX"
query_name: "gmail.com"
family: "ipv4"
...
prometheus.yml
¶
The scrape job needs to:
Get the list of targets from SD, in this case a list of DNS servers.
In
params
setmodule
to the valuegmail_mx_v4
In
relabel_configs
set theserver
scrape param to the targetIn
relabel_configs
set the standard__address__
andinstance
labelsIn
relabel_configs
set themonitor
label to the exporter address.Remember to also scrape the internal metrics under
/metrics
With the dns_exporter
running at dnsexp.example.com:15353
:
---
scrape_configs:
- job_name: "dnsexp_internal"
scrape_interval: "10s"
metrics_path: "/metrics"
relabel_configs:
- target_label: "monitor"
replacement: "127.0.0.1:15353"
static_configs:
- targets:
- "127.0.0.1:15353"
- job_name: "dnsexp_doh_gmail_mx"
scrape_interval: "10s"
metrics_path: "/query"
params:
module:
- "gmail_mx_v4"
relabel_configs:
- source_labels: ["__address__"]
target_label: "__param_server"
- source_labels: ["__address__"]
target_label: "instance"
- target_label: "__address__"
replacement: "127.0.0.1:15353"
- target_label: "monitor"
replacement: "127.0.0.1:15353"
static_configs:
- targets:
- "dns.google"
- "dns.quad9.net"
...
Would make Prometheus scrape the MX
records for gmail.com
every 10 seconds using Googles and Quad9s public DoH servers.
Example Metrics
¶
Note
These metrics are taken directly from the exporter, so they don’t have the Prometheus added instance
and job
labels yet
Metrics returned for target dns.google
:
# HELP dnsexp_dns_query_time_seconds DNS query time in seconds.
# TYPE dnsexp_dns_query_time_seconds gauge
dnsexp_dns_query_time_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",server="udp://dns.google:53",transport="UDP"} 0.010690927505493164
# HELP dnsexp_dns_response_rr_ttl_seconds DNS response RR TTL in seconds.
# TYPE dnsexp_dns_response_rr_ttl_seconds gauge
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="30 alt3.gmail-smtp-in.l.google.com.",server="udp://dns.google:53",transport="UDP"} 3044.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="10 alt1.gmail-smtp-in.l.google.com.",server="udp://dns.google:53",transport="UDP"} 3044.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="40 alt4.gmail-smtp-in.l.google.com.",server="udp://dns.google:53",transport="UDP"} 3044.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="20 alt2.gmail-smtp-in.l.google.com.",server="udp://dns.google:53",transport="UDP"} 3044.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="8.8.8.8",nsid="gpdns-ham",opcode="QUERY",port="53",protocol="udp",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="5 gmail-smtp-in.l.google.com.",server="udp://dns.google:53",transport="UDP"} 3044.0
# HELP dnsexp_dns_query_success Was this DNS query successful or not, 1 for success or 0 for failure.
# TYPE dnsexp_dns_query_success gauge
dnsexp_dns_query_success 1.0
# HELP up The value of this Gauge is always 1 when the dns_exporter is up
# TYPE up gauge
up 1.0
Metrics returned for target dns.quad9.net
:
# HELP dnsexp_dns_query_time_seconds DNS query time in seconds.
# TYPE dnsexp_dns_query_time_seconds gauge
dnsexp_dns_query_time_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",server="udp://dns.quad9.net:53",transport="UDP"} 0.028969287872314453
# HELP dnsexp_dns_response_rr_ttl_seconds DNS response RR TTL in seconds.
# TYPE dnsexp_dns_response_rr_ttl_seconds gauge
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="40 alt4.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 479.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="5 gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 479.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="30 alt3.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 479.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="20 alt2.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 479.0
dnsexp_dns_response_rr_ttl_seconds{additional="0",answer="5",authority="0",family="ipv4",flags="QR RA RD",ip="149.112.112.112",nsid="res731.arn.rrdns.pch.net",opcode="QUERY",port="53",protocol="udp",proxy="none",query_name="gmail.com",query_type="MX",rcode="NOERROR",rr_name="gmail.com.",rr_section="answer",rr_type="MX",rr_value="10 alt1.gmail-smtp-in.l.google.com.",server="udp://dns.quad9.net:53",transport="UDP"} 479.0
# HELP dnsexp_dns_query_success Was this DNS query successful or not, 1 for success or 0 for failure.
# TYPE dnsexp_dns_query_success gauge
dnsexp_dns_query_success 1.0
# HELP up The value of this Gauge is always 1 when the dns_exporter is up
# TYPE up gauge
up 1.0