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 set module to the value quad9_mx
In relabel_configs set the query_name scrape param to the target
In relabel_configs set the standard __address__ and instance labels.
In relabel_configs set the monitor 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 set module to the value gmail_mx_v4
In relabel_configs set the server scrape param to the target
In relabel_configs set the standard __address__ and instance labels
In relabel_configs set the monitor 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

Examples¶

Monitoring a list of names¶

Usecase¶

`dns_exporter.yml`¶

`prometheus.yml`¶

`Example Metrics`¶

Monitoring a list of servers¶

Usecase¶

`dns_exporter.yml`¶

`prometheus.yml`¶

`Example Metrics`¶

dns_exporter

Navigation

Related Topics

Examples¶

Monitoring a list of names¶

Usecase¶

dns_exporter.yml¶

prometheus.yml¶

Example Metrics¶

Monitoring a list of servers¶

Usecase¶

dns_exporter.yml¶

prometheus.yml¶

Example Metrics¶

`dns_exporter.yml`¶

`prometheus.yml`¶

`Example Metrics`¶

`dns_exporter.yml`¶

`prometheus.yml`¶

`Example Metrics`¶