Telegraf Merge 聚合器插件按序列键合并多条指标为多字段指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafMerge 聚合器aggregator是 Telegraf 中一类以“变换transformation”为目的的聚合插件用于将同一序列series且同一时间戳下的多条指标合并为一条携带超集字段super-set of fields的新指标。当你的数据源把同一测量名、同一标签集、同一时间戳下的字段拆散成多条指标输出时本文介绍的 Merge 插件 就是将它们重新归并为一条完整指标的最直接方案。读完本文你将掌握 merge 插件的适用场景、全部配置参数、底层合并原理SeriesGrouper 分组机制以及如何通过测试用例验证其行为。⭐ Telegraf v1.13.0 引入 分类transformation 支持平台all插件定位与适用场景在 Telegraf 中指标由measurement测量名、tags标签键值集、fields字段集与timestamp时间戳构成。Merge 插件解决的是这样一类问题字段被拆分到多条指标中但这些指标拥有相同的 measurement、相同的 tag 集合、相同的时间戳。典型的例子来自批量写入型数据源如 InfluxDB 行协议、文件输入、exec 输出等它们可能在时间戳相同时发出两条记录cpu,hostlocalhost usage_time42 1567562620000000000 cpu,hostlocalhost idle_time42 1567562620000000000这两条指标携带同一时间戳1567562620000000000、同一标签集hostlocalhost却各自只有一个字段。Merge 插件会将其合并为一条携带字段超集的指标cpu,hostlocalhost idle_time42,usage_time42 1567562620000000000这里“系列series”的定义是measurement 名称 tag 键值集合。也就是说合并分组以测量名与标签为唯一标识相同 series 且相同时间戳的指标才会被归并到同一条结果中。工作原理分组、合并与周期推送从源码结构看merge 插件实现了 aggregator.go 中定义的telegraf.Aggregator接口包含Add、Push、Reset三个核心方法并在 merge.go 中借助metric.SeriesGrouper完成核心合并逻辑Add(m)将输入指标写入分组器。若配置了round_timestamp_to会先对指标时间戳做取整ts.Round(...)再调用a.grouper.AddMetric(gm)归组。Push(acc)在每个聚合周期结束时被调用将分组器内已合并好的全部指标通过 accumulator 送出。值得注意的是源码中强制设置了纳秒级精度acc.SetPrecision(time.Nanosecond)避免因 agent 默认精度较低而二次舍入已合并指标的时间戳。Reset()周期结束后清空分组器缓存为下一个聚合周期做准备。SeriesGrouper底层合并机制分组与合并的核心实现位于 series_grouper.goAddMetric先根据measurement、排序后的taglist与timestamp计算出一个 64 位哈希 ID见groupID使用maphash对测量名、标签键值、时间戳纳秒值做哈希。若该 ID 尚未出现则复制当前指标作为分组的“种子”指标若已存在则遍历新指标的字段列表逐个通过AddField并入已有指标。Metrics()返回按首次出现顺序排列的已合并指标列表。字段的合并最终落在 metric.go 的AddField上同名字段会被新值覆盖先遍历已有字段命中则更新否则追加。因此当同系列同时间戳的多条指标出现同名字段时后到的字段值会覆盖先到的值——这在实际使用中需要注意字段命名冲突。从 running_aggregator.go 可以看到聚合器由RunningAggregator包装运行它会先执行指标过滤Filter.Select/Filter.Modify再判断指标时间戳是否落在[periodStart - Grace, periodEnd Delay]的聚合窗口内最后才调用Aggregator.Add并把返回的DropOriginal作为“是否丢弃原始指标”的依据。配置参数详解Merge 插件在 sample.conf 中提供了完整可复制的配置模板# Merge metrics into multifield metrics by series key [[aggregators.merge]] ## General Aggregator Arguments: ## The period on which to flush clear the aggregator. # period 30s ## Precision to round the metric timestamp to ## This is useful for cases where metrics to merge arrive within a small ## interval and thus vary in timestamp. The timestamp of the resulting metric ## is also rounded. # round_timestamp_to 1ns ## If true, the original metric will be dropped by the ## aggregator and will not get sent to the output plugins. drop_original true各参数含义如下参数类型默认值说明period时长字符串30s所有聚合器共有的通用参数表示聚合器刷出并清空缓存的周期。可选值如30s、1m、5m等。round_timestamp_to时长字符串0不取整指标时间戳的取整精度。当待合并的指标在很小时时间窗口内到达、时间戳略有差异时使用该参数使它们能归并到同一时间戳合并结果指标的时间戳同样会被取整。默认不取整即完全依赖指标自带时间戳完全一致。drop_original布尔true是否丢弃原始指标。为true时进入聚合器的原始指标不会再发送到输出插件避免“原始拆分指标 合并后指标”重复落库。关于round_timestamp_to的取值建议该参数在 merge.go 中通过ts.Round(time.Duration(a.RoundTimestamp))实现。只有当配置值大于 0 时才会执行取整且取整会作用于合并前后指标的时间戳。常见取整粒度可以是1ms、100ms、1s等具体取决于你的数据源时间戳抖动幅度抖动越大取整粒度应越大但也意味着时间戳精度损失越大。一个典型使用组合是输入插件如inputs.file、inputs.exec、inputs.socket_listener在极短时间内连续吐出同系列、时间戳仅相差毫秒级的多条指标此时设置round_timestamp_to 1ms或1s即可将它们在时间维度上对齐并完成合并。完整使用示例在telegraf.conf中启用合并并丢弃原始指标[[inputs.exec]] commands [/path/to/script.sh] interval 10s [[aggregators.merge]] period 10s round_timestamp_to 1s drop_original true [[outputs.influxdb]] urls [http://localhost:8086]若输入产生的原始指标为cpu,hostlocalhost usage_time42 1567562620000000000 cpu,hostlocalhost idle_time42 1567562620000000000经过 merge 聚合后输出插件收到的将只有一条合并结果cpu,hostlocalhost idle_time42,usage_time42 1567562620000000000由于drop_original true上述两条原始指标不会再被转发到输出端。这与 README 中给出的 diff 示例完全一致- cpu,hostlocalhost usage_time42 1567562620000000000 - cpu,hostlocalhost idle_time42 1567562620000000000 cpu,hostlocalhost idle_time42,usage_time42 1567562620000000000与全局配置选项的关系和其他插件一样merge 聚合器同样支持 Telegraf 的通用配置选项例如通过alias命名多个实例、通过name_override/name_prefix/name_suffix改写测量名、通过tags附加标签以及 metric filteringpass/drop/tagpass等来限定参与聚合的指标范围。详细清单可参考 docs/CONFIGURATION.md#plugins 中的“Plugins”一节。源码级行为验证测试用例解读merge_test.go 提供了对插件行为的完整验证可作为理解语义的最佳注脚TestSimple验证相同系列、相同时间戳的两条指标time_idle与time_guest被合并为一条双字段指标。TestNanosecondPrecision验证即使 accumulator 被设置为秒级精度Push内部仍强制使用纳秒精度合并后指标时间戳保持1ns不丢失。TestNoRounding验证未配置round_timestamp_to时时间戳不同1ns 与 2ns的同系列指标不会被合并保持两条独立指标输出。TestWithRounding验证配置round_timestamp_to 10ns后时间戳 1ns 与 2ns 的两条指标被取整到 0ns 并成功合并为一条。TestReset验证Reset后分组器清空下一周期的指标不会与上一周期残留数据错误合并。这组测试直观地揭示了插件的两个关键语义时间戳必须经取整后一致才合并取整参数是触发跨微小时间差合并的唯一开关。注册与使用注意点从源码结构看merge 插件通过 registry.go 中的aggregators.Add(merge, ...)完成注册并由plugins/aggregators/all目录下的导入文件纳入 Telegraf 构建。若你使用自定义构建custom builder需确保聚合器构建标签如aggregators或aggregators.merge被包含。实际使用中还需注意以下几点合并依赖时间戳完全一致在不设置round_timestamp_to时纳秒级时间戳不同的指标不会被合并这是有意设计见 TestNoRounding。同名字段存在覆盖语义后到的同名字段值会覆盖先到值由AddField行为决定规划字段名时应避免冲突。drop_original与持久化若drop_original false原始拆分指标与合并后指标都会输出输出端可能产生数据冗余。内存占用合并需要在一个period内缓存同系列指标的字段指标基数越高聚合器缓存占用越大需合理规划period。小结Merge 聚合器以“测量名 标签集 时间戳”为分组键将字段碎片化的多条指标归并为一条多字段指标是处理同系列多字段分散输出的实用工具。其配置精简仅三个参数、语义清晰时间戳对齐才合并配合round_timestamp_to可从容应对微小时间戳抖动的场景。如需了解全部聚合器插件的通用行为可继续阅读 docs/AGGREGATORS.md 与 docs/CONFIGURATION.md。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
