5分钟用Telegraf拿到第一组CPU指标

5分钟用Telegraf拿到第一组CPU指标

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

先说一个具体场景：你手上有一台服务器或一个容器，需要把它的 CPU、内存、磁盘数据定时打进时序库或画到监控面板里，但又不想为此引入一整套监控栈。Telegraf 是一个专门干这件事的 agent——它按固定的采集间隔从输入插件（inputs）收集指标，经过处理器（processors）和聚合器（aggregators）加工后，再由输出插件（outputs）写出去。整个数据管道由一份 TOML 配置文件驱动，编译产物是单个静态二进制，没有外部依赖。

它是什么，适合谁

Telegraf 的定位就是"指标的采集、加工、聚合与写入"，官方维护了 300 多个插件，覆盖系统监控、云厂商 API、消息队列、网络设备等领域。它不解释"指标异常了怎么办"——告警和可视化交给下游去做。

所以判断标准很简单：如果你的需求是"从各种数据源稳定地采数并送出去"，它很合适；如果你的需求是完整的告警引擎或可视化大盘，它不是那个答案，它负责的是管道，不是终点。

根据你的环境选一条路

本地快速试用：官方 Docker 镜像最快，拉下来挂一个配置文件就能跑：

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

生产长期运行：用包管理器或静态二进制，进程常驻且便于 systemd 管理。Debian/Ubuntu 加 InfluxData 官方源后apt-get install telegraf即可；也支持 Homebrew。要编译的话，克隆仓库后执行make build：

git clone https://gitcode.com/GitHub_Trending/te/telegraf cd telegraf && make build

💡 提示：配置文件里至少要有一个 input 和一个 output，否则 Telegraf 启动后没有任何数据流动。最小可用的插件组合是两行：一个[[inputs.*]]，一个[[outputs.*]]。

各平台的完整安装方式、GPG 校验、Helm chart 等，见 docs/INSTALL_GUIDE.md——当你需要离线安装或在非主流平台部署时翻它。

从零到第一行输出

第一步，用官方子命令只生成 CPU 输入和文件输出两段的配置：

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

telegraf config会打印全部插件的默认配置（默认全被注释），--input-filter和--output-filter只保留你要的部分。

打开minimal.conf，把它改成下面这样——一行输入、一行输出：

[[inputs.cpu]] percpu = true # 按每个 CPU 核分别上报 totalcpu = true # 额外上报一台机器的汇总 [[outputs.file]] files = ["stdout"] # 写到标准输出，方便直接观察

保存文件，然后启动：

telegraf --config minimal.conf

终端里会先滚动一段启动日志：加载了哪个配置文件、运行版本、加载了哪些插件。十几秒后开始出指标行，形如：

# 标签: 主机名; 字段: 整型计数器(i后缀) + 百分比; 末尾: 纳秒时间戳 mem,host=my-server free=1877688320i,available=16818249728i,used=3335778304i,used_percent=15.95 1574712869000000000 cpu,host=my-server,cpu=cpu-total usage_user=11.39,usage_system=4.14,usage_idle=82.38 1568760922000000000

上面两行取自两个输入插件 README 里的真实样例。第一行说明内存指标按主机标签 + 字段 + 时间戳的 line 格式输出；第二行里cpu=cpu-total是totalcpu = true产生的汇总标签。注意usage_*是占比字段：第一次采样时 CPU 插件输出的是原始计时，从第二次采样开始才会出现 usage 百分比，因为它拿两次采样的差值计算。

配置文件的三层结构

Telegraf 的配置就三层，顺序从上到下：

telegraf.conf ├── [global_tags] # 附加到所有指标上的标签 ├── [agent] # 采集间隔、批量、日志等代理设置 └── 插件区 ├── [[inputs.*]] # 采 ├── [[processors.*]] # 加工 ├── [[aggregators.*]] # 聚合 └── [[outputs.*]] # 写

最常改的几个参数：

完整参数列表和插件区的全局过滤、排序规则，见 docs/CONFIGURATION.md。

用环境变量替换敏感值

配置里任意位置都可以写${VAR}，字符串要带引号、数字布尔不带引号；还支持${VAR:-默认值}、${VAR:?未设置时报错退出}这类 shell 风格写法。用 deb/rpm 包装的 Telegraf 可以直接把变量写进/etc/default/telegraf。原则只有一条：token、密码永远不要明文写进配置文件。

[[outputs.influxdb_v2]] urls = ["${INFLUX_HOST}"] # 来自环境变量 token = "${INFLUX_TOKEN:?缺少 token}" # 未设置则启动报错 organization = "${INFLUX_ORG:-default}" # 未设置时用 default bucket = "${INFLUX_BUCKET}"

按你的目标选插件，别背插件表

最小加工示例，给 CPU 指标统一加个字段名映射：

[[processors.rename]] namepass = ["cpu"] # 只处理 cpu 测量 [[processors.rename.replace]] field = "usage_idle" # usage_idle 重命名为 idle dest = "idle"

执行顺序是：processors 先跑，然后 aggregators，processors 再跑一遍——所以如果你又加缩放类处理器，留意它可能被执行两次。聚合器可以用drop_original = true只保留聚合结果、丢弃原始指标，细节见 docs/AGGREGATORS_AND_PROCESSORS.md。完整插件目录在 plugins/ 下，每个插件都有自己的 README 和样例配置。

部署前过一遍这几条

• 先跑telegraf --test --config minimal.conf：只执行一轮输入并把结果打到 stdout 后退出，确认配置合法、指标能采到
• 排障时加--debug启动，看每个插件的加载与数据流向，确认后再关掉
• 观察 Telegraf 进程本身的 CPU/内存占用，确认它没有反客为主
• 所有 token、密码走${}环境变量或 secret store 注入，配置里不留明文
• 生产环境用 docs/SECRETSTORES.md 里的 secret store 插件托管凭据，而不是散落在环境里
• 验证输出目标连通性：正式切换前先写outputs.file到 stdout 看一眼实际格式
• 固定镜像或二进制版本，升级走灰度，不直接拉 latest

接下来往哪走

• docs/QUICK_START.md：一个基于 Docker 的最小完整示例，适合照着复现一遍
• docs/CONFIGURATION.md：全部配置参数、环境变量语法、插件过滤与排序规则
• docs/AGGREGATORS_AND_PROCESSORS.md：processors 与 aggregators 的执行顺序和drop_original行为
• docs/DATA_FORMATS_OUTPUT.md：输出支持哪些 data_format，换 JSON、Kafka 等格式时先查这里
• docs/FAQ.md：踩到具体怪问题时，先来这里搜

到这里，你已经能在自己的环境里跑通第一条指标了；剩下的事情，就是按监控目标往配置文件里加插件。下一篇会讲处理器与聚合器的执行顺序细节，以及如何避免数据被重复加工。

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