---
title: ''
description: Telegraf plugin for collecting metrics from Unbound
url: https://docs.influxdata.com/telegraf/v1/input-plugins/unbound/
estimated_tokens: 1863
product: Telegraf Controller
version: v1
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/v1/input-plugins/unbound/
date: '2026-05-21T20:10:18+02:00'
lastmod: '2026-05-21T20:10:18+02:00'
---

==========

* Telegraf v1.5.0+

[Plugin source](https://github.com/influxdata/telegraf/tree/v1.39.0/plugins/inputs/unbound/)[Download configuration](https://raw.githubusercontent.com/influxdata/telegraf/refs/tags/v1.39.0/plugins/inputs/unbound/sample.conf)

# Unbound Input Plugin

This plugin gathers stats from an [Unbound](https://www.unbound.net) DNS resolver.

**Introduced in:** Telegraf v1.5.0**Tags:** server, network**OS support:** all

## Global configuration options

Plugins support additional global and plugin configuration settings for tasks
such as modifying metrics, tags, and fields, creating aliases, and configuring
plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.

## Configuration

```toml
# A plugin to collect stats from the Unbound DNS resolver
[[inputs.unbound]]
  ## Address of server to connect to, read from unbound conf default, optionally ':port'
  ## Will lookup IP if given a hostname
  server = "127.0.0.1:8953"

  ## If running as a restricted user you can prepend sudo for additional access:
  # use_sudo = false

  ## The default location of the unbound-control binary can be overridden with:
  # binary = "/usr/sbin/unbound-control"

  ## The default location of the unbound config file can be overridden with:
  # config_file = "/etc/unbound/unbound.conf"

  ## The default timeout of 1s can be overridden with:
  # timeout = "1s"

  ## When set to true, thread metrics are tagged with the thread id.
  ##
  ## The default is false for backwards compatibility, and will be changed to
  ## true in a future version.  It is recommended to set to true on new
  ## deployments.
  thread_as_tag = false

  ## Collect metrics with the histogram of the recursive query times:
  # histogram = false
```

### Permissions

It’s important to note that this plugin references unbound-control, which may
require additional permissions to execute successfully. Depending on the
user/group permissions of the telegraf user executing this plugin, you may need
to alter the group membership, set facls, or use sudo.

#### Group membership (recommended)

```bash
$ groups telegraf
telegraf : telegraf

$ usermod -a -G unbound telegraf

$ groups telegraf
telegraf : telegraf unbound
```

#### Sudo privileges

If you use this method, you will need the following in your telegraf config:

```toml
[[inputs.unbound]]
  use_sudo = true
```

You will also need to update your sudoers file:

```bash
$ visudo
# Add the following line:
Cmnd_Alias UNBOUNDCTL = /usr/sbin/unbound-control
telegraf  ALL=(ALL) NOPASSWD: UNBOUNDCTL
Defaults!UNBOUNDCTL !logfile, !syslog, !pam_session
```

Please use the solution you see as most appropriate.

## Metrics

This is the full list of stats provided by unbound-control and potentially
collected depending of your unbound configuration. Extended statistics can also
be imported (“extended-statistics: yes” in unbound configuration). In the
output, the dots in the unbound-control stat name are replaced by
underscores(see [https://www.unbound.net/documentation/unbound-control.html](https://www.unbound.net/documentation/unbound-control.html) for
details).

Shown metrics are with `thread_as_tag` enabled.

* unbound

  * fields:
    total\_num\_queries
    total\_num\_cachehits
    total\_num\_cachemiss
    total\_num\_prefetch
    total\_num\_recursivereplies
    total\_requestlist\_avg
    total\_requestlist\_max
    total\_requestlist\_overwritten
    total\_requestlist\_exceeded
    total\_requestlist\_current\_all
    total\_requestlist\_current\_user
    total\_recursion\_time\_avg
    total\_recursion\_time\_median
    time\_now
    time\_up
    time\_elapsed
    mem\_total\_sbrk
    mem\_cache\_rrset
    mem\_cache\_message
    mem\_mod\_iterator
    mem\_mod\_validator
    num\_query\_type\_A
    num\_query\_type\_PTR
    num\_query\_type\_TXT
    num\_query\_type\_AAAA
    num\_query\_type\_SRV
    num\_query\_type\_ANY
    num\_query\_class\_IN
    num\_query\_opcode\_QUERY
    num\_query\_tcp
    num\_query\_ipv6
    num\_query\_flags\_QR
    num\_query\_flags\_AA
    num\_query\_flags\_TC
    num\_query\_flags\_RD
    num\_query\_flags\_RA
    num\_query\_flags\_Z
    num\_query\_flags\_AD
    num\_query\_flags\_CD
    num\_query\_edns\_present
    num\_query\_edns\_DO
    num\_answer\_rcode\_NOERROR
    num\_answer\_rcode\_SERVFAIL
    num\_answer\_rcode\_NXDOMAIN
    num\_answer\_rcode\_nodata
    num\_answer\_secure
    num\_answer\_bogus
    num\_rrset\_bogus
    unwanted\_queries
    unwanted\_replies

* unbound\_thread

  * tags:
    * thread

  * fields:
    * num\_queries
    * num\_cachehits
    * num\_cachemiss
    * num\_prefetch
    * num\_recursivereplies
    * requestlist\_avg
    * requestlist\_max
    * requestlist\_overwritten
    * requestlist\_exceeded
    * requestlist\_current\_all
    * requestlist\_current\_user
    * recursion\_time\_avg
    * recursion\_time\_median

If `histogram` is set to true, the following metrics are also collected, with
the field name indicating the lower bound of each histogram bin:

* unbound:
  * fields:
    histogram\_.000000
    histogram\_.000001
    histogram\_.000002
    histogram\_.000004
    histogram\_.000008
    histogram\_.000016
    histogram\_.000032
    histogram\_.000064
    histogram\_.000128
    histogram\_.000256
    histogram\_.000512
    histogram\_.001024
    histogram\_.002048
    histogram\_.004096
    histogram\_.008192
    histogram\_.016384
    histogram\_.032768
    histogram\_.065536
    histogram\_.131072
    histogram\_.262144
    histogram\_.524288
    histogram\_1.000000
    histogram\_2.000000
    histogram\_4.000000
    histogram\_8.000000
    histogram\_16.000000
    histogram\_32.000000
    histogram\_64.000000
    histogram\_128.000000
    histogram\_256.000000
    histogram\_512.000000
    histogram\_1024.000000
    histogram\_2048.000000
    histogram\_4096.000000
    histogram\_8192.000000
    histogram\_16384.000000
    histogram\_32768.000000
    histogram\_65536.000000
    histogram\_131072.000000
    histogram\_262144.000000

## Example Output

```text
unbound,host=localhost total_requestlist_avg=0,total_requestlist_exceeded=0,total_requestlist_overwritten=0,total_requestlist_current_user=0,total_recursion_time_avg=0.029186,total_tcpusage=0,total_num_queries=51,total_num_queries_ip_ratelimited=0,total_num_recursivereplies=6,total_requestlist_max=0,time_now=1522804978.784814,time_elapsed=310.435217,total_num_cachemiss=6,total_num_zero_ttl=0,time_up=310.435217,total_num_cachehits=45,total_num_prefetch=0,total_requestlist_current_all=0,total_recursion_time_median=0.016384 1522804979000000000
unbound_threads,host=localhost,thread=0 num_queries_ip_ratelimited=0,requestlist_current_user=0,recursion_time_avg=0.029186,num_prefetch=0,requestlist_overwritten=0,requestlist_exceeded=0,requestlist_current_all=0,tcpusage=0,num_cachehits=37,num_cachemiss=6,num_recursivereplies=6,requestlist_avg=0,num_queries=43,num_zero_ttl=0,requestlist_max=0,recursion_time_median=0.032768 1522804979000000000
unbound_threads,host=localhost,thread=1 num_zero_ttl=0,recursion_time_avg=0,num_queries_ip_ratelimited=0,num_cachehits=8,num_prefetch=0,requestlist_exceeded=0,recursion_time_median=0,tcpusage=0,num_cachemiss=0,num_recursivereplies=0,requestlist_max=0,requestlist_overwritten=0,requestlist_current_user=0,num_queries=8,requestlist_avg=0,requestlist_current_all=0 1522804979000000000
```