Telegraf trig 输入插件详解：内置正弦/余弦演示数据源的配置、指标与源码剖析

Telegraf trig 输入插件详解：内置正弦/余弦演示数据源的配置、指标与源码剖析

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

trig 是 Telegraf 自带的一个演示型输入插件（input plugin），它按采集周期生成正弦（sine）与余弦（cosine）数值并以指标（metric）形式输出。阅读本文你将掌握该插件的完整配置方式、指标结构与输出示例，并理解其从插件注册（registry）、Gather采集逻辑到测试验证的源码级实现路径，以及如何在通用输入参数体系下灵活控制它的采集行为。

插件定位：为什么 Telegraf 内置一个"演示插件"

根据 plugins/inputs/trig/README.md 的说明，trig 插件的定位非常明确：

This plugin is for demonstration purposes and inserts sine and cosine values as metrics.

也就是说，它不采集任何真实系统数据，而是人为地生成一个连续变化的正弦/余弦波形序列。这类插件的实际价值在于：

• 验证数据链路：在没有真实监控对象时，用它给 Telegraf 喂入持续、可预测的指标流，验证「input → agent → output」整条管道是否通畅；
• 调试输出与序列化：其指标名、字段、时间戳完全确定，方便核对输出端（如 InfluxDB、Kafka 等）写入的数据格式是否正确；
• 理解插件机制：源码不到 40 行（trig.go），是学习 Telegraf 输入插件结构、注册流程与Accumulator用法的最小完整样本。

README 同时标注了插件的元信息：自 Telegraf v0.3.0 引入、状态为testing、支持所有平台（all）。testing状态表明它属于"用于内部测试/演示"的插件，生产环境中一般不应启用。

配置说明

trig 插件支持所有输入插件的通用全局配置（如alias、interval、name_suffix等），这部分内容见 docs/CONFIGURATION.md 的 Plugins 章节（对应 README 中通过<!-- @/docs/includes/plugin_config.md -->注释内嵌的 docs/includes/plugin_config.md 内容）：插件支持修改指标、tag、field，创建别名以及配置插件顺序等全局与插件级设置。

插件自身只有一个专有配置项，完整示例如下（与 plugins/inputs/trig/sample.conf 一致）：

# Inserts sine and cosine waves for demonstration purposes [[inputs.trig]] ## Set the amplitude amplitude = 10.0

参数说明：

参数	类型	默认值	说明
amplitude	float	0（结构体零值）	正弦/余弦波的振幅，即输出值的绝对值上限

需要注意：amplitude是 trig.go 中Trig结构体上唯一带toml标签的导出字段。若不显式配置，Go 结构体默认取零值0，插件会持续输出sine=0,cosine=0，因此演示时必须显式设置非零振幅（如示例中的10.0）。

作为输入插件，你还可以在其配置块中叠加任意通用输入参数，例如：

[[inputs.trig]] amplitude = 10.0 ## 覆盖 agent 的全局采集间隔，只对本插件实例生效 interval = "30s" ## 为本实例命名，便于区分多个 trig 实例 alias = "trig-demo" ## 重命名 measurement name_override = "demo_wave"

其中interval、alias、name_override等均为 docs/CONFIGURATION.md 中"Input Plugins"一节列出的通用参数：interval可覆盖 agent 的interval设定、控制采集频率；name_override可覆盖 measurement 的基础名（默认为插件名，即trig）。Telegraf 允许同名插件定义多个实例且各自独立运行，因此你也可以同时配置两组不同振幅的[[inputs.trig]]来产生两条波形。

指标结构与输出示例

插件产出的指标结构如下（继承自 plugins/inputs/trig/README.md 的 Metrics 一节）：

• measurement:trig
• fields:
  • sine(float)
  • cosine(float)

实际运行后的示例输出（line protocol 风格）：

trig,host=MBP15-SWANG.local cosine=10,sine=0 1632338680000000000 trig,host=MBP15-SWANG.local sine=5.877852522924732,cosine=8.090169943749473 1632338690000000000 trig,host=MBP15-SWANG.local sine=9.510565162951535,cosine=3.0901699437494745 1632338700000000000

从示例可以读出三件事：

1. measurement 名为trig，并自动附带了host标签（由 agent 全局标签机制添加，插件自身不设置任何 tag）；
2. 每个字段为 float，数值范围被amplitude约束在[-amplitude, amplitude]；
3. 时间戳以 10 秒递增，对应默认的采集间隔。

源码剖析：Gather 中的相位推进机制

下面结合 plugins/inputs/trig/trig.go 逐段说明实现。

数据结构

type Trig struct { Amplitude float64 `toml:"amplitude"` x float64 }

• Amplitude：导出字段，带toml:"amplitude"标签，是配置系统注入的唯一参数；
• x：私有字段，是相位计数器——每采集一次累加 1，决定了波形的自增相位。它不对外配置，完全由插件实例在内存中维护，这意味着振幅相同时，波形相位会随进程运行时间持续前移而非重置。

采集逻辑

func (s *Trig) Gather(acc telegraf.Accumulator) error { sinner := math.Sin((s.x*math.Pi)/5.0) * s.Amplitude cosinner := math.Cos((s.x*math.Pi)/5.0) * s.Amplitude fields := make(map[string]interface{}) fields["sine"] = sinner fields["cosine"] = cosinner tags := make(map[string]string) s.x += 1.0 acc.AddFields("trig", fields, tags) return nil }

几个关键点：

• 相位步进为 π/5：每次Gather时计算sin(x·π/5)与cos(x·π/5)再乘以振幅，随后s.x += 1.0。因此每 10 个采集周期完成一个完整周期（x 从 0 到 10 恰好转过 2π）。对照示例输出首行sine=0, cosine=10（x=0 时 sin0=0、cos0=1），第二行sine≈5.878, cosine≈8.090（x=1，即 π/5=36° 处）完全吻合；
• 先计算、后自增：代码先用当前x计算再累加，保证第一个采集点固定为sine=0, cosine=amplitude，输出序列可预期；
• 通过Accumulator.AddFields提交：measurement固定为trig，tags 为空 map——host 等标签由 agent 层统一附加，插件不参与；
• Gather恒返回nil，不存在失败分支，这也是演示插件的典型特征。

注册与编译开关

插件通过init()函数完成自注册（trig.go）：

func init() { inputs.Add("trig", func() telegraf.Input { return &Trig{x: 0.0} }) }

这里的inputs.Add定义在 plugins/inputs/registry.go：它把插件名trig与创建函数存入全局 mapInputs，配置系统在解析到[[inputs.trig]]时即通过该 map 实例化插件。

是否将插件编入二进制，由构建标签（build tag）控制。plugins/inputs/all/trig.go 的内容是：

//go:build !custom || inputs || inputs.trig import _ "github.com/influxdata/telegraf/plugins/inputs/trig" // register plugin

含义是：默认构建（无custom标签）或显式指定inputs/inputs.trig标签时，init()中的注册代码才会参与编译。若你用tools/custom_builder做定制构建且未勾选 trig，该插件将不存在于二进制中。此外，文件首行//go:generate注释表明 sample.conf 与 README 的配置片段通过tools/readme_config_includer生成器保持同步——README 中```toml @sample.conf语法的配置块正是直接内嵌自 sample.conf。

测试验证：波形正确性如何被断言

plugins/inputs/trig/trig_test.go 用一个简洁的循环测试锁定了插件行为：

func TestTrig(t *testing.T) { s := &Trig{Amplitude: 10.0} for i := 0.0; i < 10.0; i++ { var acc testutil.Accumulator sine := math.Sin((i*math.Pi)/5.0) * s.Amplitude cosine := math.Cos((i*math.Pi)/5.0) * s.Amplitude require.NoError(t, s.Gather(&acc)) // ... acc.AssertContainsFields(t, "trig", fields) } }

测试连续调用Gather10 次（恰好一个完整周期），每次都按i·π/5独立推算期望的sine/cosine值，并用testutil.Accumulator的AssertContainsFields断言 measurementtrig中两个字段值与数学期望一致。这同时验证了两件事：计算公式的正确性，以及x计数器随调用递增的相位推进行为（若忘记s.x += 1.0，第二轮之后所有断言都会失败）。

小结

trig 插件虽然只暴露amplitude一个配置项、只产出sine/cosine两个字段，但它以最小的代码完整展示了 Telegraf 输入插件的核心要素：

要素	在 trig 中的体现	参考文件
配置定义	Trig.Amplitude+toml标签	trig.go
插件注册	inputs.Add("trig", ...)+ 全局Inputsmap	registry.go
采集入口	Gather(acc telegraf.Accumulator)，acc.AddFields提交指标	trig.go
行为契约	单周期 10 步、相位步进 π/5 的字段断言	trig_test.go
文档同步	@sample.conf内嵌机制	plugins/inputs/trig/README.md、sample.conf

当你在联调 Telegraf 数据管道、验证输出插件写入格式，或想快速看懂输入插件的骨架结构时，启用[[inputs.trig]]并设置一个非零amplitude，就是成本最低的起点。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf