Telegraf Basicstats 聚合器插件指标基础统计与聚合实践指南【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本指南围绕 Telegraf 中的basicstats聚合器插件展开讲解如何对采集到的指标进行计数、差值、最大/最小值、均值、方差、标准差等基础统计聚合并在每个period周期内输出聚合结果。读者将掌握basicstats的完整配置方法、15 种可选统计项的语义与输出字段命名规则、聚合器生命周期与窗口机制以及基于源码层面的在线方差算法实现细节。插件概述basicstats是 Telegraf 提供的标准聚合器插件之一用于在一段时间窗口内对一组指标进行计算输出count计数、diff差值、min最小值、max最大值、mean均值、non_negative_diff非负差值、rate每秒变化率等基础统计量。它自 Telegrafv1.5.0起提供属于statistics类别支持在所有平台上运行。与处理器processor逐条变换指标不同聚合器aggregator把一个周期内到达的多条指标合并为一条聚合结果非常适合用于削峰填谷、生成周期级监控汇总如 CPU 使用率均值、磁盘延迟峰值、连接数差值等。工作原理聚合器生命周期basicstats遵循 Telegraf 聚合器的标准生命周期接口见 aggregator.go由三个核心方法组成Add(in Metric)每收到一条输入指标时被调用将指标值累积进内部缓存Push(acc Accumulator)每个聚合周期结束时被调用把聚合结果写入 accumulator最终发给输出插件Reset()推送完成后清空内部缓存为下一个周期做准备。在 basicstats.go 的Add实现中插件以指标的HashID()作为缓存键每个测量名 标签组合独立聚合同一个键下每个字段各自维护一份独立的统计状态basicstats结构体。也就是说不同标签序列的指标不会被混算聚合结果保持了原有标签。窗口调度由 models/running_aggregator.go 中的RunningAggregator负责它会根据period、delay、grace计算聚合窗口起止时间把窗口之外早于窗口起点减去grace或晚于窗口终点加上delay的指标丢弃并在窗口结束时依次执行Push与Reset。从源码结构看Add、Push、Reset被RunningAggregator的互斥锁保护不会并发调用。配置指南最小可用配置在 Telegraf 配置文件中加入如下片段完整样例见 sample.conf# Keep the aggregate basicstats of each metric passing through. [[aggregators.basicstats]] ## The period on which to flush clear the aggregator. # period 30s ## If true, the original metric will be dropped by the ## aggregator and will not get sent to the output plugins. # drop_original false ## Configures which basic stats to push as fields # stats [count,min,max,mean,variance,stdev]通用参数basicstats支持聚合器插件通用的全局配置选项包括指标修改、标签/字段过滤、别名、插件执行顺序等详见 docs/CONFIGURATION.md。同时它自身包含以下关键参数参数类型默认值说明periodduration30s聚合器冲刷并清空内部缓存的周期即统计窗口长度drop_originalbooleanfalse为true时原始指标被聚合器丢弃不会转发给输出插件为false时原始指标照常输出statsarray of strings见下指定要输出哪些统计量字段stats参数的语义stats数组控制实际推送的统计字段basicstats.go 的初始化逻辑规定了三种情况不指定Stats为nil默认只聚合并输出count、min、max、mean、stdev、s2六个统计项。文档与源码均明确指出其余统计项默认不聚合是为了保持向后兼容——避免用户升级后系统毫无预兆地突然开始输出sum等新字段对应测试 TestBasicStatsWithDefaultStats 专门验证了默认不输出a_sum显式配置按数组中的名称逐个开启对应的统计项空数组[]不聚合任何统计量Push阶段不会产生任何输出点对应测试 TestBasicStatsWithNoStats。此外parseStats对未知的统计名称不会报错终止而是通过b.Log.Warnf(Unrecognized basic stat %q, ignoring, name)记录一条警告日志后忽略见 basicstats.go对应的 TestBasicStatsWithUnknownStat 验证了配置未知统计项时不会产生任何输出。启用全部统计项[[aggregators.basicstats]] period 30s drop_original true stats [count,min,max,mean,s2,stdev,sum,diff,non_negative_diff,rate,non_negative_rate,percent_change,interval,last,first]注意配置示例中的variance实际对应的输出字段名为_s2样本方差配置stats时同样使用s2这个名称。支持的统计项与输出字段basicstats对输入指标的每个数值型字段独立计算统计量输出字段名为原始字段名_统计项。原文档列出的字段族完整如下以field1为例field1_count周期内该字段的取值个数field1_diff差值最后一个值减前一个值field1_rate每秒变化率差值除以采样时间间隔field1_max最大值field1_min最小值field1_mean均值field1_non_negative_diff非负差值差值小于 0 时该字段不输出field1_non_negative_rate非负每秒变化率差值小于 0 时该字段不输出field1_percent_change百分比变化diff / 前值 * 100field1_sum求和field1_s2方差样本方差分母为 n-1field1_stdev标准差样本方差的平方根field1_interval采样时间间隔纳秒field1_last周期内最后到达的值field1_first周期内最先到达的值15 个统计项对应的stats配置名称与源码开关见 basicstats.go如下表stats配置名输出字段后缀含义默认开启count_count取值个数✔min_min最小值✔max_max最大值✔mean_mean均值✔s2_s2样本方差✔stdev_stdev样本标准差✔sum_sum求和✘diff_diff差值✘non_negative_diff_non_negative_diff非负差值✘rate_rate每秒变化率✘non_negative_rate_non_negative_rate非负每秒变化率✘percent_change_percent_change百分比变化✘interval_interval时间间隔ns✘last_last最后值✘first_first首值✘关于s2/stdev与count 1的特殊行为variance和stdev使用样本方差计算分母为count - 1见 basicstats.go。源码注释明确指出if count 1 StdDev infinite so I wont send data即当count 1时分母为 0、方差无穷大因此_s2、_stdev、_diff、_rate、_non_negative_diff、_non_negative_rate、_percent_change、_interval等依赖第二笔数据的统计量都不会输出——只有count、min、max、mean、sum、last、first这类单值即可确定的统计量会被推送。测试 TestBasicStatsDifferentPeriods 中单条指标m1单独推送时只输出 count/min/max/mean/last/first正是对这一行为的验证。字段类型与数据转换basicstats只会聚合数值型字段。Add内部通过convert函数见 basicstats.go把字段值转换为float64仅接受三种 Go 类型float64int64uint64字符串、布尔值等其他类型的字段会被静默跳过返回false不会进入聚合计算也不会导致错误。测试 basicstats_test.go 中的m2指标特意包含了ignoreme: string与andme: true两个非数值字段最终结果中确实不包含这两个字段的统计输出。算法细节在线方差与均值计算均值、方差、标准差的计算采用单趟在线算法Welford 算法源码注释引用了维基百科相关页面见 basicstats.go核心思路如下n : count 1 delta : x - mean mean mean delta / n m2 m2 delta * (x - mean)其中M2是累积的平方差和中间值最终方差s2 M2 / (count - 1)标准差stdev sqrt(s2)这种增量式算法的优点是不需要缓存全部历史数据内存占用恒定且数值稳定性优于先求和再套公式的朴素实现。差值系列统计diff、rate、percent_change依赖内部维护的PREVIOUS上一个值与TIME上一次采样时间两个中间值其中diff 当前值 - PREVIOUSinterval 当前时间 - TIMErate diff / interval.Seconds()percent_change diff / PREVIOUS * 100从测试 TestBasicStatsWithRate 可以印证m1与m2时间相差 1 毫秒字段b从 1 变到 3故b_diff 2、b_rate 2 / 0.001 2000。示例输出与逐步验证原文档给出的示例两次聚合周期如下system,hosttars load11 1475583980000000000 system,hosttars load11 1475583990000000000 system,hosttars load1_count2,load1_diff0,load1_rate0,load1_max1,load1_min1,load1_mean1,load1_sum2,load1_s20,load1_stdev0,load1_interval10000000000i,load1_last1 1475584010000000000 system,hosttars load11 1475584020000000000 system,hosttars load13 1475584030000000000 system,hosttars load1_count2,load1_diff2,load1_rate0.2,load1_max3,load1_min1,load1_mean2,load1_sum4,load1_s22,load1_stdev1.414162,load1_interval10000000000i,load1_last3,load1_first3 1475584010000000000逐条解读第一个聚合窗口两条原始指标load11、load11间隔 10 秒load1_count2窗口内共 2 个样本load1_diff0、load1_rate0两值相同差值为 0load1_max1、load1_min1、load1_mean1、load1_sum2常数序列的统计结果load1_s20、load1_stdev0无波动方差与标准差为 0load1_interval10000000000i相邻样本时间间隔 10 亿纳秒 10 秒整数类型字段以i后缀标记load1_last1最后到达的值。第二个聚合窗口两条原始指标load11、load13load1_count2、load1_diff2最后一个值 3 与前一个值 1 的差为 2load1_rate0.22 / 10秒 0.2即每秒增长 0.2load1_max3、load1_min1、load1_mean2、load1_sum4load1_s22、load1_stdev1.414162两个样本[1,3]的样本方差为(3-2)²(1-2)² / (2-1) 2标准差约为 √2load1_last3、load1_first3窗口内最后与最先到达的值。通过对比可以直观看出聚合结果完整继承了原始测量名system与标签hosttars只是把load1字段替换成了load1_*统计字段族。测试与行为保障basicstats_test.go 提供了非常全面的行为验证是理解插件语义的最佳参照周期内聚合TestBasicStatsWithPeriod 验证两个指标加入后的 count/min/max/mean/s2/stdev 全部结果跨周期行为TestBasicStatsDifferentPeriods 验证Push/Reset之间的状态隔离以及last、first在单条样本下的取值单统计项组合count、min、max、mean、sum、s2、stdev、diff、rate、non_negative_rate、percent_change、interval、non_negative_diff、last、first各有独立测试可直接对照预期的字段名与数值浮点精度TestBasicStatsWithOnlySumFloatingPointErrata 验证sum直接累加而非由mean * count推算避免1151被算成7.999999...的浮点误差默认与异常配置默认统计集、空数组、未知统计名均有对应测试性能基准BenchmarkApply 提供Add热路径的基准参考。插件注册与构建basicstats通过 basicstats.go 底部的aggregators.Add(basicstats, ...)注册进插件注册表。若使用自定义构建custom build可通过 plugins/aggregators/all/basicstats.go 中的构建标签!custom || aggregators || aggregators.basicstats精确控制是否打包该插件。实战建议用drop_original true降低写放大若只需要周期统计而无需原始点开启该选项可显著减少发往时序数据库的点数适合低频汇总场景period与采集间隔匹配聚合窗口建议取输入插件采集间隔的整数倍否则窗口内的样本数不稳定rate、interval的含义会偏移按需开启统计项默认只输出 6 项是为兼容旧行为新项目建议显式列出所需统计项避免输出冗余字段带来额外存储开销监控差值类指标diff/rate/non_negative_diff/percent_change非常适合计数器类指标如网络流量、连接数的周期增量观测注意方差为样本方差窗口内只有 1 个样本时不会输出s2/stdev等统计量查询时需按count 1过滤避免被空字段干扰。完整的实战配置示例[[inputs.cpu]] percpu true totalcpu true collect_cpu_time false report_active false # 每 60 秒对 CPU 指标做一次基础统计汇总并丢弃原始点 [[aggregators.basicstats]] period 60s drop_original true stats [count, min, max, mean, sum, s2, stdev, diff, rate]以上配置将每个 60 秒窗口内的 CPU 使用率聚合为usage_*_count、usage_*_mean、usage_*_max等字段便于后续按分钟粒度的告警阈值与趋势分析。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考