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

161
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]]
## If running as a restricted user you can prepend sudo for additional access: ## Address of server to connect to, read from unbound conf default, optionally ':port'
#use_sudo = false ## 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: ## If running as a restricted user you can prepend sudo for additional access:
binary = "/usr/sbin/unbound-control" # use_sudo = false
## The default timeout of 1s can be overriden with: ## The default location of the unbound-control binary can be overridden with:
#timeout = "1s" # binary = "/usr/sbin/unbound-control"
## Use the builtin fielddrop/fieldpass telegraf filters in order to keep only specific fields ## The default timeout of 1s can be overriden with:
fieldpass = ["total_*", "num_*","time_up", "mem_*"] # timeout = "1s"
## IP of server to connect to, read from unbound conf default, optionally ':port' ## When set to true, thread metrics are tagged with the thread id.
## Will lookup IP if given a hostname ##
server = "127.0.0.1:8953" ## 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
## Output thread related values in a separate measurement "unbound_threads", with additional tag ## deployments.
## "thread" identifying the thread number (0 ... the number of configured threads) thread_as_tag = false
## By default, thread related metrics are output as additional fields in measurement "unbound"
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 of your unbound configuration. Histogram related statistics will never be collected, 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). 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
```

33
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 = `
## If running as a restricted user you can prepend sudo for additional access: ## Address of server to connect to, read from unbound conf default, optionally ':port'
#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'
## Will lookup IP if given a hostname ## Will lookup IP if given a hostname
server = "127.0.0.1:8953" server = "127.0.0.1:8953"
## Output thread related values in a separate measurement "unbound_threads", with additional tag ## If running as a restricted user you can prepend sudo for additional access:
## "thread" identifying the thread number (0 ... the number of configured threads) # use_sudo = false
## By default, thread related metrics are output as additional fields in a single metric point
## 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 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