Telegraf custom_builder 定制编译工具按配置裁剪插件、构建最小化 Agent 二进制【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读Telegraf 默认发行版会编译全部数百个输入、输出、处理器等插件导致二进制体积较大、运行时占用更多内存。custom_builder是 Telegraf 仓库内置的定制化构建工具它读取你的 Telegraf 配置文件本地文件、配置目录或远程 URL自动分析其中实际用到的插件并借助 Go 的 build tags 只把这些插件编译进二进制。读完本文你将掌握从源码构建该工具、用--config/--config-dir生成专属 Agent、理解其自动推导 parser/serializer 依赖的原理以及用--dry-run、--tags等参数进行调试的完整方法。工具背景与适用场景Telegraf 是一个用于采集、处理、聚合并输出指标、日志及其他任意数据的代理程序项目描述与 README.md 一致。默认构建会包含仓库中所有插件而实际生产环境往往只用到其中一小部分。custom_builder的出现正是为了解决这一问题更小的磁盘占用只包含所选插件二进制显著瘦身更低的内存开销未编译的插件不会注册、不会加载减少运行时内存更快的启动与更小的攻击面无关功能不进入二进制。其官方定位见 tools/custom_builder/README.md是“a tool to select the plugins compiled into the Telegraf binary. By doing so, Telegraf can become smaller, saving both disk space and memory if only a sub-set of plugins is selected.”该工具属于仓库的tools工具链与 tools/readme_linter、tools/config_includer 等同属开发者/运维工具但它直接服务于最终用户的部署定制需求。环境要求与源码获取必备工具链编译定制化二进制需要GoGolang语言工具链具体最低版本要求请查阅当前 Telegraf 版本 README.md 中Build From Source一节make 构建系统custom_builder自身和定制后的 Telegraf 都通过 Makefile 驱动构建。go与make两个命令都必须位于你的PATH中。下载 Telegraf 源码第一步是获取你计划定制的 Telegraf 版本源码。以下示例使用v1.29.5标签你也可以换成其他版本或直接使用master# git clone --branch v1.29.5 --single-branch https://github.com/influxdata/telegraf.git ... # cd telegraf作为替代方案你也可以直接下载某个 Telegraf release 的源码 tarball 或 zip 压缩包解压后进入仓库根目录即可。构建 custom_builder 工具本身custom_builder是一个独立的 Go 可执行程序位于tools/custom_builder目录源码入口见 main.go。通过仓库根目录的 Makefile 目标build_tools构建见 Makefile# make build_tools对应的构建命令为go build -o ./tools/custom_builder/custom_builder ./tools/custom_builder。构建成功后产物位于tools/custom_builder/目录下文件名为custom_builderWindows 下为custom_builder.exe。提示build_tools目标也是make docs等任务的前置依赖见 Makefile说明该工具同样被用于文档等辅助任务的构建链中。使用方式从配置文件生成定制 Telegraf基础用法单个配置文件最简单的方式是直接传入你的 Telegraf 配置文件。假设配置位于/etc/telegraf/telegraf.conf# ./tools/custom_builder/custom_builder --config /etc/telegraf/telegraf.confcustom_builder会解析该配置文件提取其中出现过的插件生成对应的 build tags然后调用make build在仓库根目录产出定制后的 Telegraf 二进制构建目标的定义见 Makefilebuild: CGO_ENABLED0 go build -tags $(BUILDTAGS) -ldflags $(LDFLAGS) ./cmd/telegraf可以看到定制编译正是通过向go build传入-tags $(BUILDTAGS)实现的其中BUILDTAGS环境变量由custom_builder在运行时注入见 main.go。同时使用配置目录与 Telegraf 本身一致custom_builder支持--config-dir指定配置目录。若要一并使用/etc/telegraf/telegraf.d下的配置# ./tools/custom_builder/custom_builder \ --config /etc/telegraf/telegraf.conf \ --config-dir /etc/telegraf/telegraf.d需要说明的是源码中对配置目录的处理是遍历目录下所有以.conf结尾的文件并全部纳入见 config.go因此目录中建议只放置需要启用的插件配置片段。远程配置文件配置也可以来自远程位置与 Telegraf 加载远程配置的方式相同# ./tools/custom_builder/custom_builder --config http://myserver/telegraf.conf该命令会从myserver下载配置并据此完成插件选择。多配置叠加超集合并--config与--config-dir都可以多次指定。当需要把 Telegraf 部署到多台配置各不相同的机器上时只需一次性传入所有配置的超集custom_builder会自动合并去重得出覆盖全部场景的插件清单# ./tools/custom_builder/custom_builder \ --config system1/telegraf.conf \ --config system2/telegraf.conf \ --config ... \ --config systemN/telegraf.conf \ --config-dir system1/telegraf.d \ --config-dir system2/telegraf.d \ --config-dir ... \ --config-dir systemN/telegraf.d查看帮助更多参数说明可通过--help获取# ./tools/custom_builder/custom_builder --help--help会输出工具简介、用法、全部 flags 以及内置示例相关实现见 main.go。命令行参数速查结合源码 main.go 中的 flag 定义custom_builder支持的全部参数如下参数类型默认值说明--config file可重复无从配置文件导入插件可用多次--config-dir dir可重复无从指定目录中的.conf文件导入插件可用多次--dry-run布尔false跳过实际构建步骤仅计算并输出结果--quiet布尔false减少日志输出--migrations布尔false在 build tags 中额外加入migrations包含配置迁移逻辑--tags布尔false显示最终使用的 build tags其中--dry-run与--tags组合非常适合在正式构建前确认插件选择结果。当未指定任何--config与--config-dir时程序会报错退出no configuration specified见 main.go。工作原理从配置到 build tagscustom_builder的核心处理链路在process()函数中main.go共分四步收集全部可用插件packageCollection.CollectAvailable()遍历plugins/下七大类目录——aggregators、inputs、outputs、parsers、processors、secretstores、serializers类别定义见 main.go并通过 Go AST 静态解析每个包的init()函数中的registry.Add(...)/AddStreaming(...)调用提取插件注册名见 packages.go。inputs/example、*_test等包会被过滤排除见 packages.go。导入配置文件ImportConfigurations()读取全部配置文件 目录用 TOML 解析出各插件类别下的实例同时提取每个实例的data_format字段见 config.go 与 config.go。过滤匹配selection.Filter()将配置中出现的插件与收集到的包逐一比对生成“启用插件”集合配置中出现但仓库中不存在的插件会报错configured but unknown packages见 config.go。生成 tags 并构建ExtractTags()将启用的包映射为category.plugin形式的 tag 并排序见 packages.go最终拼成以custom,开头的完整 tags 串注入BUILDTAGS环境变量后调用make buildmain.go。构建完成后程序会打印分门别类的Enabled plugins清单格式见 packages.go便于人工核对。自动推导数据格式依赖parser / serializer这是custom_builder最实用的能力之一。仅仅因为某个 input 插件配置了data_format json就需要把对应 parser 一并编译进去否则运行时会找不到解析器。源码对此做了两类自动推导见 config.go显式data_format配置中若写了data_format则按插件类别自动补入依赖——inputs与processors中的该字段对应parsers.data_formatoutputs中的该字段对应serializers.data_format特别地execd处理器同时需要 parser 与 serializer见 config.go。默认data_format若插件实例未配置该字段则读取插件自带.conf样例中的默认data_format值packages.go同样补入对应 parser/serializer其中exec输入插件被特例处理为默认使用json。仓库中的测试用例直接验证了这一行为testcases/issue_15627的配置文件同时使用了data_format json_v2与data_format value的mqtt_consumer输入其expected.tags结果中除了inputs.mqtt_consumer和outputs.influxdb_v2还自动包含了parsers.json_v2与parsers.value见 testcases/issue_15627/telegraf.conf 与 testcases/issue_15627/expected.tags。另一个用例issue_13592验证了多输入单输出场景下仅输出确切需要的四个 input 插件和一个 output 插件见 testcases/issue_13592/telegraf.conf 与 testcases/issue_13592/expected.tags。这些用例由 main_test.go 以--dry-run模式驱动process()自动执行将实际生成的 tags 与expected.tags逐条比对是验证插件选择逻辑的回归测试入口。注意事项务必检查启用清单请确保配置中所用到的全部parsers与serializers都被包含并仔细核对程序输出的 enabled-plugins 列表。由于依赖自动推导的存在部分插件可能因为其他插件的依赖关系被自动启用却并未出现在你的配置中也不会显式显示为“被配置”因此人工核对最终列表仍然必要相关说明见 tools/custom_builder/README.md 的 Notes 一节。运行环境一致定制后的 Telegraf 二进制只能运行编译进去的插件。若后续要往配置中增加新插件需要重新运行custom_builder。多系统部署当不同主机配置不同时应传入所有配置的超集一次构建出通用二进制避免为每台机器分别编译。dry-run 先行正式构建前建议先用--dry-run --tags查看将要使用的 tags 与插件清单确认无误后再执行完整构建。延伸阅读工具完整文档tools/custom_builder/README.md工具入口与参数解析tools/custom_builder/main.go配置解析与依赖推导tools/custom_builder/config.go插件收集与 tags 生成tools/custom_builder/packages.go回归测试与示例配置tools/custom_builder/main_test.go、tools/custom_builder/testcases构建目标定义MakefileTelegraf 构建指引README.md【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考