dns_exporter.metrics

The dns_exporter.metrics module contains definition of all the metrics for dns_exporter.

All metrics exposed by dns_exporter are prefixed with dnsexp_ (apart from up and the built-in Python metrics).

dns_exporter.metrics.FAILURE_REASONS = ['invalid_request_module', 'invalid_request_config', 'invalid_request_server', 'invalid_request_proxy', 'invalid_request_family', 'invalid_request_ip', 'invalid_request_port', 'invalid_request_path', 'invalid_request_protocol', 'invalid_request_query_name', 'invalid_request_query_type', 'invalid_request_query_class', 'certificate_error', 'connection_error', 'response_truncated', 'socket_error', 'timeout', 'invalid_response_statuscode', 'invalid_response_rcode', 'invalid_response_flags', 'invalid_response_answer_rrs', 'invalid_response_authority_rrs', 'invalid_response_additional_rrs', 'other_failure']

FAILURE_REASONS is a list of the possible failure modes which might show up in the dnsexp_failure_reason metric.

dns_exporter.metrics.dnsexp_build_version = prometheus_client.metrics.Info(dnsexp_build_version)

dnsexp_build_version is a persistent Info metric which contains the version of dns_exporter.

The version is taken from the installed Python package if possible, and from _version.py written by setuptools_scm if the package is not installed, like when running from a Git checkout.

dns_exporter.metrics.dnsexp_dns_queries_total = prometheus_client.metrics.Counter(dnsexp_dns_queries)

dnsexp_dns_queries_total is the Counter keeping track of how many DNS queries this exporter sends out.

This metric has no labels.

dns_exporter.metrics.dnsexp_dns_responsetime_seconds = prometheus_client.metrics.Histogram(dnsexp_dns_responsetime_seconds)

Return the dnsexp_dns_responsetime_seconds metric.

dnsexp_dns_responsetime_seconds is the Histogram keeping track of how many DNS responses this exporter received since start and how long the query took.

Each DNS query duration is observed in this histogram with the following labels to identify it:

  • server

  • ip

  • port

  • protocol

  • family

  • query_name

  • query_type

  • transport

  • opcode

  • rcode

  • flags

  • answer

  • authority

  • additional

  • nsid

In some cases the nsid label has no value and the placeholder no_nsid is used instead.

dns_exporter.metrics.dnsexp_http_requests_total = prometheus_client.metrics.Counter(dnsexp_http_requests)

dnsexp_http_requests_total is a persistent Counter keeping track of the total number of HTTP requests received by the exporter since start.

This metric has a single label, path which is set to the request path, usually /query (for making DNS queries) or /metrics (for getting the internal exporter metrics.

dns_exporter.metrics.dnsexp_http_responses_total = prometheus_client.metrics.Counter(dnsexp_http_responses)

dnsexp_http_responses_total is a Counter keeping track of the total number of HTTP responses sent by the exporter since start.

This metric has two labels:

  • path is set to the request path, usually /query (for making DNS queries) or /metrics (for getting the internal exporter metrics).

  • response_code is set to the HTTP response code, usually 200.

During normal operation the exporter will never return non-200 response codes.

dns_exporter.metrics.dnsexp_scrape_failures_total = prometheus_client.metrics.Counter(dnsexp_scrape_failures)

dnsexp_scrape_failures_total is the Counter keeping track of how many scrape requests failed for some reason.

This Counter has the following labels, they are the same as dns_exporter.metrics.dnsexp_dns_query_time_seconds plus the reason label which has the failure reason.

  • reason

  • server

  • ip

  • port

  • protocol

  • family

  • query_name

  • query_type

  • transport

  • opcode

  • rcode

  • flags

  • answer

  • authority

  • additional

  • nsid

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_socket_age_seconds = prometheus_client.metrics.Gauge(dnsexp_socket_age_seconds)

dnsexp_socket_age_seconds is a Gauge keeping track of the age of each of the reusable sockets in the internal socket cache in the exporter.

This metric has six labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path/none

  • proxy Proxy URL or none

  • index Socket index

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_socket_idle_seconds = prometheus_client.metrics.Gauge(dnsexp_socket_idle_seconds)

dnsexp_socket_idle_seconds is a Gauge keeping track of idle time of each of the reusable sockets in the internal socket cache in the exporter.

This metric has six labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path/none

  • proxy Proxy URL or none

  • index Socket index

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_socket_receive_bytes_total = prometheus_client.metrics.Gauge(dnsexp_socket_receive_bytes_total)

dnsexp_socket_receive_bytes_total is a Gauge keeping track of the number of bytes received by each socket. Only the raw response size is counted, excluding TCP/UDP/TLS/IP overhead.

This metric has six labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path

  • proxy Proxy URL or none

  • index Socket index

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_socket_transmit_bytes_total = prometheus_client.metrics.Gauge(dnsexp_socket_transmit_bytes_total)

dnsexp_socket_transmit_bytes_total is a Gauge keeping track of the number of bytes transmitted to servers by each socket. Only the raw query size is counted, excluding TCP/UDP/TLS/IP overhead.

This metric has six labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path/none

  • proxy Proxy URL or none

  • index Socket index

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_socket_uses_total = prometheus_client.metrics.Gauge(dnsexp_socket_uses_total)

dnsexp_socket_uses_total is a Gauge keeping track of the number of times each socket has been used.

This metric has six labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path

  • proxy Proxy URL

  • index Socket index

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.dnsexp_sockets_total = prometheus_client.metrics.Gauge(dnsexp_sockets_total)

dnsexp_sockets_total is a Gauge keeping track of the number of sockets in the internal socket cache.

This metric has five labels:

  • protocol

  • server

  • ip

  • verify TLS verify setting, True/False/CA Path/none

  • proxy Proxy URL or none

The placeholder none is used for cases where there is no suitable value for the label.

dns_exporter.metrics.get_dns_qtime_metric() → GaugeMetricFamily

dnsexp_dns_query_time_seconds is the gauge used as the primary timing metric for DNS queries.

Each DNS query duration is added to this gauge with the following labels to identify it:

  • server

  • ip

  • port

  • protocol

  • family

  • query_name

  • query_type

  • transport

  • opcode

  • rcode

  • flags

  • answer

  • authority

  • additional

  • nsid

  • connection (if enabled)

In some cases the nsid label has no value and the placeholder no_nsid is used instead.

dns_exporter.metrics.get_dns_success_metric(value: int | None = None) → GaugeMetricFamily

dnsexp_dns_query_success is a Gauge set to 1 when a DNS query is successful, or 0 otherwise.

A DNS query is considered failed in the following cases:

  • Configuration issues preventing a DNS query

  • Network or server issues preventing a response from reaching the exporter

  • Response parsing issues

  • Response validation issues

A DNS query is considered a success if a DNS query response is received and any configured validation logic passes.

dns_exporter.metrics.get_dns_ttl_metric() → GaugeMetricFamily

dnsexp_dns_response_rr_ttl_seconds is a Gauge which tracks the TTL of individual response RRs.

This metric will often be set multiple times during a scrape, whenever a DNS query results in multiple RRs in the answer/authority/additional sections. For example, if a DNS query results in a response with 2 ANSWER, 0 AUTHORITY and 4 ADDITIONAL then this metric will be set 6 times (with different labels).

This Gauge has the following labels, they are the same as dns_exporter.metrics.dnsexp_dns_query_time_seconds plus a few more:

  • server

  • ip

  • port

  • protocol

  • family

  • query_name

  • query_type

  • transport

  • opcode

  • rcode

  • flags

  • answer

  • authority

  • additional

  • nsid

  • rr_section (answer, authority or additional)

  • rr_name (the RR name)

  • rr_type (the RR type)

  • rr_value (the first X chars of the RR value)

  • connection (if enabled)