Unbound

Supported OS Linux Windows Mac OS

Integration version1.0.1

Overview

This check monitors Unbound through the Datadog Agent.

Get metrics from unbound service in real time to:

  • Visualize and monitor unbound states

Setup

The Unbound check is not included in the Datadog Agent package, so you need to install it.

Installation

For Agent v7.21+ / v6.21+, follow the instructions below to install the Unbound check on your host. See Use Community Integrations to install with the Docker Agent or earlier versions of the Agent.

  1. Run the following command to install the Agent integration:

    datadog-agent integration install -t datadog-unbound==<INTEGRATION_VERSION>
    
  2. Configure your integration similar to core integrations.

Configuration

  1. Edit the unbound.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory to start collecting unbound metrics. See the sample unbound.d/conf.yaml for all available configuration options.

  2. Restart the Agent.

Validation

Run the Agent’s status subcommand and look for unbound under the Checks section.

Data Collected

Metrics

unbound.thread.num.queries
(count)
The number of queries received by thread
Shown as query
unbound.thread.num.queries_ip_ratelimited
(count)
The number of queries rate limited by thread
Shown as query
unbound.thread.num.cachehits
(count)
The number of queries that were successfully answered using a cache lookup
Shown as query
unbound.thread.num.cachemiss
(count)
The number of queries that needed recursive processing
Shown as query
unbound.thread.num.dnscrypt.crypted
(count)
The number of queries that were encrypted and successfully decapsulated by dnscrypt
Shown as query
unbound.thread.num.dnscrypt.cert
(count)
The number of queries that were requesting dnscrypt certificates
Shown as query
unbound.thread.num.dnscrypt.cleartext
(count)
The number of queries received on dnscrypt port that were cleartext and not a request for certificates
Shown as query
unbound.thread.num.dnscrypt.malformed
(count)
The number of requests that were neither cleartext nor valid dnscrypt messages
Shown as request
unbound.thread.num.prefetch
(count)
The number of cache prefetches performed
unbound.thread.num.zero_ttl
(count)
The number of replies with ttl zero because they served an expired cache entry
Shown as response
unbound.thread.num.recursivereplies
(count)
The number of replies sent to queries that needed recursive processing
Shown as response
unbound.thread.requestlist.avg
(gauge)
The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query
Shown as request
unbound.thread.requestlist.max
(gauge)
Maximum size attained by the internal recursive processing request list
Shown as request
unbound.thread.requestlist.overwritten
(count)
The number of requests in the request list that were overwritten by newer entries
Shown as request
unbound.thread.requestlist.exceeded
(gauge)
Queries that were dropped because the request list was full
Shown as query
unbound.thread.requestlist.current.all
(gauge)
Current size of the request list
Shown as request
unbound.thread.requestlist.current.user
(gauge)
Current size of the request list (only the requests from client queries)
Shown as request
unbound.thread.recursion.time.avg
(gauge)
Average time it took to answer queries that needed recursive processing
Shown as second
unbound.thread.recursion.time.median
(gauge)
The median of the time it took to answer queries that needed recursive processing
Shown as second
unbound.thread.tcpusage
(gauge)
The currently held tcp buffers for incoming connections
Shown as buffer
unbound.total.num.queries
(count)
The total number of queries summed over threads
Shown as query
unbound.total.num.cachehits
(count)
The total number of cache hits summed over threads
Shown as hit
unbound.total.num.cachemiss
(count)
The total number of cache misses summed over threads
Shown as miss
unbound.total.num.dnscrypt.crypted
(count)
The total number of dnscrypt crypted summed over threads
Shown as query
unbound.total.num.dnscrypt.cert
(count)
The total number of dnscrypt cert summed over threads
Shown as query
unbound.total.num.dnscrypt.cleartext
(count)
The total number of dnscrypt cleartext summed over threads
Shown as query
unbound.total.num.dnscrypt.malformed
(count)
The total number of dnscrypt malformed summed over threads
Shown as request
unbound.total.num.prefetch
(count)
The total number of prefetch summed over threads
unbound.total.num.zero_ttl
(count)
The total number of zero ttl summed over threads
Shown as response
unbound.total.num.recursivereplies
(count)
The total number of recursive replies summed over threads
Shown as response
unbound.total.requestlist.avg
(gauge)
The total number of requests averaged over threads
Shown as request
unbound.total.requestlist.max
(gauge)
The maximum of the thread requestlist.max values
Shown as request
unbound.total.requestlist.overwritten
(gauge)
The number of requests in the request list that were overwritten by newer entries summed over threads
Shown as request
unbound.total.requestlist.exceeded
(gauge)
The total number of queries that were dropped because the request list was full summed over threads
Shown as query
unbound.total.requestlist.current.all
(gauge)
The current size of all threads' request lists
Shown as request
unbound.total.recursion.time.avg
(gauge)
The average time it took to answer queries that needed recursive processing averaged over threads
Shown as second
unbound.total.recursion.time.median
(gauge)
The median of the time it took to answer queries that needed recursive processing averaged over threads
Shown as second
unbound.time.now
(gauge)
The current time in seconds since 1970
Shown as second
unbound.time.up
(gauge)
The uptime since server boot in seconds
Shown as second
unbound.time.elapsed
(gauge)
The time since last statistics printout in seconds
Shown as second
unbound.mem.total.sbrk
(gauge)
If sbrk(2) is available an estimate of the heap size of the program in bytes
Shown as byte
unbound.mem.cache.rrset
(gauge)
Memory in bytes in use by the RRset cache
Shown as byte
unbound.mem.cache.message
(gauge)
Memory in bytes in use by the message cache
Shown as byte
unbound.mem.cache.dnscrypt_shared_secret
(gauge)
Memory in bytes in use by the dnscrypt shared secrets cache
Shown as byte
unbound.mem.cache.dnscrypt_nonce
(gauge)
Memory in bytes in use by the dnscrypt nonce cache
Shown as byte
unbound.mem.mod.iterator
(gauge)
Memory in bytes in use by the iterator module
Shown as byte
unbound.mem.mod.validator
(gauge)
Memory in bytes in use by the validator module. Includes the key cache and negative cache.
Shown as byte
unbound.mem.mod.respip
(gauge)
Memory in bytes in use by the respip module
Shown as byte
unbound.mem.streamwait
(gauge)
Memory in bytes in use by the TCP and TLS stream wait buffers. These are answers waiting to be written back to the clients.
Shown as byte
unbound.num.query.type
(count)
The total number of queries over all threads by type
Shown as query
unbound.num.query.class
(count)
The total number of queries over all threads by class
Shown as query
unbound.num.query.opcode
(count)
The total number of queries over all threads by opcode
Shown as query
unbound.num.query.tcp
(count)
The number of queries that were made using TCP towards the unbound server
Shown as query
unbound.num.query.tcpout
(count)
The number of queries that the unbound server made using TCP outgoing towards other servers
Shown as query
unbound.num.query.tls
(count)
The number of queries that were made using TLS towards the unbound server. These are also counted in num.query.tcp because TLS uses TCP.
Shown as query
unbound.num.query.tls.resume
(count)
The number of TLS session resumptions. These are queries over TLS towards the unbound server where the client negotiated a TLS session resumption key
unbound.num.query.ipv6
(count)
The number of queries that were made using IPv6 towards the unbound server
Shown as query
unbound.num.query.flags
(count)
The number of queries by flag set in the header
Shown as query
unbound.num.query.edns.present
(count)
The number of queries that had an EDNS OPT record present
Shown as query
unbound.num.query.edns.DO
(count)
The number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set
Shown as query
unbound.num.query.ratelimited
(count)
The number of queries that are turned away from being sent to nameserver due to ratelimiting
Shown as query
unbound.num.query.dnscrypt.shared_secret.cachemiss
(count)
The number of dnscrypt queries that did not find a shared secret in the cache
Shown as query
unbound.num.query.dnscrypt.replay
(count)
The number of dnscrypt queries that found a nonce hit in the nonce cache and hence are considered a query replay
Shown as query
unbound.num.answer.rcode
(count)
The number of answers to queries from cache or from recursion by return code
Shown as response
unbound.num.answer.rcode.nodata
(count)
The number of answers to queries that had the pseudo return code nodata
Shown as response
unbound.num.answer.secure
(count)
The number of answers that were secure
Shown as response
unbound.num.answer.bogus
(count)
The number of answers that were bogus
Shown as response
unbound.num.rrset.bogus
(count)
The number of rrsets marked bogus by the validator
unbound.unwanted.queries
(count)
The number of queries that were refused or dropped because they failed the access control settings
Shown as query
unbound.unwanted.replies
(count)
The number of replies that were unwanted or unsolicited
Shown as response
unbound.msg.cache.count
(count)
The number of items (DNS replies) in the message cache
Shown as item
unbound.rrset.cache.count
(count)
The number of RRsets in the rrset cache
Shown as item
unbound.infra.cache.count
(count)
The number of items in the infra cache
Shown as item
unbound.key.cache.count
(count)
The number of items in the key cache
Shown as item
unbound.dnscrypt_shared_secret.cache.count
(count)
The number of items in the shared secret cache
Shown as item
unbound.dnscrypt_nonce.cache.count
(count)
The number of items in the client nonce cache
Shown as item
unbound.num.query.authzone.up
(count)
The number of queries answered from auth-zone data (upstream queries)
Shown as query
unbound.num.query.authzone.down
(count)
The number of queries for downstream answered from auth-zone data
Shown as query
unbound.num.query.aggressive.NOERROR
(count)
The number of queries answered using cached NSEC records with NODATA RCODE
Shown as query
unbound.num.query.aggressive.NXDOMAIN
(count)
The number of queries answered using cached NSEC records with NXDOMAIN RCODE
Shown as query
unbound.num.query.subnet
(count)
The number of queries which received an answer and contained EDNS client subnet data
Shown as query
unbound.num.query.subnet_cache
(count)
The number of queries answered from the EDNS client subnet cache
Shown as query

Events

The Unbound check does not include any events.

Service Checks

unbound.can_get_stats
Returns CRITICAL if unbound-control fails or there’s an error parsing its output. Returns OK otherwise.
Statuses: ok, critical

Troubleshooting

Need help? Contact Datadog support.