From 893bc2790af51f151449014ee3b738789e7c85b9 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Wed, 23 May 2018 12:22:25 -0700 Subject: [PATCH] Update unbound README --- plugins/inputs/unbound/README.md | 161 +++++++++++++++--------------- plugins/inputs/unbound/unbound.go | 33 +++--- 2 files changed, 94 insertions(+), 100 deletions(-) diff --git a/plugins/inputs/unbound/README.md b/plugins/inputs/unbound/README.md index ff2b03af3..4f1f862bb 100644 --- a/plugins/inputs/unbound/README.md +++ b/plugins/inputs/unbound/README.md @@ -1,56 +1,78 @@ # Unbound Input Plugin -This plugin gathers stats from [Unbound - a validating, recursive, and caching DNS resolver](https://www.unbound.net/) +This plugin gathers stats from [Unbound](https://www.unbound.net/) - +a validating, recursive, and caching DNS resolver. ### Configuration: ```toml - # A plugin to collect stats from Unbound - a validating, recursive, and caching DNS resolver - [[inputs.unbound]] - ## If running as a restricted user you can prepend sudo for additional access: - #use_sudo = false +# 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" - ## The default location of the unbound-control binary can be overridden with: - binary = "/usr/sbin/unbound-control" + ## If running as a restricted user you can prepend sudo for additional access: + # use_sudo = false - ## The default timeout of 1s can be overriden with: - #timeout = "1s" + ## The default location of the unbound-control binary can be overridden with: + # binary = "/usr/sbin/unbound-control" - ## Use the builtin fielddrop/fieldpass telegraf filters in order to keep only specific fields - fieldpass = ["total_*", "num_*","time_up", "mem_*"] + ## The default timeout of 1s can be overriden with: + # timeout = "1s" - ## IP 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" - - ## Output thread related values in a separate measurement "unbound_threads", with additional tag - ## "thread" identifying the thread number (0 ... the number of configured threads) - ## By default, thread related metrics are output as additional fields in measurement "unbound" - thread_as_tag = false + ## When set to true, thread metrics are tagged with the thread id. + ## + ## The default is false for backwards compatibility, and will be change to + ## true in a future version. It is recommended to set to true on new + ## deployments. + thread_as_tag = false ``` -### Measurements & Fields: +#### Permissions: -This is the full list of stats provided by unbound-control and potentially collected by telegram -depending of your unbound configuration. Histogram related statistics will never be collected, +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: +telegraf ALL=(ALL) NOPASSWD: /usr/sbin/unbound-control +``` + +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. Histogram related statistics will never be collected, 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 for details). +Shown metrics are with `thread_as_tag` enabled. + - unbound - thread0_num_queries - thread0_num_cachehits - thread0_num_cachemiss - thread0_num_prefetch - thread0_num_recursivereplies - thread0_requestlist_avg - thread0_requestlist_max - thread0_requestlist_overwritten - thread0_requestlist_exceeded - thread0_requestlist_current_all - thread0_requestlist_current_user - thread0_recursion_time_avg - thread0_recursion_time_median + - fields: total_num_queries total_num_cachehits total_num_cachemiss @@ -102,54 +124,27 @@ https://www.unbound.net/documentation/unbound-control.html for details). unwanted_queries unwanted_replies -### Permissions: +- 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 -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 +### Example Output: ``` - -**Sudo privileges**: -If you use this method, you will need the following in your telegraf config: -```toml -[[inputs.unbound]] - use_sudo = true +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 ``` - -You will also need to update your sudoers file: -```bash -$ visudo -# Add the following line: -telegraf ALL=(ALL) NOPASSWD: /usr/sbin/unbound-control -``` - -Please use the solution you see as most appropriate. - -### Example Output (default): - -``` - telegraf --config etc/telegraf.conf --input-filter unbound --test -* Plugin: inputs.unbound, Collection 1 -> unbound,host=localhost total_num_cachehits=0,total_num_prefetch=0,total_requestlist_avg=0,total_requestlist_max=0,total_recursion_time_median=0,total_num_queries=0,total_requestlist_overwritten=0,total_requestlist_current_all=0,time_up=159185.583967,total_num_recursivereplies=0,total_requestlist_exceeded=0,total_requestlist_current_user=0,total_recursion_time_avg=0,total_tcpusage=0,total_num_cachemiss=0 1510130793000000000 - -``` - -### Example Output (with thread_as_tag = true, unbound configured with num_threads: 2) - -``` - telegraf --config etc/telegraf.conf --input-filter unbound --test -* Plugin: inputs.unbound, Collection 1 -> 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 - -``` \ No newline at end of file diff --git a/plugins/inputs/unbound/unbound.go b/plugins/inputs/unbound/unbound.go index 21eee33a3..31a6d5005 100644 --- a/plugins/inputs/unbound/unbound.go +++ b/plugins/inputs/unbound/unbound.go @@ -35,31 +35,30 @@ var defaultBinary = "/usr/sbin/unbound-control" var defaultTimeout = internal.Duration{Duration: time.Second} var sampleConfig = ` - ## 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 timeout of 1s can be overriden with: - timeout = "1s" - - ## Use the builtin fielddrop/fieldpass telegraf filters in order to keep/remove specific fields - fieldpass = ["total_*", "num_*","time_up", "mem_*"] - - ## IP of server to connect to, read from unbound conf default, optionally ':port' + ## 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" - ## Output thread related values in a separate measurement "unbound_threads", with additional tag - ## "thread" identifying the thread number (0 ... the number of configured threads) - ## By default, thread related metrics are output as additional fields in a single metric point + ## 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 timeout of 1s can be overriden 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 change to + ## true in a future version. It is recommended to set to true on new + ## deployments. thread_as_tag = false ` // Description displays what this plugin is about func (s *Unbound) Description() string { - return "A plugin to collect stats from Unbound - a validating, recursive, and caching DNS resolver" + return "A plugin to collect stats from the Unbound DNS resolver" } // SampleConfig displays configuration instructions