Telegraf 外部插件External Plugins开发指南借助 execd 与 Execd Go Shim 扩展插件生态【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的插件系统虽然以 Go 编写、随主仓库统一发布但通过execd机制任何人都可以在 Telegraf 之外用任意语言编写、构建并运行独立的输入input、处理器processor与输出output插件本文即围绕这一机制展开。读完本文你将掌握外部插件的设计动机、execd三类插件inputs.execd / processors.execd / outputs.execd的接入方式、以及如何借助plugins/common/shim把 Telegraf 内置插件一键外部化并独立构建运行。什么是 Telegraf 外部插件外部插件External Plugins指在 Telegraf 主仓库之外构建的外部程序它们不随 Telegraf 二进制编译而是通过execd插件作为独立进程被 Telegraf 拉起以标准输入stdin/ 标准输出stdout与 Telegraf 通信。官方入口文档位于 docs/EXTERNAL_PLUGINS.md完整收录清单见仓库根目录的 EXTERNAL_PLUGINS.md。相比只能在 Telegraf 内部用 Go 编写的内置插件外部插件提供了显著更大的灵活性语言自由外部插件可以用任意语言编写内置插件只能用 Go库生态不受限可以访问非 Go 语言的库包括需要 CGO 支持的第三方库可引入闭源软件能够利用不开放给开源社区的许可软件控制二进制体积可以携带大型依赖而不会撑大 Telegraf 本身的发布体积发布节奏自主不必等待 Telegraf 团队发布插件即可开始使用内外转换简单借助 shim可以轻松在内部插件与外部插件之间互相转换。需要强调的是外部插件并不豁免插件作者的职责外部插件的作者同时负责其维护与功能迭代用户大概率会在其各自的仓库上直接提交 issue见 docs/EXTERNAL_PLUGINS.md 中的说明。外部插件的通信载体execd 插件家族外部程序之所以能接入 Telegraf依靠的是三个execd插件它们是外部插件在 Telegraf 侧的宿主插件通信方向说明inputs.execd进程 stdout → Telegraf将外部程序作为常驻守护进程从 stdout 按数据格式读取指标processors.execdTelegraf stdin → 进程 → stdout将指标通过 stdin 送入外部进程再从 stdout 读回处理结果outputs.execdTelegraf stdin → 进程将指标写入外部守护进程的 stdin由外部程序负责写出inputs.execd把外部程序当作指标源inputs.execd 运行给定的外部程序作为长驻守护进程并按 docs/DATA_FORMATS_INPUT.md 中列出的数据格式解析进程 stdout 上的指标。程序预期持续运行并在收到配置的signal时输出数据。进程的stderr会被转发到 Telegraf 日志默认按 error 级别记录也可以用E!error、W!warning、I!info、D!debug、T!trace前缀加空格来控制日志级别例如输出I! A log message会在 Telegraf 日志中生成一条 info 记录。其最小支持版本为 Telegraf v1.14.0示例配置见 sample.conf# Run executable as long-running input plugin [[inputs.execd]] ## One program to run as daemon. ## NOTE: process and each argument should each be their own string command [telegraf-smartctl, -d, /dev/sda] ## Environment variables ## Array of keyvalue pairs to pass as environment variables # environment [] ## Define how the process is signaled on each collection interval. ## Valid values are: ## none : Do not signal anything. (Recommended for service inputs) ## The process must output metrics by itself. ## STDIN : Send a newline on STDIN. (Recommended for gather inputs) ## SIGHUP : Send a HUP signal. Not available on Windows. (not recommended) ## SIGUSR1 : Send a USR1 signal. Not available on Windows. ## SIGUSR2 : Send a USR2 signal. Not available on Windows. # signal none ## Delay before the process is restarted after an unexpected termination # restart_delay 10s ## Buffer size used to read from the command output stream ## Optional parameter. Default is 64 Kib, minimum is 16 bytes # buffer_size 64Kib ## Disable automatic restart of the program and stop if the program exits ## with an error (non-zero error code) # stop_on_error false ## Data format to consume. # data_format influxsignal是 input 场景下最关键的选项对于按采集周期主动 gather 的程序建议用STDIN每次向 stdin 发送一个换行触发采集对于自行持续输出指标的 service 型程序建议用none。仓库中附带四种语言的示例程序可对照不同 signal 用法count.go期望SIGHUP、count.pynone、count.rbnone、count.shSTDIN。processors.execd把外部程序当作流式处理器processors.execd 将指标通过 stdin 送入外部进程并从其 stdout 读回处理后的指标stderr输出会被记录到日志。它有两个重要注意点见其 README带追踪tracking的指标在传入外部进程那一刻即被视为已投递目前无法将 execd 进程输出的指标与进入的指标一一对应处理器可能增删指标且全程异步目前只能使用data_format influx因为必须要求序列化-解析对称且不丢失关键类型数据。其配置结构如下完整示例见 sample.conf# Run executable as long-running processor plugin [[processors.execd]] ## One program to run as daemon. ## NOTE: process and each argument should each be their own string ## eg: command [/path/to/your_program, arg1, arg2] command [cat] ## Environment variables # environment [] ## Delay before the process is restarted after an unexpected termination # restart_delay 10s ## Serialization format for communicating with the executed program # data_format influxREADME 中还给出了一个完整的 Go 守护进程示例用influx.NewStreamParser(os.Stdin)逐条解析 stdin 上的指标读取count字段乘以 2 后再用serializers_influx.Serializer写回 stdout——这正是外部处理器插件的典型实现模式。配套测试用例位于 plugins/processors/execd/testcases其中dataformat-influx、dataformat-json、defaults等目录各含telegraf.conf与input.influx可作为端到端联调参考。outputs.execd把外部程序当作写出目标outputs.execd 将指标写入外部守护进程的 stdin命令只执行一次之后每次写入都以指定数据格式传入支持格式见 docs/DATA_FORMATS_OUTPUT.md。其配置见 sample.conf还包括两个输出侧特有选项# Run executable as long-running output plugin [[outputs.execd]] command [my-telegraf-output, --some-flag, value] # environment [] restart_delay 10s ## Flag to determine whether execd should throw error when part of metrics is unserializable # ignore_serialization_error false ## Use batch serialization instead of per metric. # use_batch_format false data_format influx该插件的错误处理模型需要特别注意其 README 有专门说明它采用fire-and-forget通信模型指标一旦写入外部进程的 stdin 管道即被视为写入成功而不是等到外部插件真正处理完毕。由于操作系统管道缓冲通常约 64KB写入 stdin 在缓冲区填满前都是非阻塞的外部插件出错时只会向 stderr 写错误信息Telegraf 负责记录不会触发 Telegraf 的重试机制也不阻止指标从缓冲区移除——因此指标可能丢失。若需要可靠投递应改用内置输出插件或在外部插件内部自行实现确认机制。仓库附带的 file.sh 与 redis_influx.rb 等示例可帮助你快速上手。Execd Go Shim把内置插件一键外部化对于 Go 插件仓库提供了 Execd Go Shim其目标是把 Telegraf 主仓库中的内部 input、processor、output 插件轻松抽取到独立仓库任何人都可以把它构建成独立应用再经由上述三类execd插件接入 Telegraf。shim 的核心实现shim 的核心类型在 goshim.go 中定义。Shim结构体同时持有三种插件接口type Shim struct { Input telegraf.Input Processor telegraf.StreamingProcessor Output telegraf.Output BatchSize int BatchTimeout time.Duration ... }它暴露的Run(pollInterval)方法会按输入 → 处理器 → 输出的优先级只运行一种插件goshim.go中Run的实现依次检查s.Input、s.Processor、s.Output都不为空才返回errors.New(nothing to run)这也解释了文档中每个仓库只放一个插件的建议——shim 并非为同时运行多个插件而设计。输入型插件采集到的指标经由writeProcessedMetrics用 influx 序列化器编码后写入 stdout这与inputs.execd的读取协议完全对应。配置加载逻辑见 config.goLoadConfig读取 TOML 配置后从plugins/inputs、plugins/processors、plugins/outputs各自的注册表中按名字查找插件构造器并解码配置当未指定配置文件时DefaultImportedPlugins会直接加载所有被 import 进来的插件并打印No config found. Loading default config for plugin ...日志。配置文件中的环境变量如$VAR或${VAR}会在读取时通过os.Expand展开便于按环境注入敏感配置。示例入口程序shim 自带的可直接复制的入口程序位于 plugins/common/shim/example/cmd/main.go其关键结构为package main import ( flag fmt os time // TODO: import your plugins _ github.com/influxdata/tail // Example external package for showing where you can import your plugins github.com/influxdata/telegraf/plugins/common/shim ) var pollInterval flag.Duration(poll_interval, 1*time.Second, how often to send metrics) var pollIntervalDisabled flag.Bool( poll_interval_disabled, false, set to true to disable polling. You want to use this when you are sending metrics on your own schedule, ) var configFile flag.String(config, , path to the config file for this plugin) func main() { flag.Parse() if *pollIntervalDisabled { *pollInterval shim.PollIntervalDisabled } shimLayer : shim.New() // If no config is specified, all imported plugins are loaded. if err shimLayer.LoadConfig(configFile); err ! nil { fmt.Fprintf(os.Stderr, Err loading input: %s\n, err) os.Exit(1) } if err shimLayer.Run(*pollInterval); err ! nil { fmt.Fprintf(os.Stderr, Err: %s\n, err) os.Exit(1) } }shim.PollIntervalDisabled值为time.Duration(0)用于显式禁用轮询适合按自身节奏推送指标的程序与内置常量定义一致见 goshim.go。对应的插件配置文件模板为 plugin.conf[[inputs.my_plugin_name]] value_name value分步指南将插件外部化并与 execd 对接官方文档 docs/EXTERNAL_PLUGINS.md 提供了完整的七步流程这也是把插件无论是新写的还是从内置迁移的接入execd的标准路线编写 Telegraf 插件。根据插件类型遵循 InfluxData 的最佳实践指南来创建插件本体输入插件docs/INPUTS.md处理器插件docs/PROCESSORS.md聚合器插件docs/AGGREGATORS.md输出插件docs/OUTPUTS.md将项目迁移到外部仓库。建议保留原有的路径结构并非强制。例如插件原在plugins/inputs/cpu则新仓库中也建议放在plugins/inputs/cpu下便于社区对照与维护。复制入口程序。把 plugins/common/shim/example/cmd/main.go 复制到项目cmd目录下作为独立运行时的入口点它会自动调用 shim 代码。再次强调一个仓库只放一个插件因为 shim 不支持同时运行多个插件。修改 main.go 导入你的插件。在 Telegraf 内部这一般由all.go完成但外部化时直接写在 main.go 顶部即可。跳过这一步插件将什么都不做形式如_ github.com/me/my-plugin-telegraf/plugins/inputs/cpu可选添加插件专属配置plugin.conf。注意该配置文件必须与 Telegraf 其余配置分离不能放在 Telegraf 加载所有配置的共享目录中——如果 Telegraf 读到了这个文件它不知道该文件对应哪个插件。Telegraf 是通过execd配置块来定位这个插件的。在仓库主页补充使用与开发说明内容应涵盖如何下载对应平台的发布包或如何 clone 外部插件的二进制构建二进制的命令需要编辑的telegraf.conf位置与 inputs.execd、processors.execd 或 outputs.execd 配合使用的完整配置。提交插件。通过 Pull Request 将外部插件加入 EXTERNAL_PLUGINS.md 清单需要包含插件名称、插件仓库链接、以及一段简短描述。构建与运行外部插件构建二进制对 Go 插件使用 shim构建非常简单go build -o rand cmd/main.go以rand示例项目为例即生成可独立运行的rand二进制。独立测试不依赖 Telegraf输入插件直接运行二进制即可测试。例如./rand -config plugin.conf。根据轮询设置以及你实现的是 service 插件还是 gather 型插件数据可能立即出现、也可能需要先按回车或等待一个轮询周期指标会写到 STDOUT用Ctrl-C结束测试。处理器 / 输出插件同样可以手动测试但需要在 STDIN 上喂入合法的指标以便验证插件行为是否符合预期。这是接入 Telegraf 之前非常有价值的调试手段。接入 Telegraf构建完成后在 Telegraf 配置中通过execd块调用新二进制。以输入插件为例详见 plugins/common/shim/README.md[[inputs.execd]] command [/path/to/rand, -config, /path/to/plugin.conf] signal none结合前文inputs.execd的完整配置项environment、restart_delay、buffer_size、stop_on_error、data_format等即可正式投产。已收录的外部插件生态一览仓库根目录 EXTERNAL_PLUGINS.md 维护着社区贡献的外部插件清单Pull Request 长期欢迎可作为参考实现与选型来源输入类Inputs如awsalarmsAWS 告警采集、octoprint3D 打印信息、opcdaOPC DA 工业自动化协议、plexPlex 媒体服务器 Webhook、rand随机数生成、systemd-timingssystemd 启动与单元时间戳指标、twitter/youtube账号信息、dnsmasq、x509_crlX509 CRL 文件、s7comm西门子 PLC、oracle/db2关系型数据库统计、aptDebian 包更新检查、knotKnot DNS 统计、linux-psi内核压力停滞信息、bacnetBACnet 设备、tado/homekit智能家居等输出类Outputs如kinesisAmazon Kinesis 聚合压缩、firehoseKinesis Data Firehose 批量发送、playfabAzure PlayFab处理器类Processors如geoip为 IP 附加 GeoIP 信息、metadata追加 OpenStack 元数据。这些插件全部通过execd三种插件之一接入 Telegraf可直接对照研究其仓库结构、main.go 与配置组织方式。总结外部插件机制是 Telegraf 插件体系的重要延伸一方面通过inputs.execd、processors.execd、outputs.execd三个宿主插件让任何语言的程序都能作为一等公民参与指标采集、处理与写出另一方面通过 Execd Go Shim让 Go 插件的内置 ↔ 外部转换成本降到最低——只需复制入口 main.go、import 插件、构建二进制并配置execd块。外部插件在带来语言自由、依赖自主和发布灵活的同时也要求作者承担完整的维护与文档职责尤其要理解outputs.execd的 fire-and-forget 语义可能带来的数据丢失风险。对于希望扩展 Telegraf 能力边界的开发者而言从 EXTERNAL_PLUGINS.md 中的成熟案例入手再依据 docs/EXTERNAL_PLUGINS.md 的七步流程发布自己的插件是最稳妥的路径。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考