Telegraf 集成实战

‍‍‌> 目标：把 Telegraf 1.40.2 与 InfluxDB 2.7.12 打通端到端指标链路——部署数据库、配置 outputs.influxdb_v2、重启服务、用 Flux 查询验证真实数据落库；每一步均照录实测回显（2026-10-18）。读完本篇即可复现「服务器指标 → 时序库 → 查询分析」的最小可用监控数据面。插件配置细节见《Telegraf 1.40 插件配置详解》，安装方式见《Telegraf 安装部署指南》。

一、环境信息

角色	系统	软件	角色
`srv-ubuntu-2204`	Ubuntu 22.04.5 LTS	Telegraf 1.40.2（systemd 托管，方案 A 安装）	采集代理，8 个系统 input
`ops`	Ubuntu 22.04	InfluxDB 2.7.12（官方镜像）	时序库后端，端口 8086

版本回显实测：

Telegraf 1.40.2 (git: HEAD@2e0a2ed1)
{"name":"influxdb", "message":"ready for queries and writes", "status":"pass", "checks":[], "version": "v2.7.12", "commit": "ec9dcde5"}

为什么选 InfluxDB 做第一集成：Telegraf 与 InfluxDB 同出 InfluxData，Line Protocol 原生对齐零转换；outputs.influxdb_v2 支持批量写、gzip 与自动重试，是 Telegraf 68 个 output 中最成熟的主航道（选型论证见《Telegraf 介绍与选型指南》）。

二、集成架构

┌───────────────────────────┐   HTTP POST /api/v2/write   ┌──────────────────────┐
│ srv-ubuntu-2204           │ ──────────────────────────► │ InfluxDB 2.7.12      │
│ Telegraf 1.40.2 (systemd) │   Line Protocol + token     │ bucket: telegraf     │
│ inputs: cpu/disk/diskio/  │   batch 1000 / flush 10s    │ org: lab             │
│ kernel/mem/processes/     │                             │ Flux 查询 :8086      │
│ swap/system               │                             └──────────────────────┘
└───────────────────────────┘                                      ▲
                                                                   │ Flux
                                                             分析/看板/告警

三、第一步：部署 InfluxDB 2.7

3.1 一条命令完成部署与初始化

官方镜像支持用 DOCKER_INFLUXDB_INIT_* 环境变量在首次启动时自动完成初始化（管理员账号、组织、bucket、token 一次建齐）：

docker run -d --name influxdb-2.7-telegraf-integration \
  -p 8086:8086 \
  -v /opt/data/influxdb-2.7-telegraf-integration:/var/lib/influxdb2 \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=sre \
  -e DOCKER_INFLUXDB_INIT_PASSWORD='Tg-Int-2026#lab' \
  -e DOCKER_INFLUXDB_INIT_ORG=lab \
  -e DOCKER_INFLUXDB_INIT_BUCKET=telegraf \
  -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN='tg-int-token-2026-lab' \
  influxdb:2.7

实测回显（镜像拉取）：

Status: Downloaded newer image for influxdb:2.7
aaa5c99d0d93acf6f2346ba2168085a7888d686c6e964d549da83e2960213a8a

服务监听确认（docker logs 照录）：

ts=2026-10-18T03:52:38.812669Z lvl=info msg=Listening log_id=15~I52Ql000 service=tcp-listener transport=http addr=:9999 port=9999
ts=2026-10-18T03:52:39.925692Z lvl=info msg=Listening log_id=15~I56wW000 service=tcp-listener transport=http addr=:8086 port=8086

说明：9999 是 InfluxDB v2 内部评测端口，实际对外只需 8086。初始化是幂等保护设计——若数据目录已存在则跳过 setup（实测日志照录）：
2026-10-18T03:52:39.859741875Z  info    found existing boltdb file, skipping setup wrapper      {"system": "docker", "bolt_path": "/var/lib/influxdb2/influxd.bolt"}

3.2 三项健康验证（实测照录）

# 1) 健康检查
curl -s http://localhost:8086/health

{"name":"influxdb", "message":"ready for queries and writes", "status":"pass", "checks":[], "version": "v2.7.12", "commit": "ec9dcde5"}

# 2) token 鉴权并列 bucket（预期看到 telegraf）
curl -s -H "Authorization: Token tg-int-token-2026-lab" "http://localhost:8086/api/v2/buckets?org=lab"

['_monitoring', '_tasks', 'telegraf']

# 3) 确认 setup 已完成（重新初始化被拒绝即正常）
curl -s http://localhost:8086/api/v2/setup

{
        "allowed": false
}

💡 安全提示：INIT_ADMIN_TOKEN 是全权限令牌，生产环境应改用随机长值并只保存在密管系统；本文为实验环境用了显式简单值，复现时请替换。

四、第二步：配置 Telegraf 输出端

4.1 写入 outputs.influxdb_v2 分片配置

利用包安装自带的分片目录机制（《Telegraf 安装部署指南》9.1），新增文件即可，不动主配置：

# /etc/telegraf/telegraf.d/influxdb.conf
[[outputs.influxdb_v2]]
  urls = ["http://172.17.0.34:8086"]   # InfluxDB 服务地址
  token = "tg-int-token-2026-lab"      # 初始化时设定的 ADMIN_TOKEN
  organization = "lab"
  bucket = "telegraf"

urls 填 InfluxDB 服务的可达地址；本例采集端与数据库同宿主网络，直接用服务 IP。跨机部署时填 http://<数据库主机IP>:8086 并确保防火墙放行。

4.2 重启并确认写入

systemctl restart telegraf

实测：systemctl is-active telegraf 回显 active；journal 中只有正常的采集输出行（如 diskio,host=srv-ubuntu-2204,name=loop11 ...），没有任何 E! 错误行——Telegraf 对写入失败会刷 E! [agent] Error writing to outputs.influxdb_v2 ...，日志干净即说明写入链路通畅。

五、第三步：Flux 查询验证（数据真实落库）

5.1 查 cpu 最新点

在 InfluxDB 服务内用内置 CLI 执行 Flux：

influx query --org lab --token tg-int-token-2026-lab \
  'from(bucket:"telegraf") |> range(start:-5m) |> filter(fn:(r) => r._measurement == "cpu" and r._field == "usage_idle") |> last()'

实测回显（照录，节选前三个 series）：

Result: _result
Table: keys: [_start, _stop, _field, _measurement, cpu, host]
                   _start:time                      _stop:time           _field:string     _measurement:string              cpu:string             host:string                      _time:time                  _value:float
------------------------------  ------------------------------  ----------------------  ----------------------  ----------------------  ------------------------------  ----------------------------
2026-10-18T03:48:44.765130974Z  2026-10-18T03:53:44.765130974Z              usage_idle                     cpu               cpu-total         srv-ubuntu-2204  2026-10-18T03:53:40.000000000Z             88.32491582484921
...
2026-10-18T03:48:44.765130974Z  2026-10-18T03:53:44.765130974Z              usage_idle                     cpu                    cpu0         srv-ubuntu-2204  2026-10-18T03:53:40.000000000Z             83.08270676688902
...
2026-10-18T03:48:44.765130974Z  2026-10-18T03:53:44.765130974Z              usage_idle                     cpu                    cpu1         srv-ubuntu-2204  2026-10-18T03:53:40.000000000Z             88.86679920479898

采集端 10 秒一个点的 usage_idle 已实时进入 bucket（数据时刻 03:53:40，查询时刻 03:53:44，延迟仅 4 秒 = flush 周期 + 查询开销）。

5.2 确认接入的 measurement 清单

influx query --org lab --token tg-int-token-2026-lab \
  'import "influxdata/influxdb/schema" schema.measurements(bucket:"telegraf", start:-5m)'

实测回显（照录）：

Result: _result
Table: keys: []
         _value:string
----------------------
                   cpu
                  disk
                diskio
                kernel
                   mem
             processes
                  swap
                system

8 个 measurement 与 Telegraf 默认启用的 8 个系统 input 完全对应（《Telegraf 安装部署指南》4.4 的 Loaded inputs: 行），无缺漏。

5.3 再抽一个 measurement 交叉验证

influx query --org lab --token tg-int-token-2026-lab \
  'from(bucket:"telegraf") |> range(start:-5m) |> filter(fn:(r) => r._measurement == "mem" and r._field == "used_percent") |> last()'

实测回显（尾行照录）：

2026-10-18T03:48:51.622774781Z  2026-10-18T03:53:51.622774781Z            used_percent                     mem         srv-ubuntu-2204  2026-10-18T03:53:40.000000000Z             72.95686033812197

至此全链路闭环：Telegraf 采集（journal 可见）→ HTTP 写入（无错误日志）→ InfluxDB 落库（Flux 查出真实数值）。后续接 Grafana（InfluxDB Flux 数据源填同一 token）即可出图，不在本文展开。

六、outputs.influxdb_v2 关键参数表

参数	默认	说明
urls	—	服务地址数组，可多活轮询
token	—	v2 令牌（建议 `${INFLUX_TOKEN}` 环境变量注入，见《Telegraf 1.40 插件配置详解》3.4）
organization / bucket	—	写入目标空间与桶
batch_size	5000	每批写入点数（官方默认；全局 metric_batch_size 默认 1000 时以小者为准）
flush_interval	10s	写出周期
quota	—	写入速率限制
use_gzip	false	开启 gzip 压缩传输，跨机房带宽紧张时建议开启
idle_connection_timeout	0	空闲连接保持

七、故障排查（对照实测现象）

E! ... unauthorized: 401 Unauthorized：token 错或 organization/bucket 名不符——用 3.2 的 curl 先独立验证 token 可用性，再回头查 Telegraf 配置；
E! ... connection refused：urls 地址/端口不通——采集端 curl -s http://<addr>:8086/health 先排网络；
查询没数据但无报错：核对 bucket 名与查询的 range(start:) 窗口；Flux 的 last() 只在窗口内有数据时返回；
数据时间不对：两端主机时钟漂移——InfluxDB 按采集端时间戳入库，telegraf 主机需 NTP 对时。

八、参考链接

InfluxDB v2 官方文档：https://docs.influxdata.com/influxdb/v2/
Telegraf influxdb_v2 输出插件：https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2
Flux 查询语言：https://docs.influxdata.com/flux/v0/
Docker 镜像说明：https://hub.docker.com/_/influxdb
站内系列：《Telegraf 介绍与选型指南》《Telegraf 安装部署指南》《Telegraf 1.40 插件配置详解》