Skip to main content

Unbound

Plugin: go.d.plugin Module: unbound

Overview

This collector monitors Unbound servers.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

This integration doesn't support auto-detection.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per Unbound instance

These metrics refer to the entire monitored application.

This scope has no labels.

Metrics:

MetricDimensionsUnit
unbound.queriesqueriesqueries
unbound.queries_ip_ratelimitedratelimitedqueries
unbound.dnscrypt_queriescrypted, cert, cleartext, malformedqueries
unbound.cachehits, missevents
unbound.cache_percentagehits, misspercentage
unbound.prefetchprefetchesprefetches
unbound.expiredexpiredreplies
unbound.zero_ttl_replieszero_ttlreplies
unbound.recursive_repliesrecursivereplies
unbound.recursion_timeavg, medianmilliseconds
unbound.request_list_usageavg, maxqueries
unbound.current_request_list_usageall, usersqueries
unbound.request_list_jostle_listoverwritten, droppedqueries
unbound.tcpusageusagebuffers
unbound.uptimetimeseconds
unbound.cache_memorymessage, rrset, dnscrypt_nonce, dnscrypt_shared_secretKB
unbound.mod_memoryiterator, respip, validator, subnet, ipsecKB
unbound.mem_streamwaitstreamwaitKB
unbound.cache_countinfra, key, msg, rrset, dnscrypt_nonce, shared_secretitems
unbound.type_queriesa dimension per query typequeries
unbound.class_queriesa dimension per query classqueries
unbound.opcode_queriesa dimension per query opcodequeries
unbound.flag_queriesqr, aa, tc, rd, ra, z, ad, cdqueries
unbound.rcode_answersa dimension per reply rcodereplies

Per thread

These metrics refer to threads.

This scope has no labels.

Metrics:

MetricDimensionsUnit
unbound.thread_queriesqueriesqueries
unbound.thread_queries_ip_ratelimitedratelimitedqueries
unbound.thread_dnscrypt_queriescrypted, cert, cleartext, malformedqueries
unbound.thread_cachehits, missevents
unbound.thread_cache_percentagehits, misspercentage
unbound.thread_prefetchprefetchesprefetches
unbound.thread_expiredexpiredreplies
unbound.thread_zero_ttl_replieszero_ttlreplies
unbound.thread_recursive_repliesrecursivereplies
unbound.thread_recursion_timeavg, medianmilliseconds
unbound.thread_request_list_usageavg, maxqueries
unbound.thread_current_request_list_usageall, usersqueries
unbound.thread_request_list_jostle_listoverwritten, droppedqueries
unbound.thread_tcpusageusagebuffers

Alerts

There are no alerts configured by default for this integration.

Setup

Prerequisites

Enable remote control interface

Set control-enable to yes in unbound.conf.

Check permissions and adjust if necessary

If using unix socket:

  • socket should be readable and writeable by netdata user

If using ip socket and TLS is disabled:

  • socket should be accessible via network

If TLS is enabled, in addition:

  • control-key-file should be readable by netdata user
  • control-cert-file should be readable by netdata user

For auto-detection parameters from unbound.conf:

  • unbound.conf should be readable by netdata user
  • if you have several configuration files (include feature) all of them should be readable by netdata user

Configuration

File

The configuration file name for this integration is go.d/unbound.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/unbound.conf

Options

The following options can be defined globally: update_every, autodetection_retry.

Config options
NameDescriptionDefaultRequired
update_everyData collection frequency.5no
autodetection_retryRecheck interval in seconds. Zero means no recheck will be scheduled.0no
addressServer address in IP:PORT format.127.0.0.1:8953yes
timeoutConnection/read/write/ssl handshake timeout.1no
conf_pathAbsolute path to the unbound configuration file./etc/unbound/unbound.confno
cumulative_statsStatistics collection mode. Should have the same value as the statistics-cumulative parameter in the unbound configuration file.nono
use_tlsWhether to use TLS or not.yesno
tls_skip_verifyServer certificate chain and hostname validation policy. Controls whether the client performs this check.yesno
tls_caCertificate authority that client use when verifying server certificates.no
tls_certClient tls certificate./etc/unbound/unbound_control.pemno
tls_keyClient tls key./etc/unbound/unbound_control.keyno

Examples

Basic

An example configuration.

Config
jobs:
- name: local
address: 127.0.0.1:8953

Unix socket

Connecting through Unix socket.

Config
jobs:
- name: socket
address: /var/run/unbound.sock

Multi-instance

Note: When you define multiple jobs, their names must be unique.

Local and remote instances.

Config
jobs:
- name: local
address: 127.0.0.1:8953

- name: remote
address: 203.0.113.11:8953

Troubleshooting

Debug Mode

To troubleshoot issues with the unbound collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

  • Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].

    cd /usr/libexec/netdata/plugins.d/
  • Switch to the netdata user.

    sudo -u netdata -s
  • Run the go.d.plugin to debug the collector:

    ./go.d.plugin -d -m unbound

Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.