Telegraf 指标采集快速上手：5 分钟跑通第一条监控数据流

Telegraf 指标采集快速上手：5 分钟跑通第一条监控数据流

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

凌晨值班，你刚接手一台新服务器，想立刻知道它的 CPU、内存和磁盘在干什么。装一整套监控栈显然太重了，而 Telegraf 恰恰是为这种场景设计的：它是一个插件驱动的监控代理（metric collection agent），采集、处理并写出指标、日志等任意数据，单文件、无依赖，启动几秒后就能看到数据在往外流。本文带你从安装到看到第一条指标，全程只走最短路径。

项目速览：一张信息卡认识 Telegraf

先看定位，再决定要不要深入。

插件数量不是吹出来的：直接ls一下 plugins/inputs/ 和 plugins/outputs/ 就能数出来，目录即清单。

准备工作：装之前先确认三件事

这一步能帮你避开 90% 的"装不上"问题。

1. 选版本：生产环境用稳定版，不要追 nightly。各版本的变更细节都在 CHANGELOG.md 里，升级前扫一眼对应条目即可。
2. 选安装方式：开发测试用 Docker 最快；长期部署用包管理器（有 DEB/RPM 仓库）或二进制包；macOS 用户可以直接brew install telegraf。完整方式见 docs/INSTALL_GUIDE.md。
3. 确认环境干净：Telegraf 是静态二进制，不需要 Go、不需要数据库客户端库。唯一要确认的是目标端口没被占（比如你打算输出到 InfluxDB 时，8086 是否可达）。

装完用一行命令验证：

telegraf --version

能打印出版本号，准备阶段就结束。

跑通第一条数据流：装、配、启动一气呵成

目标是 5 分钟内让指标打印到控制台。按下面四步走，做完你就有了产出。

第 1 步：拿一个最小配置。与其手敲，不如让 Telegraf 自己生成全量默认配置，再抄你需要的几行：

telegraf config > telegraf.conf

从生成结果里只保留三个插件段落，存成minimal.conf：

[[inputs.cpu]] [[inputs.mem]] [[outputs.file]] files = ["stdout"]

第 2 步：启动。

telegraf --config minimal.conf

第 3 步：看结果。几秒后标准输出开始出现类似这样的行：

cpu,cpu=cpu0,host=your-server,cpu=total usage_idle=95.4,usage_user=3.4 1654321098765 mem,host=your-server used_percent=54.4,available=3423456768i 1654321098765

第 4 步（Docker 用户）：把配置文件挂进容器即可，配置内容不变：

docker pull telegraf docker run --rm --volume $PWD/minimal.conf:/etc/telegraf/telegraf.conf telegraf

到此为止，你已经完成了"采集 → 写出"的最小闭环。后面的章节只是在解释你刚才跑的东西，以及如何扩展它。

配置逐段解读：字段—作用—取值建议

Telegraf 配置是 TOML，读配置时抓住[agent]和[[inputs.xxx]]/[[outputs.xxx]]两类结构就够了。单表（[agent]）是全局设置，数组表（[[...]]）每写一次就启用一个插件实例——这也是为什么同一个插件可以配置多份（比如连两个不同的 InfluxDB）。

[agent]里值得调的字段：

[global_tags]给所有指标追加统一标签，比如env = "prod"，做多环境查询时能省掉大量 where 条件。

敏感信息别写死在文件里，用环境变量占位：

[[outputs.influxdb_v2]] urls = ["${INFLUX_HOST}"] token = "${INFLUX_TOKEN}"

规则与陷阱（例如注释内的变量不会被替换）写在 docs/CONFIGURATION.md，格式细节在 docs/TOML.md。

能力地图：采集、处理、输出三类场景

刚才的最小配置只用了"输入 + 输出"两端。Telegraf 的完整链路是输入插件 →（可选）解析器 → 处理器 → 聚合器 → 输出插件，按三类场景各挑一个代表，知道去哪找其余的就够了。

采集端（[[inputs.*]]，246 个）

[[inputs.diskio]] # 指定设备，只看 sda devices = ["sda"] [[inputs.mysql]] # 多实例：servers 写多行即可 servers = ["user:pass@tcp(127.0.0.1:3306)/"]

覆盖主机硬件（cpu/mem/diskio/net）、中间件（redis/mysql/mongodb/kafka_consumer）、云平台与云监控（cloudwatch/azure_monitor）、网络设备（snmp/netflow）。完整清单用telegraf plugins inputs直接打印。

处理端（[[processors.*]]，36 个）

[[processors.rename]] # 重命名字段，让历史数据字段名统一 [[processors.rename.replace]] field = "usage_idle" dest = "idle" [[processors.calculator]] # 派生字段：用现有字段算新字段 namepass = ["cpu"] [[processors.calculator.fields]] dest = "usage_busy" expr = "100.0 - usage_idle"

输出端（[[outputs.*]]，69 个）

[[outputs.kafka]] brokers = ["kafka:9092"] topic = "metrics" data_format = "influx"

除时序库外还有 Kafka、HTTP、文件、MQTT 等。输入输出两侧还支持data_format声明任意解析/序列化格式（22 个解析器 + 15 个序列化器），比如把 JSON、Prometheus 文本、Avro 等外部格式直接喂进来，参考 docs/DATA_FORMATS_INPUT.md。

进阶玩法：为什么要在管道里做处理和聚合

跑通之后很快会遇到两个真实问题：指标太多，字段名不统一。

第一个问题靠聚合器解决。原始指标每秒几十条，直接写入存储成本高、查询也吵。[[aggregators.*]]会按周期把原始数据压成统计值：

[[aggregators.basicstats]] period = "5m" delay = "0s" drop_original = false [[aggregators.basicstats.metrics]] namepass = ["cpu"] fields = ["usage_user"]

period决定统计窗口，drop_original决定要不要丢弃原始数据——保留原值适合调试，生产环境建议丢弃以省存储。官方 10 个聚合器（minmax/derivative/quantile 等）的行为差异讲得很透，读 docs/AGGREGATORS_AND_PROCESSORS.md 一次即可。

第二个问题靠处理器顺序控制解决。多个处理器和聚合器可以叠加，执行顺序由配置决定，也支持按namepass只作用于特定指标。顺序行为（含 processor 与 aggregator 的先后关系）有完整的测试用例可以对照，见 agent/testcases/，这是理解管道语义最快的材料。

故障速查表：现象—原因—解法

命令细节（--test、--version、config子命令等）汇总在 docs/COMMANDS_AND_FLAGS.md。

延伸学习：按问题找文档

下一步：把这条数据流接到你的真实环境

你现在手里有一个能跑的 Telegraf，最短的三件事：

1. 把outputs.file换成你的存储（outputs.influxdb_v2最常见），凭据走环境变量；
2. 从 246 个输入里挑出业务真正要的那 3~5 个，其余保持注释；
3. 加一个[[aggregators.basicstats]]，观察存储量下降多少。

Telegraf 的价值在于把"采集什么、怎么变、写到哪"拆成了三段可独立替换的插件管道——今天打印到控制台，明天接 Kafka，后天加聚合，配置结构完全不用推倒重来。下一步就从换输出开始，五分钟之内你就能在时序库里查到第一张真实监控曲线。

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