dom
/
telegraf
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update unbound README

This commit is contained in:
Daniel Nelson 2018-05-23 12:22:25 -07:00
parent eb31ff3101
commit 893bc2790a
2 changed files with 94 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
plugins/inputs/unbound/README.md
View File

@ -1,56 +1,78 @@
# Unbound Input Plugin # 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: ### Configuration:
```toml ```toml
# A plugin to collect stats from Unbound - a validating, recursive, and caching DNS resolver # A plugin to collect stats from the Unbound DNS resolver
[[inputs.unbound]] [[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: ## If running as a restricted user you can prepend sudo for additional access:
# use_sudo = false # use_sudo = false
## The default location of the unbound-control binary can be overridden with: ## The default location of the unbound-control binary can be overridden with:
binary = "/usr/sbin/unbound-control" # binary = "/usr/sbin/unbound-control"
## The default timeout of 1s can be overriden with: ## The default timeout of 1s can be overriden with:
# timeout = "1s" # timeout = "1s"
## Use the builtin fielddrop/fieldpass telegraf filters in order to keep only specific fields ## When set to true, thread metrics are tagged with the thread id.
fieldpass = ["total_*", "num_*","time_up", "mem_*"] ##
## The default is false for backwards compatibility, and will be change to
## IP of server to connect to, read from unbound conf default, optionally ':port' ## true in a future version. It is recommended to set to true on new
## Will lookup IP if given a hostname ## deployments.
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 thread_as_tag = false
``` ```
### Measurements & Fields: #### Permissions:
This is the full list of stats provided by unbound-control and potentially collected by telegram 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, depending of your unbound configuration. Histogram related statistics will never be collected,
extended statistics can also be imported ("extended-statistics: yes" in 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 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). https://www.unbound.net/documentation/unbound-control.html for details).
Shown metrics are with `thread_as_tag` enabled.
- unbound - unbound
thread0_num_queries - fields:
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
total_num_queries total_num_queries
total_num_cachehits total_num_cachehits
total_num_cachemiss total_num_cachemiss
@ -102,54 +124,27 @@ https://www.unbound.net/documentation/unbound-control.html for details).
unwanted_queries unwanted_queries
unwanted_replies 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. ### Example Output:
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
``` ```
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
**Sudo privileges**: 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
If you use this method, you will need the following in your telegraf config: 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
```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.
### 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
``` ```

25
plugins/inputs/unbound/unbound.go
View File

@ -35,31 +35,30 @@ var defaultBinary = "/usr/sbin/unbound-control"
var defaultTimeout = internal.Duration{Duration: time.Second} var defaultTimeout = internal.Duration{Duration: time.Second}
var sampleConfig = ` var sampleConfig = `
## 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: ## If running as a restricted user you can prepend sudo for additional access:
# use_sudo = false # use_sudo = false
## The default location of the unbound-control binary can be overridden with: ## The default location of the unbound-control binary can be overridden with:
binary = "/usr/sbin/unbound-control" # binary = "/usr/sbin/unbound-control"
## The default timeout of 1s can be overriden with: ## The default timeout of 1s can be overriden with:
timeout = "1s" # timeout = "1s"
## Use the builtin fielddrop/fieldpass telegraf filters in order to keep/remove specific fields ## When set to true, thread metrics are tagged with the thread id.
fieldpass = ["total_*", "num_*","time_up", "mem_*"] ##
## The default is false for backwards compatibility, and will be change to
## IP of server to connect to, read from unbound conf default, optionally ':port' ## true in a future version. It is recommended to set to true on new
## Will lookup IP if given a hostname ## deployments.
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
thread_as_tag = false thread_as_tag = false
` `
// Description displays what this plugin is about // Description displays what this plugin is about
func (s *Unbound) Description() string { 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 // SampleConfig displays configuration instructions