Telegraf Split 处理器：用模板将单条指标拆分、重组为多条指标

Telegraf Split 处理器用模板将单条指标拆分、重组为多条指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Split 处理器是 Telegrafv1.28.0 起引入提供的一类 transformation转换类处理器插件其核心能力是基于用户定义的模板把一条指标拆分成一条或多条新指标。它适用于一条采集数据里混杂了多组业务数据的场景——例如一次采集返回了多个传感器的通道数据需要按传感器拆分后再分别写入时序库。读完本文你将掌握processors.split的完整配置语法、字段/标签过滤规则、drop_original的取舍策略以及从源码与测试用例角度理解其底层行为与踩坑点。插件定位与适用场景Split 插件在 Telegraf 中属于数据整形类处理器作用于指标从输入到输出之间的处理链。它解决的核心问题是单条指标中承载了过多维度信息导致下游按业务维度分析、告警或存储时难以拆分。典型场景包括一次 HTTP 采集接口返回了多个传感器的数据全部堆在同一条指标上需要按传感器拆成多条独立指标一条指标同时携带了需要发往不同目标或按不同周期处理的多组字段需要把原始指标复制成多份分别应用不同的字段子集进行后续处理。从源码结构看插件定义在 plugins/processors/split/split.go并在init()中通过processors.Add(split, ...)注册为名为split的处理器见 split.go因此配置段名为[[processors.split]]。插件的官方元数据元信息标注为版本Telegraf v1.28.0 引入分类transformation转换类支持平台all全平台配置详解模板、字段与标签完整配置样例插件在仓库中的官方示例配置为 sample.conf完整内容如下# Split a metric into one or more metrics with the specified field(s)/tag(s) [[processors.split]] ## Keeps the original metric by default # drop_original false ## Template for an output metric ## Users can define multiple templates to split the original metric into ## multiple, potentially overlapping, metrics. [[processors.split.template]] ## New metric name name ## List of tag keys for this metric template, accepts globs, e.g. * tags [] ## List of field keys for this metric template, accepts globs, e.g. * fields []参数说明配置项类型默认值必填说明drop_originalbooleanfalse否是否丢弃原始指标仅保留模板生成的拆分结果默认保留原始指标template.namestring—是拆分后新指标的名称不能为空否则插件Init()阶段直接报错template.tags[]string[]否要复制到新指标的标签 key 列表支持 glob 通配如*、sensor1*不配置则新指标不含任何标签template.fields[]string[]是要复制到新指标的字段 key 列表支持 glob 通配至少需要一项否则Init()报错关于以上约束源码中有明确的硬校验逻辑。在 split.go 的Init()方法中未配置任何template时返回at least one template required任一模板的name为空时返回metric name cannot be empty任一模板的fields为空时返回at least one field is required for a valid metric字段与标签列表都会通过filter.Compile(...)编译为过滤匹配器编译失败会以failed to create new field filter/failed to create new tag filter报错说明 glob 语法与 Telegraf 全局 filter 的匹配规则一致。drop_original的行为在 split.go 中体现当其为true时对原始指标调用point.Accept()直接消费掉等价于丢弃为false默认时则把原始指标原样保留在输出队列中。模板可重叠模板之间是互相独立的允许重叠同一个字段或标签可以出现在多个模板中从而被复制进多条新指标。例如传感器 1 与传感器 2 共享的host标签可以同时进入两个模板的输出指标。这正是拆分与复制之间的平衡点——它不只做切分也能按需复制数据。核心行为拆分规则与无匹配处理拆分处理流程从 split.go 的Apply()方法可以看到逐条指标的处理流程对每条输入指标先根据drop_original决定保留或丢弃原始指标遍历每一个模板用模板的字段过滤器匹配原始指标的所有字段命中者收集进新指标的fields若模板配置了tags用标签过滤器匹配原始指标的所有标签命中者收集进新指标的tags未配置tags时新指标不复制任何标签关键规则若某模板在原始指标上没有任何命中字段len(fields) 0则该模板跳过不生成输出指标新指标使用metric.New(template.Name, tags, fields, point.Time())创建时间戳完全继承原始指标的时间戳不做重打时间戳。这一点值得强调没有字段命中的模板不会产生空指标。结合drop_original true 且所有模板都未命中的情况就会导致全部指标被丢弃。关于 drop_original 与数据丢失的警告官方 README 给出了明确的警示见 plugins/processors/split/README.md如果将 drop_original 改为 true当没有任何模板匹配时插件可能导致丢弃全部指标请务必在上生产环境前测试模板并使用指标过滤以避免数据丢失。这是一个容易被忽略的数据安全风险。从源码看drop_original true时原始指标被直接Accept()而每个模板无命中即跳过二者叠加的结果就是一旦模板的 glob 写错、字段名对不上输入指标将全部消失。官方给出的缓解手段包括先小流量验证模板配合 Telegraf 的metricpass/tagexclude等过滤见 docs/CONFIGURATION.md控制进入该处理器的指标范围。完整示例双传感器指标拆分官方 README 给出了一个典型的双传感器拆分场景见 plugins/processors/split/README.md 的 Example 小节把一条携带两个传感器数据的指标拆分成sensor1和sensor2两条独立指标并把原始指标的所有标签复制给新指标。配置如下[[processors.split]] drop_original true [[processors.split.template]] name sensor1 tags [ * ] fields [ sensor1* ] [[processors.split.template]] name sensor2 tags [ * ] fields [ sensor2* ]输入指标metric,statusactive sensor1_channel14i,sensor1_channel22i,sensor2_channel11i,sensor2_channel22i 1684784689000000000输出指标sensor1,statusactive sensor1_channel14i,sensor1_channel22i 1684784689000000000 sensor2,statusactive sensor2_channel11i,sensor2_channel22i 1684784689000000000可以看到tags [*]把statusactive完整复制给了两条新指标fields [sensor1*]/fields [sensor2*]通过 glob 前缀匹配把各自传感器通道的字段分拣到对应指标时间戳1684784689000000000原样保留。测试用例佐证五种典型行为的验证插件的行为在仓库中有完整的测试覆盖测试入口见 split_test.go其TestCases会遍历 testcases 目录下的每一个子目录用其中的config.toml加载配置、用input.influx作为输入、用expected.out作为期望输出逐一比对。以下五个用例正好覆盖了插件的主要行为分支1. singlemetric保留原始 精确字段拆分配置见 testcases/singlemetric/config.toml未设置drop_original默认为 false两个模板使用精确字段名。期望输出expected.out为metric sensor1_channel14i,sensor1_channel22i,sensor2_channel11i,sensor2_channel22i 1684784689000000000 sensor1 sensor1_channel14i,sensor1_channel22i 1684784689000000000 sensor2 sensor2_channel11i,sensor2_channel22i 1684784689000000000验证点默认保留原始指标模板按精确字段名拆分未配置tags时新指标不带任何标签。2. drop_original丢弃原始指标配置见 testcases/drop_original/config.toml设置drop_original true。期望输出expected.out中只剩两条新指标sensor1 sensor1_channel14i,sensor1_channel22i 1684784689000000000 sensor2 sensor2_channel11i,sensor2_channel22i 16847846890000000003. globsglob 同时作用于字段与标签配置见 testcases/globs/config.toml字段使用sensor1*/sensor2*标签使用sensor1*/sensor2*加host。输入指标为metric,sensor1_statusactive,sensor2_statusfailed,hostfoobar sensor1_channel14i,sensor1_channel22i,sensor2_channel11i,sensor2_channel22i 1684784689000000000期望输出expected.out展示了 glob 标签过滤与原始指标保留的叠加效果metric,sensor1_statusactive,sensor2_statusfailed,hostfoobar sensor1_channel14i,sensor1_channel22i,sensor2_channel11i,sensor2_channel22i 1684784689000000000 sensor1,sensor1_statusactive,hostfoobar sensor1_channel14i,sensor1_channel22i 1684784689000000000 sensor2,sensor2_statusfailed,hostfoobar sensor2_channel11i,sensor2_channel22i 1684784689000000000验证点模板 1 只带走sensor1_status标签模板 2 只带走sensor2_status标签而host被两个模板共享——这正是模板可重叠、同一标签可进入多条指标的实证。4. tags仅复制指定标签配置见 testcases/tags/config.toml标签使用精确列表[status, hostname]。期望输出expected.out中两条新指标均完整携带status与hostname标签metric,statusactive,hostnamefoobar sensor1_channel14i,sensor1_channel22i,sensor2_channel11i,sensor2_channel22i 1684784689000000000 sensor1,statusactive,hostnamefoobar sensor1_channel14i,sensor1_channel22i 1684784689000000000 sensor2,statusactive,hostnamefoobar sensor2_channel11i,sensor2_channel22i 16847846890000000005. nomatches模板零命中时保留原始指标配置见 testcases/nomatches/config.toml输入指标metric,tagfake value42 ...中没有任何字段能命中模板的字段列表。期望输出expected.out仅为metric,tagfake value42 1684784689000000000验证点模板无命中时不产生任何新指标由于drop_original默认为 false原始指标被完整保留。这个用例从正面印证了官方警告的机理——若此处drop_original true输出将为空。与其他配置机制的配合全局配置选项与所有 Telegraf 插件一样processors.split也支持 docs/CONFIGURATION.md 中描述的全局配置选项例如通过namepass/namedrop决定哪些指标进入该处理器、通过fieldpass/tagpass预先过滤输入等。由于插件存在无命中即可能丢数据的特性建议在使用drop_original true时用全局指标过滤把预期一定会命中模板的指标限定在最小范围内降低误伤面。处理器执行顺序Split 属于 processors 阶段其执行顺序遵循 docs/CONFIGURATION.md 与 docs/AGGREGATORS_AND_PROCESSORS.md 描述的处理器链规则在聚合器aggregators之前按配置顺序执行。因此拆分后的指标会继续流经后续处理器并最终被序列化输出。关于输出的注意事项官方 README 还给出了一条针对输出的提示见 plugins/processors/split/README.md某些输出对产生的指标序列数量较为敏感。相同序列相同的名称、标签键值、字段名的多条指标若带有相同时间戳可能被压缩为最后产生的那条指标。这意味着如果你的模板可能把同一批字段拆分成多条同序列同时戳的指标下游如 InfluxDB 等按时间戳写入的时序库可能会发生覆盖squashing需要结合输出端的写入策略如 docs/CONFIGURATION.md 中输出插件的 flush 与数据写入设置合理设计模板避免无意义的数据挤压。从源码看实现细节最后把插件的核心实现路径汇总如下方便需要深入源码的读者对照注册init()中processors.Add(split, ...)split.go配置段名固定为[[processors.split]]配置校验Init()中校验模板数量、名称非空、字段列表非空并预编译字段/标签过滤器split.go数据转换Apply()中按保留/丢弃原始指标 → 逐模板匹配字段与标签 → 无字段命中则跳过 → 以原始时间戳构造新指标的顺序处理split.go追踪指标支持TestTrackingMetrics测试split_test.go验证了插件对 tracking metrics 的兼容——被丢弃的原始指标会正确触发送达回调拆分产生的新指标被下游Accept()后输入端的追踪计数能够正常收敛不会出现送达信息泄漏。综合来看Split 处理器是一个小而精的转换工具它用最少的配置项drop_original 若干模板提供了字段/标签级 glob 过滤、模板重叠复制、原始指标保留/丢弃等能力。使用时的两个关键纪律是模板fields至少一项且名称非空否则无法启动、drop_original true前务必验证模板命中率否则可能静默丢数据。掌握了这两点你就能安全地在 Telegraf 管线中用它完成各类指标拆分与重组任务。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考