Skip to main content

Monitoring Unbound

Unbound is recognised by its unbound process and read through unbound-control, the same tool you use on the command line. The agent asks for statistics once a minute without resetting them, so your own unbound-control stats keeps working. The one thing Unbound needs is remote control enabled, which most packaged installs already have.

How Unbound is recognised​

The signed definition matches a host running a process named unbound. Every 60 seconds the agent runs unbound-control stats_noreset and parses five values out of the output. There is no port check and no log tail in this definition: unbound-control is the whole probe, so when it cannot talk to the daemon the check fails with the command's own message.

What is collected​

Queries and cache. The total number of queries answered, cache hits and cache misses since the daemon started. These are cumulative totals, so on a chart they climb and the slope is the information; hits divided by queries is your cache hit rate.

Latency and queueing. The average recursion time in seconds for the queries that needed a lookup, and the average length of the request list, the queue of queries waiting on recursion. A request list that grows is the first sign the resolver is not keeping up.

No facts are recorded for Unbound: the definition carries no version probe.

SignalMetric
Queries answered, total and per secondsvc.unbound.queries, svc.unbound.query_rate
Cache hits / misses, totalsvc.unbound.cache_hits, svc.unbound.cache_miss
Cache hits / misses per secondsvc.unbound.cache_hit_rate, svc.unbound.cache_miss_rate
Cache hit share, percentsvc.unbound.cache_hit_pct
Average recursion timesvc.unbound.recursion_time_avg
Average request list lengthsvc.unbound.requestlist_avg
Request list overflows, total and per minutesvc.unbound.requestlist_exceeded, svc.unbound.requestlist_exceeded_per_min

Names, tags and units are in the metrics reference.

Logs. Unbound's journal entries ship at notice level and above. See Logs.

Alerts out of the box​

No rule ships for Unbound. Any metric above can drive a custom rule in the console under Alerting, rules. The averages, the hit share and the per-minute overflow count are the ones to alert on: a threshold on svc.unbound.recursion_time_avg, svc.unbound.requestlist_avg or svc.unbound.requestlist_exceeded_per_min describes a resolver in trouble, and svc.unbound.cache_hit_pct falling describes a cache that stopped helping. The totals only ever grow, so a threshold on them would fire once and never clear.

Limitations​

  • unbound-control needs remote control enabled in unbound.conf (control-enable: yes in the remote-control section, with the keys unbound-control-setup generates). Without it the probe fails and nothing is collected.
  • There is no liveness check on port 53. A daemon that answers unbound-control but not queries looks healthy to this definition.
  • The counters are totals since the last start of Unbound; a restart resets them to zero.
  • Only the five values above are read. Per-thread lines and the rest of the statistics output are ignored.
  • The Unbound version is not recorded as a fact.