Telegraf 1.40 插件配置详解

‍‍​​‌​> 目标：以 Telegraf 1.40.2 为基准，逐插件讲透 inputs / processors / aggregators / outputs 四类插件的配置方法与验证手段，每个插件均按「改配置 → 运行 → 验证指标真实产出」闭环实测并照录回显；同时实测 [agent] 全局段关键参数与环境变量替换行为，最后沉淀 --test / --once / --input-filter 调试方法与 1.40 版本的兼容性变化。安装与 systemd 托管见《Telegraf 安装部署指南》，输出端到 InfluxDB 的全链路见《Telegraf 集成实战》。

一、环境信息

• 实测环境：Ubuntu 22.04 LTS（x86_64）实验节点 cfg-ubuntu-2204，Telegraf 1.40.2（telegraf --version 实测回显 Telegraf 1.40.2 (git: HEAD@2e0a2ed1)，2026-10-18）；
• 配置驱动形态：本文所有实验均为「命令行指定配置文件」方式运行（telegraf --config <文件>），不依赖 systemd；systemd 托管方式的配置加载入口相同（/etc/telegraf/telegraf.conf + /etc/telegraf/telegraf.d/），见《Telegraf 安装部署指南》；
• 插件编译规模（服务启动日志照录）：

2026-10-18T03:11:14Z I! Starting Telegraf 1.40.2 brought to you by InfluxData the makers of InfluxDB
2026-10-18T03:11:14Z I! Available plugins: 244 inputs, 9 aggregators, 35 processors, 26 parsers, 68 outputs, 8 secret stores

二、配置体系总览

Telegraf 配置为单一 TOML 文件，核心结构分两块：

[agent]                 # 全局调度参数（一个）
[[inputs.cpu]]          # 输入插件（双中括号数组表，可重复定义）
  percpu = true

[[processors.override]] # 处理器（按声明顺序串联）
  [processors.override.tags]
    team = "sre"

[[aggregators.basicstats]] # 聚合器（窗口聚合）
  period = "5s"

[[outputs.file]]        # 输出插件（可多个）
  files = ["stdout"]

加载顺序与合并规则（实测结论）：

1. --config 指定的文件先加载，--config-directory 目录内 .conf 按文件名排序并入（systemd 单元默认同时加载两者）；
2. 双中括号 [[...]] 是数组表，同一插件可写多段（如两个不同端口的 [[inputs.socket_listener]]），这是 Telegraf 区别于单例配置的关键设计；
3. 未写 [agent] 段时全部走默认值（interval=10s、flush_interval=10s 等，见第三章）；
4. 配置内 ${VAR} 引用环境变量——1.38 起默认严格模式（实测见 3.4）。

三、[agent] 全局段参数实测

以下默认值照录自 v1.40.2 官方样例配置（实测环境 /etc/telegraf/telegraf.conf，605229 字节）：

3.1 hostname 与 global_tags

配置：

[agent]
  interval = "1s"
  hostname = "cfg-ubuntu-2204"

[[inputs.mem]]

[[outputs.file]]
  files = ["/opt/data/telegraf/c1-omit0.out"]

实测输出（--once 后文件照录，行已截断）：

mem,host=cfg-ubuntu-2204 low_total=0i,swap_free=405504i,swap_total=2147479552i,buffered=248381440i,cached=9678077952i,inactive=14323974144i,...

host tag 默认取机器主机名（可被 hostname 覆盖）。全局维度用 [global_tags] 注入，配合环境变量：

[global_tags]
  dc = "${MY_DC}"

export MY_DC=sh1

实测输出（照录，行已截断）：

mem,dc=sh1,host=cfg-ubuntu-2204 huge_pages_to...

global_tags 注入所有 metric，是多机房批量部署时打机房/环境标的最省力手段（对打点网关场景同样生效，实测见 4.5 的 app_request,dc=sh1,... 行）。

3.2 omit_hostname 实测

把 hostname = "cfg-ubuntu-2204" 换成 omit_hostname = true 后重跑，输出变为（实测照录，行已截断）：

mem dirty=84905984i,huge_page_size=2097152i,huge_pages_total=0i,swap_total=2147479552i,...

host tag 彻底消失。适用于「指标已由上层系统注入主机维度」的场景。

3.3 interval 与 flush 的关系实测

[agent] interval = "1s" + outputs.file（默认 flush_interval=10s）时，文件约每 10 秒收到一批 10 行；将 flush_interval = "1s" 后落盘节奏同步为 1 秒。采集与写出是两个独立时钟，调试时如果「文件迟迟没数据」，先查 flush_interval。

3.4 环境变量替换（严格模式双向实测）

配置内 ${VAR} 引用环境变量是部署时注入密钥/机房号的标准做法。1.40 严格模式下双向实测：

• 变量已定义（export MY_DC=sh1）：tag 正常注入（3.1 实测行 mem,dc=sh1,...）；
• 变量未定义（不导出直接跑）：无任何报错、进程正常退出，但该 tag 被静默省略——输出直接是 mem,host=cfg-ubuntu-2204 total=...，dc tag 不存在，回显里也没有 E! 错误行（实测 grep -c "^E!" 结果为 0）。

运维含义：上线前先 --once 抽查首行 tag 集是否齐全——看到「该有的 tag 不见了」大概率是环境变量没注入，而不是配置写错。

四、常用 inputs 实测

4.1 cpu

[[inputs.cpu]]
  percpu = false      # 不按核心拆分
  totalcpu = true     # 输出 cpu-total 汇总
  fieldpass = ["usage_user", "usage_idle"]  # 只要两个字段

--test 实测输出（照录）：

> cpu,cpu=cpu-total,host=cfg-ubuntu-2204 usage_idle=81.80300501009931,usage_user=9.015025041993765 1792295093000000000

要点：fieldpass 在采集端过滤字段（1.35+ 官方推荐写法，旧写法 field_include 已弃用），输出只剩指定字段，降低序列化与网络开销。

4.2 mem / disk / net / system

四件套零配置可用（[[inputs.mem]] 即可）。--test 实测输出（节选照录，行已截断）：

> mem,host=cfg-ubuntu-2204 active=15050240000u,available=9618329600u,available_percent=28.619756782189786,buffered=252821504u,cached=9554083840u,...
> disk,device=overlay,fstype=overlay,host=cfg-ubuntu-2204,mode=rw,path=/ free=576622669824u,inodes_free=48923720u,inodes_total=52396032u,inodes_used=3472312u,...
> disk,device=tmpfs,fstype=tmpfs,host=cfg-ubuntu-2204,mode=rw,path=/dev free=67108864u,...

inputs.disk 按挂载点逐条输出（overlay/tmpfs/ext4 各一行），指标量大时用 mount_points = ["/"] 收敛。

排障实录（inputs.diskio，journal 实测照录）：在无 udev 数据库的精简系统上刷警告——

2026-10-17T19:44:50Z W! [inputs.diskio] Unable to gather disk name for "loop6": error reading /dev/.udev/db/block:loop6: stat /dev/.udev/db/block:loop6: no such file or directory

块设备名映射失败（W! 级告警），指标照常产出；介意可用 name_exclude = "loop*" 排除回环设备。

4.3 docker（Docker 指标采集）

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"

部署方式与挂载方法见《Telegraf 安装部署指南》方案 D（官方镜像 + docker.sock 挂载）。--test 实测输出（节选照录，2026-10-18）：

> docker,engine_host=ops,host=docker-host-2204,server_version=29.8.1 n_cpus=12i,n_containers=61i,n_containers_running=60i,n_images=314i 1792293950000000000
> docker_container_mem,container_image=clickhouse/clickhouse-server,container_name=plausible-v3.2.1-clickhouse,container_status=running,... usage_percent=37.8997802734375,limit=536870912u,usage=203472896u 1792294845000000000
> docker_container_cpu,...,cpu=cpu-total,... usage_percent=3.0988021228203184,usage_total=339459447000u 1792294845000000000
> docker_container_net,...,network=total,... rx_bytes=96901648u,tx_bytes=124658080u 1792294845000000000

产出两类 measurement：docker（引擎总览：实例数/镜像数/CPU 数）与 docker_container_status/mem/cpu/net/blkio（逐实例，docker compose 的 label 自动成为 tag）。采集逐实例数据时指标量与实例数成正比，量大时用 container_name_exclude/perdevice = false 收敛。

4.4 tail + grok（日志转指标，logparser 的继任者）

⚠️ 版本变化（实测踩坑）：加载含 [[inputs.logparser]] 的配置实测报错（照录）：

E! DeprecationError: Plugin "inputs.logparser" deprecated since version 1.15.0 and removed: use 'inputs.tail' with 'grok' data format instead

官方替代方案是 inputs.tail + data_format = "grok"。且 1.40 的 tail 不再支持 from_beginning（严格校验报 update input inputs.tail: from_beginning is not a valid option），改用 initial_read_offset。

[[inputs.tail]]
  files = ["/opt/data/telegraf/access.log"]
  initial_read_offset = "beginning"   # 从头读；默认 saved-or-end（续读）
  data_format = "grok"
  grok_patterns = ["%{COMBINED_LOG_FORMAT}"]

[[outputs.file]]
  files = ["stdout"]

对样例 access log（COMBINED 格式）实测解析输出（照录，2026-10-18）：

tail,host=cfg-ubuntu-2204,path=/opt/data/telegraf/access.log,resp_code=200,verb=GET client_ip="10.0.0.12",ident="-",auth="-",request="/api/health",http_version=1.1,resp_bytes=1024i,referrer="-",agent="curl/8.5.0" 1792294201000000000
tail,host=cfg-ubuntu-2204,path=/opt/data/telegraf/access.log,resp_code=201,verb=POST agent="Mozilla/5.0",resp_bytes=3564i,referrer="https://shop.example.com/cart",client_ip="10.0.0.15",ident="-",auth="alice",request="/api/orders",http_version=1.1 1792294205000000000

要点：COMBINED_LOG_FORMAT 解析结果的 measurement 固定为 tail，path/resp_code/verb 等成为 tag，请求行/UA 等为字符串 field；低基数字段（状态码、方法）适合做 tag，URL 这类高基数字段保持 field 或用 grok_drop_captures 精简。tail 默认从文件尾续读（断点续传语义），验证历史数据时才设 initial_read_offset = "beginning"。

4.5 socket_listener / statsd（应用打点网关）

[[inputs.socket_listener]]
  service_address = "tcp://:8094"   # 另有 udp://；数据格式 Influx Line
  data_format = "influx"

[[inputs.statsd]]
  service_address = ":8125"         # 经典 statsd 协议（UDP）

实测闭环（常驻服务运行后向端口打点，输出文件照录）：

echo "app_request,svc=pay,code=200 count=1i" > /dev/tcp/localhost/8094
echo "demo.counter:1|c" > /dev/udp/localhost/8125

app_request,code=200,dc=sh1,host=cfg-ubuntu-2204,svc=pay count=1i 1792294860483180644
demo_counter,dc=sh1,host=cfg-ubuntu-2204 count=1i 1792294860000000000

两条链路均真实采到：应用侧零 SDK（一行文本打点）→ Telegraf 网关统一补 dc（global_tags，见 3.1）与 host → 落盘/转发；statsd 计数器自动改名为 demo_counter（点转下划线）。注意：Telegraf 是补齐维度的好网关，但它不提供 statsd 的仪表与告警，后端仍需时序库（见《Telegraf 集成实战》）。

4.6 本专栏暂不展开的 input 家族

mysql/redis/nginx（服务探针）、kafka_consumer/mqtt_consumer（消息消费）、snmp/modbus（网络与工业）、http/http_listener_v2（拉取与接收）等配置套路与上文一致：插件段声明参数 → --test 或 --usage 验证 → 输出端确认。完整插件清单见官方 plugins 目录与 telegraf --usage <name>（4.7 节）。

4.7 速查：--usage 查看插件模板

不确定某插件有哪些参数时（实测 telegraf --usage cpu 回显节选）：

# Read metrics about cpu usage
[[inputs.cpu]]
  ## Whether to report per-cpu stats or not
  percpu = true
  ## Whether to report total system cpu stats or not
  totalcpu = true
  ...

五、processors 实测

5.1 override：补固定维度

[[inputs.mem]]

[[processors.override]]
  [processors.override.tags]
    team = "sre"
    env = "lab"

实测输出（--test 照录，字段列表截断）：

> mem,env=lab,host=cfg-ubuntu-2204,team=sre active=15066439680u,available=9629966336u,available_percent=28.654382394734665,...

所有 metric 补上 team/env 两个 tag——与 global_tags 的区别：override 是流水线插件，可按声明顺序与 namepass 条件只作用于部分 metric。

5.2 date：注入时间维度 tag

[[processors.date]]
  tag_key = "day"
  date_format = "02"   # 注意：Go 时间布局，非 strftime

实测输出（--test 照录，字段列表截断）：

> mem,day=18,host=cfg-ubuntu-2204 active=15066750976u,...

当日（18 号）注入为 tag。

⚠️ 实测踩坑：date_format 用的是 Go 参考时间布局（2006-01-02）而非 strftime %d。实测写 %d 得到的 tag 值是字面量 %d；正确写法：天= 02、月= 01、年= 2006、时= 15、分= 04、秒= 05。

5.3 其他常用 processor 速览

六、aggregators 实测

6.1 basicstats：窗口统计

[[inputs.cpu]]
  percpu = false
  totalcpu = true
  fieldpass = ["usage_user"]

[[aggregators.basicstats]]
  period = "5s"        # 5 秒一个统计窗口
  drop_original = true # 丢弃原始点，只留聚合结果

实测输出文件（运行约 16 秒后照录）：

cpu,cpu=cpu-total,host=cfg-ubuntu-2204 usage_user_mean=4.570268679442909,usage_user_s2=2.44372708400717,usage_user_stdev=1.5632424904688236,usage_user_count=5,usage_user_min=2.958579881687375,usage_user_max=7.004219409318608 1792295260000000000

要点：basicstats 把原字段展开为 <field>_mean/_min/_max/_stdev/_s2/_count 六个统计字段（实测无 _sum/_last；_s2 是无偏方差、_stdev 为标准差），measurement 与 tag 不变；count=5 印证 5 秒窗口恰好覆盖 5 个 1s 采集点；drop_original = true 后原始点不再写出，存储成本立降。另注意聚合结果也要等 flush_interval 才落盘——短周期验证时把运行窗口拉到 ≥2×flush_interval。

6.2 其他 aggregator 速览

min / max（只留极值点）、final（窗口最后一个点，常配合 series_timeout 做存量快照）、histogram（分桶）、derivative / rate（差值与速率）、valuecounter（tag 值计数）、merge（多 series 合并）、quantile（分位数）。

七、outputs 实测

7.1 file：调试利器

[[outputs.file]]
  files = ["stdout"]                                # 打印到标准输出（journal 可见）
  # files = ["/opt/data/telegraf/metrics.out"]      # 或写文件
  # files = ["/opt/data/telegraf/m-%Y%m%d.out"]     # 支持日期轮转模板
  data_format = "influx"                            # Line Protocol（默认）

调试阶段一律先用 stdout，journalctl -u telegraf 或前台运行直接看行；写文件时注意服务以 telegraf 用户运行，目标文件属主要对（权限排障实录见《Telegraf 安装部署指南》6.4），且文件为追加模式——多轮实验写到同一文件会混入历史行，验证时先清空或换新文件名。

7.2 prometheus_client：暴露抓取端点

[[outputs.prometheus_client]]
  listen = ":9273"
  metric_version = 2

实测启动后 curl localhost:9273/metrics（照录节选）：

# HELP go_gc_duration_seconds A summary of the wall-time pause (stop-the-world) duration in garbage collection cycles.
mem_active{host="cfg-ubuntu-2204"} 1.4738432e+10
mem_available{host="cfg-ubuntu-2204"} 9.79808256e+09
mem_available_percent{host="cfg-ubuntu-2204"} 29.15461950888182

要点：measurement+field 拼成 Prometheus 指标名（mem_available_percent），tag 转 label（host=...）；metric_version = 2 是官方推荐命名方案（v1 会拼接出冗长指标名）。端到端 Prometheus 抓取方案见《Telegraf 集成实战》。

7.3 influxdb_v2：写入时序库（实战主战场）

[[outputs.influxdb_v2]]
  urls = ["http://127.0.0.1:8086"]
  token = "${INFLUX_TOKEN}"
  organization = "lab"
  bucket = "telegraf"

本文不展开——全链路（部署 InfluxDB → 建 token/bucket → Telegraf 写入 → Flux 查询验证）在《Telegraf 集成实战》完整实测。

八、调试与验证方法（实测方法论）

8.1 四个命令行开关

8.2 监听型插件的 --test 竞态

socket_listener/statsd 这类接收型插件在 --test（一次性退出）模式下可能来不及收包即退出，验证打点链路要用前台真跑 + 后台发数（实测脚本骨架）：

timeout 8 telegraf --config /etc/telegraf/demo/t-sl.conf > /tmp/sl.log 2>&1 &
sleep 2; echo "app_request,svc=pay count=1i" > /dev/tcp/localhost/8094
sleep 6; grep app_request /tmp/sl.log

另注意：多实例并存时端口互踩（实测报 E! [telegraf] Error running agent: starting input inputs.socket_listener: listen tcp :8094: bind: address already in use），用 ss -lntp 或逐个停实例排查。

8.3 配置排错三步法（实测总结）

1. 起不来先看 E! 行：telegraf --config xx.conf --once 2>&1 | grep -E "^E!"，报 DeprecationError ... removed = 1.40 已移除该插件（见 4.4 logparser）、报 xxx is not a valid option = 参数改名（如 tail 的 from_beginning → initial_read_offset）；
2. 起得来但没数据：确认 [agent] flush_interval（3.3）、outputs 是否 stdout（journal 可见）、监听端口是否被占（8.2）、outputs.file 是否追加到旧文件（7.1）；
3. 数据不对劲：查「tag 莫名消失」（3.4 环境变量）、Go 时间布局（5.2）、tag/field 类型（converter 修正）。

九、常见问题（FAQ）

Q1：老配置里 [[inputs.logparser]] 报错？ 1.15 弃用、1.40 移除（实测报错全文见 4.4）。迁移：改 [[inputs.tail]] + data_format = "grok"，from_beginning 改 initial_read_offset = "beginning"。

Q2：1.40 的 tail 为什么读不到已有日志内容？ 默认 initial_read_offset = "saved-or-end"（从文件尾续读）。历史内容需要解析时显式设 initial_read_offset = "beginning"（实测两种行为均已验证）。

Q3：metric 里该有的 tag 不见了？ 环境变量未注入（3.4 实测：1.40 严格模式下未定义变量不报错，tag 直接省略）。补导出变量或改用 secret-store（启动日志 8 secret stores 即为此能力）。

Q4：--test 能验证 outputs 吗？ 不能（8.1 实测：test 模式 outputs 不参与）。用 --once + outputs.file files=["stdout"] 看全链路。

Q5：两个 Telegraf 实例互相抢端口？ 监听型 input 端口唯一（8.2 实测报错）。要么换端口，要么用 --input-filter 隔离职责。

Q6：skip_processors_after_aggregators 警告？ 实测启动日志：W! The default value of 'skip_processors_after_aggregators' will change to 'true' with Telegraf v1.40.0!——若 processor 必须在 aggregator 之后执行（如对聚合结果改写），显式设 skip_processors_after_aggregators = false；否则可忽略。

十、参考链接

• 官方插件目录：https://github.com/influxdata/telegraf/tree/master/plugins
• 配置参考：https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md
• 数据解析指南（grok/tail）：https://github.com/influxdata/telegraf/blob/master/docs/PARSING_DATA.md
• TOML 语法说明：https://github.com/influxdata/telegraf/blob/master/docs/TOML.md
• 站内系列：《Telegraf 介绍与选型指南》《Telegraf 安装部署指南》《Telegraf 集成实战》