Telegraf unbound 输入插件采集 Unbound DNS 解析器统计指标的完整配置与实现解析【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本文基于 Telegraf 仓库中plugins/inputs/unbound/README.md及其配套源码 unbound.go、sample.conf、unbound_test.go 整理。该插件自 Telegraf v1.5.0 引入适用于所有平台server、network 类插件。它通过调用unbound-control命令行工具周期性采集 Unbound 递归 DNS 解析器的查询量、缓存命中率、递归时延、内存占用、DNSSEC 验证结果等统计指标并可开启线程级指标与递归查询时延直方图帮助你在 DNS 基础设施监控中定位解析性能退化、缓存异常与验证失败等问题。读完本文你可以完成插件的配置、权限设置组成员或 sudo 两种方式理解全部配置项的实际行为以及从源码层面弄清指标是如何从unbound-control的原始输出解析成 Telegraf 测量值的。工作原理shell out 到 unbound-control从源码看该插件并非通过 socket 直接读取统计数据而是在每次采集时shell out执行unbound-control二进制参数固定为stats_noreset读取统计但不重置计数器。核心采集逻辑在 Gather 方法与 unboundRunner 中调用链为init()将插件以名称unbound注册到输入插件注册表默认值Binary/usr/sbin/unbound-control、Timeout1s、UseSudofalse、Server、ThreadAsTagfalse、ConfigFile、Histogramfalse注册入口见 init 函数若配置了server先解析出host:port。由于unbound-control要求 IP 地址插件会用net.Resolver对该主机名做一次带超时timeout配置的 DNS 查询取第一个 IP再拼成-s IPport参数未显式指定端口时不追加端口参数若配置了config_file追加-c参数指向 unbound 配置文件若use_sudo true则改用sudo binary ...形式执行通过 internal.RunTimeout 启动命令并按timeout限制运行时间超时会尝试杀死进程标准输出即keyvalue形式的统计行。stats_noreset意味着采集是无副作用的计数器保持累计值插件重启或采集间隔变化都不会清零历史统计这对计算速率型指标如每秒查询量是必要的。配置插件的完整示例配置如下与仓库中 sample.conf 一致# 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各配置项的含义与源码行为对照如下配置项默认值说明server读取 unbound 自身配置unbound-control连接的地址可带:port。给主机名时插件会先做 DNS 解析再传 IP 给unbound-control源码强制要求 IPuse_sudofalse为true时以sudo前缀执行二进制用于受限用户场景binary/usr/sbin/unbound-controlunbound-control可执行文件路径config_file传给unbound-control -c的 unbound 配置文件路径默认读取系统默认配置timeout1s命令执行超时同时也是主机名解析的上下文超时超时后进程会被尝试终止thread_as_tagfalse为true时逐线程统计从unbound测量中拆出写入带thread标签的unbound_threads测量。默认false是向后兼容考虑官方建议新部署设为truehistogramfalse为true时额外采集递归查询时延直方图字段。注意直方图统计要求 unbound 侧开启extended-statistics: yes除插件自身配置外它同样支持 Telegraf 的全局与插件级配置选项字段/标签过滤、别名、插件排序等参见 docs/CONFIGURATION.md 的 Plugins 章节README 中该部分由 docs/includes/plugin_config.md 生成嵌入。权限设置文档特别强调插件依赖unbound-control该工具通常需要额外权限才能成功执行。取决于执行插件的 telegraf 用户/组权限你可能需要调整组成员、设置 ACL或使用 sudo。文档给出两种方案。方案一组成员推荐将 telegraf 用户加入 unbound 组$ groups telegraf telegraf : telegraf $ usermod -a -G unbound telegraf $ groups telegraf telegraf : telegraf unbound这是官方文档推荐的方式配置文件中无需任何额外项。方案二sudo 授权配置中开启[[inputs.unbound]] use_sudo true并在 sudoers 中追加visudo$ visudo # Add the following line: Cmnd_Alias UNBOUNDCTL /usr/sbin/unbound-control telegraf ALL(ALL) NOPASSWD: UNBOUNDCTL Defaults!UNBOUNDCTL !logfile, !syslog, !pam_session从源码看use_sudo true时命令会被重组为sudo /usr/sbin/unbound-control [-s IPport] [-c config] stats_noreset见 unboundRunner因此 sudoers 中放行的可执行文件路径必须与binary配置一致。文档最后建议选择你认为最合适的方案。输出指标插件输出的字段与 unbound 配置相关基础统计随unbound-control stats_noreset输出扩展统计extended statistics需要在 unbound 配置中开启extended-statistics: yes才会出现。原始统计名中的点号会被替换为下划线。下面列出 README 给出的完整字段清单。unbound整机级测量- 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字段大致分组total_*为查询/缓存/递归总量与请求队列水位time_*为时间戳与运行时长mem_*为内存模块占用num_query_*按查询类型、class、opcode、TCP/IPv6、DNS 头部标志位与 EDNS 维度计数num_answer_*为应答 rcode 与 DNSSEC 验证结果secure/bogusunwanted_*为被拒绝的查询与应答。unbound_threadsthread_as_tag true 时- unbound_threads - 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_medianhistogram 字段histogram true 时开启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示例输出unbound,hostlocalhost total_requestlist_avg0,total_requestlist_exceeded0,total_requestlist_overwritten0,total_requestlist_current_user0,total_recursion_time_avg0.029186,total_tcpusage0,total_num_queries51,total_num_queries_ip_ratelimited0,total_num_recursivereplies6,total_requestlist_max0,time_now1522804978.784814,time_elapsed310.435217,total_num_cachemiss6,total_num_zero_ttl0,time_up310.435217,total_num_cachehits45,total_num_prefetch0,total_requestlist_current_all0,total_recursion_time_median0.016384 1522804979000000000 unbound_threads,hostlocalhost,thread0 num_queries_ip_ratelimited0,requestlist_current_user0,recursion_time_avg0.029186,num_prefetch0,requestlist_overwritten0,requestlist_exceeded0,requestlist_current_all0,tcpusage0,num_cachehits37,num_cachemiss6,num_recursivereplies6,requestlist_avg0,num_queries43,num_zero_ttl0,requestlist_max0,recursion_time_median0.032768 1522804979000000000 unbound_threads,hostlocalhost,thread1 num_zero_ttl0,recursion_time_avg0,num_queries_ip_ratelimited0,num_cachehits8,num_prefetch0,requestlist_exceeded0,recursion_time_median0,tcpusage0,num_cachemiss0,num_recursivereplies0,requestlist_max0,requestlist_overwritten0,requestlist_current_user0,num_queries8,requestlist_avg0,requestlist_current_all0 1522804979000000000注意示例输出中的total_tcpusage、total_num_queries_ip_ratelimited、num_zero_ttl等字段README 的静态清单描述的是较基础的统计集而实际输出还包含 unbound 版本相关的扩展字段如 TCP 使用率、IP 限速、零 TTL 计数。这是因为插件对stats_noreset的输出生成式解析——任何形如keyvalue且值可解析为数字的行都会成为字段所以新版 Unbound 增加统计项时无需改动插件代码即可自动出现。源码级实现细节输出解析与容错Gather 用bufio.Scanner逐行读取命令输出按第一个切分键值每行必须恰好切出两段len(cols) 2否则整行静默跳过值用strconv.ParseFloat(value, 64)解析非数字时通过acc.AddError记录错误expected a numerical value for ...并跳过该行——注意这不会使整次采集失败而是部分容错其余统计名统一strings.ReplaceAll(stat, ., _)后进入unbound测量。这种宽松解析与测试文件中的断言一致TestParseFullOutput 用一段真实的unbound-control输出63 个字段验证默认模式TestParseFullOutputHistogram 验证开启直方图后字段数变为 103恰好多出 40 个histogram_*字段TestParseFullOutputThreadAsTag 与 TestParseFullOutputThreadAsTagHistogram 验证线程拆分后的两个测量。thread_as_tag 的拆分规则当ThreadAsTag为true时凡以thread开头的统计名如thread0.num.queries会被拆分去掉thread前缀的部分0作为thread标签值剩余 token 用下划线连接作为字段名num_queries归入unbound_threads测量见 Gather 中的线程分支 与 unbound_threads 写入。有两点值得注意线程号必须能解析为整数否则该行留在unbound测量中按普通点号替换处理该分支只在ThreadAsTag开启时生效。默认false时thread0.num.queries这类字段会以thread0_num_queries形式平铺在unbound测量里——测试期望值如thread0_num_queries证实了这一点。这也解释了 README 中默认 false 为向后兼容未来版本将改为 true新部署建议设为 true的含义。histogram 的命名归一化Unbound 扩展统计中直方图行形如histogram.000000.000512.to.000000.0010245503区间下界.to.上界。插件的处理是见 histogram 分支先判断是否以histogram.开头只有histogram true时才转换否则该行被完全丢弃不会以其他形式出现取.to.之前的部分作为 bin 下界再TrimLeft(suffix, 0)去掉前导零若结果以.开头原下界全零如000000.000000则补回一个0得到histogram_.000000因此histogram.000000.000512.to.000000.001024→ 字段histogram_.000512histogram.000001.000000.to.000002.000000→histogram_1.000000。测试期望表 parsedFullOutputHistogram 中histogram_.00000020、histogram_1.000000136等值可以直接对照验证。另外直方图行即使histogram false也会被识别为该分支只是不采集不会混入unbound普通字段——从分支顺序看histogram.前缀判断先于通用的点号替换分支执行。超时控制命令执行统一走 internal.RunTimeout先Start再WaitTimeout文档注释明确超时会尝试杀死进程。因此timeout同时约束 DNS 主机名解析resolver 上下文与命令本身运行时长对守护进程卡死的unbound-control起到兜底作用。采集失败的表现unboundRunner返回的错误主机名解析失败、无 IP、命令执行失败/超时会被Gather包装为error gathering metrics: ...向上返回导致本次采集记为错误并进入插件错误计数而不是部分写入。这一点与行级解析错误AddError后继续不同进程级失败整次丢弃行级失败只丢该行。验证采集可以使用--test参数只运行输入插件并输出到 stdout见 docs/COMMANDS_AND_FLAGS.md 中的说明快速验证插件配置与权限是否正确telegraf --config /etc/telegraf/telegraf.conf --test若权限不足通常会看到error running unbound-control ...之类的错误若server主机名无法解析则会看到error looking up ip for server ...或error no ip for server ...均出自 unboundRunner。正常时输出形如上文示例输出中的unbound,host...行。小结与注意事项插件本质是unbound-control stats_noreset的包装器二进制路径、配置文件、sudo 前缀、目标地址都是对这条命令的参数拼装理解命令即理解插件server填主机名可以但插件会替你做一次 DNS 解析若该解析本身依赖被监控的 Unbound要留意采集链路不形成自我依赖故障放大新部署建议thread_as_tag true以获得带thread标签的unbound_threads测量避免线程字段平铺在unbound上需要直方图时在 unbound 配置中开启extended-statistics: yes并在插件中设置histogram true字段数会从 63 增至 103以测试期望为准权限二选一加入 unbound 组推荐或按文档配置 sudoers 白名单后者需保证binary路径与 sudoers 中放行路径一致解析是所见即所得的宽松模式Unbound 版本升级带来的新统计项会自动映射为字段点换下划线排查字段缺失时优先核对 unbound 侧extended-statistics配置而不是插件本身。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考