Telegraf 监控代理实战：5 分钟跑通采集闭环，一路做到生产部署

Telegraf 监控代理实战：5 分钟跑通采集闭环，一路做到生产部署

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

Telegraf 是一个插件驱动的监控代理，负责从各种来源采集指标、做处理与聚合、再写入你指定的存储。本文用一条 10 秒采集间隔的配置带你走完整条链路：安装、生成首份配置、test 模式验证，最后给出一份生产部署检查清单。

从「用户先报障」到「你先知道」：Telegraf 解决什么问题

没有采集代理时，你只能在用户报障后翻日志猜原因：CPU 何时飙的、哪个容器先 OOM，答案永远缺失。Telegraf 补上这一环：它按固定间隔（默认 10 秒）采集指标，内置 240+ 输入插件与 100+ 输出目标，把数据可靠地搬进你选定的存储。

30 秒看懂数据流：采集、缓冲、刷出三步

Telegraf 的工作模型只有三步：定时采集 → 内存缓冲 → 定时刷出，中间的处理和聚合是可插拔的。

理解这一点后，后面所有配置都能对号入座：改输入是改"采什么"，改处理是改"中间怎么变"，改输出是改"写到哪"。

⚡ 5 分钟跑通最小闭环：装好、生成配置、test 模式看数据

不用先搭数据库——Telegraf 的--test模式只跑输入插件，把指标直接打到标准输出后退出，这是验证采集最快的路径。

第一步，拿到二进制：

git clone https://gitcode.com/GitHub_Trending/te/telegraf cd telegraf && make build # 产物为当前目录下的 ./telegraf

第二步，只生成你要的插件配置，避开几百行注释模板：

./telegraf config --input-filter cpu --output-filter file > telegraf.conf

第三步，跑一次 test 模式：

./telegraf --config telegraf.conf --test

标准输出会打印行协议格式的 cpu 指标（usage_user、usage_system 等字段），打印完进程立即退出。到这里你已经在本地看到采集到的真实数据了，全程没碰任何存储。

配置的三种写法：输入、处理、输出各留一个关键示例

配置就是一条流水线：输入决定采什么，处理决定怎么变，输出决定写到哪；每段记住一个关键写法即可。

输入侧：[[inputs.xxx]]表格数组即一个插件实例，标签统一写在 tags 里：

[[inputs.cpu]] percpu = false # 只看整体，数据量减半 totalcpu = true [inputs.cpu.tags] # 标签跟随每条指标，查询时可按环境过滤 environment = "prod"

处理侧：processors 挂在输入与输出之间，最常用的是 override（改名、加标签、过滤）：

[[processors.override]] namepass = ["cpu"] # 只放行 cpu 指标 nameprefix = "app_" # 统一加前缀，区分不同应用

其余处理器：rename 改字段/标签名、converter 做类型转换、starlark 直接写脚本做任意变换，细节见 docs/PROCESSORS.md；聚合侧对应 quantile、derivative 等 aggregator，适合"每 30 秒出一个分位数"这类降采样。

输出侧：写 InfluxDB v2 只需四个必填项：

[[outputs.influxdb_v2]] urls = ["http://influxdb.example.com:8086"] token = "$INFLUXDB_TOKEN" # 环境变量展开，别写真值 organization = "my-org" bucket = "telegraf" content_encoding = "gzip" # 高吞吐时开压缩

调试期先用[[outputs.file]]（files = ["stdout"]）落盘观察格式，稳定后再切正式输出。

🧾 生产部署检查清单：上线前逐项打勾

上生产前把下面几项过一遍，能避开绝大多数线上事故。

• 配置拆分：主配置只留[agent]，每个插件独立成文件放进--config-directory指向的目录，改一个插件只动一个文件
• 抖动参数：collection_jitter、flush_jitter设为 0~5s，50 台机器同时采集时削掉整点流量尖峰
• 缓冲兜底：把buffer_strategy设为disk并指定buffer_directory，存储抖动期间数据先落盘、重启不丢
• 秘密管理：token、密码一律走环境变量或 secretstore 展开，配置进 Git 前全局搜一遍明文凭据
• 容器环境：K8s 用 DaemonSet 部署；采容器指标用 inputs.docker 并挂/var/lib/docker/containers，或直接用 inputs.kubernetes 走 API
• 热更新：加--watch-config notify，改配置不用重启进程
• 自监控：启用[[inputs.internal]]，再加[[inputs.procstat]]且pattern = "telegraf"，agent 自己先被监控起来

清单打完，这份配置就具备进生产评审的资格了。

🧯 踩坑与自检：六个高概率翻车点，各配一条验证命令

这些问题在生产上都会遇到，按顺序跑验证命令即可定位。

1. 配置语法错误或未知选项：进程启动即报错退出，信息带文件名和行号。验证：./telegraf --once --config telegraf.conf，配置不过它会直接报出来
2. 插件参数写错：对照官方用法最快。验证：./telegraf --usage cpu打印该插件全部参数及默认值
3. service 类输入采不到数据：tail、snmp_trap 这类插件是"等数据来"，test 模式默认不等待。验证：./telegraf --config telegraf.conf --test --test-wait 30
4. 指标采到了但没写出去：写失败会体现在自身指标里。验证：开[[inputs.internal]]，观察telegraf_output_write_errors是否持续增长
5. 数据量超预期打爆存储：先看每轮实际产出。验证：./telegraf --config telegraf.conf --debug，日志会给出每个插件每轮 gather 的条数
6. 升级后行为变了：老参数可能已废弃。验证：./telegraf --deprecation-list列出当前版本全部弃项，逐条对照配置

下一步：五条进阶路线，各附一句理由

• 写 Starlark 处理器：复杂变换不用加插件、不用重启，配置里直接写脚本，适合字段按业务规则重命名
• 上 aggregator 降采样：derivative、quantile 把秒级数据压成 30 秒粒度，存储成本降一个量级
• 用 custom builder 瘦身：tools/custom_builder/ 只编译你用到的插件，镜像从几百 MB 缩到几十 MB
• 翻插件目录找现成方案：plugins/inputs/ 下每个插件自带 README 与 sample.conf，先找再造轮子
• 接入状态持久化：部分 input 支持把采集状态落盘，重启后按增量续采、不重复拉历史数据

下一台机器、下一个插件，照着本文的闭环复制一遍就能上手。

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