Dnscheck Receiver

Maintainers: @dmitryax Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Configuration

The following configuration settings are available:

dns_servers (required): The list of DNS servers to query.
hostnames (required): The list of hostnames and record types to resolve.
collection_interval (optional, default = 60s): This receiver collects metrics on an interval. Valid time units are ns, us (or µs), ms, s, m, h.
initial_delay (optional, default = 1s): Defines how long this receiver waits before starting.

DNS Server Configuration

Each entry in dns_servers has the following properties:

endpoint (required): The DNS server address, as host or host:port (default port 53).
network (optional, default = udp): The transport protocol used to query the server. One of udp, tcp, or tcp-tls.
timeout (optional, default = 5s): Per-query dial timeout for this server.

Hostname Configuration

Each entry in hostnames has the following properties:

name (required): The hostname to resolve.
record_type (optional, default = A): The DNS record type to query (e.g. A, AAAA, CNAME, MX, TXT).

Optional Metrics Configuration

Each metric can be enabled or disabled individually. By default, all metrics are enabled except dnscheck.error. Example:

receivers:
  dns_check:
    metrics:
      dnscheck.error:
        enabled: true

Metrics

Details about the metrics produced by this receiver can be found in documentation.md

RCODE Reference

The dnscheck.status metric carries the DNS response code (RCODE) returned for the query in its dns.rcode attribute. This attribute is present whenever a response was received from the server, even if the response itself indicates a failure (e.g. NXDOMAIN, SERVFAIL, REFUSED). It is absent only when no response was received at all, such as on a timeout or network unreachable error. The table below covers RCODE values 0-23; see the IANA DNS Parameters registry for the full and up-to-date list.

Code	Name	Description
0	NoError	No Error
1	FormErr	Format Error
2	ServFail	Server Failure
3	NXDomain	Non-Existent Domain
4	NotImp	Not Implemented
5	Refused	Query Refused
6	YXDomain	Name Exists when it should not
7	YXRRSet	RR Set Exists when it should not
8	NXRRSet	RR Set that should exist does not
9	NotAuth	Server Not Authoritative for zone / Not Authorized
10	NotZone	Name not contained in zone
11	DSOTYPENI	DSO-TYPE Not Implemented
12-15	Unassigned	Unassigned
16	BADVERS/BADSIG	Bad OPT Version / TSIG Signature Failure
17	BADKEY	Key not recognized
18	BADTIME	Signature out of time window
19	BADMODE	Bad TKEY Mode
20	BADNAME	Duplicate key name
21	BADALG	Algorithm not supported
22	BADTRUNC	Bad Truncation
23	BADCOOKIE	Bad/missing Server Cookie

Example Configuration

receivers:
  dns_check:
    collection_interval: 60s
    initial_delay: 1s
    dns_servers:
      - endpoint: "8.8.8.8"
      - endpoint: "1.1.1.1:53"
        network: udp
        timeout: 5s
      - endpoint: "9.9.9.9:853"
        network: tcp-tls
        timeout: 10s
    hostnames:
      - name: "example.com"
        record_type: A
      - name: "example.com"
        record_type: AAAA
processors:
  batch:
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    metrics:
      receivers: [ dns_check ]
      processors: [ batch ]
      exporters: [ debug ]

Metrics

Metric Name	Description	Unit	Type	Attributes
✅ `dnscheck.duration`	Round-trip duration of the DNS query.	ms	Gauge	dns.domain, dns.record.type, dns.server
❌ `dnscheck.error`	Number of errors recorded during the DNS check.	{error}	UpDownCounter	dns.domain, dns.record.type, dns.server, error.message
✅ `dnscheck.status`	1 if the DNS query returned successfully, 0 otherwise. The dns.resolved.ip and dns.resolved.all.ips attributes are only present when the value is 1. The dns.rcode attribute is present whenever a response was received from the server, including non-success responses such as NXDOMAIN, SERVFAIL, or REFUSED; it is absent only when no response was received at all (e.g. timeout or network unreachable).	1	UpDownCounter	dns.domain, dns.rcode, dns.record.type, dns.resolved.all.ips, dns.resolved.ip, dns.server

Attributes

Attribute Name	Description	Type
`dns.domain`	Domain name queried.	string
`dns.rcode`	DNS response code (RCODE) returned for the query. Only present when a response was received from the server, including non-success responses such as NXDOMAIN, SERVFAIL, or REFUSED. Absent when no response was received at all (e.g. timeout or network unreachable). See the RCODE Reference table in the README for the meaning of each value, based on the IANA DNS Parameters registry (https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6).	int
`dns.record.type`	Record type queried.	string
`dns.resolved.all.ips`	All resolved IP addresses.	string
`dns.resolved.ip`	First/primary resolved IP address.	string
`dns.server`	Address of the DNS server queried.	string
`error.message`	Error message recorded when the DNS check fails.	string

Last generated: 2026-08-03

​Dnscheck Receiver

​Supported Telemetry

​Overview

​Configuration

​DNS Server Configuration

​Hostname Configuration

​Optional Metrics Configuration

​Metrics

​RCODE Reference

​Example Configuration

​Metrics

​Attributes

Dnscheck Receiver

Supported Telemetry

Overview

Configuration

DNS Server Configuration

Hostname Configuration

Optional Metrics Configuration

Metrics

RCODE Reference

Example Configuration

Metrics

Attributes