企业官网建设流程全解析

Telegraf 快速上手指南：用 Docker 在五分钟内完成 CPU 与内存指标采集

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

本篇技术指南以 docs/QUICK_START.md 为骨架，面向希望快速上手 Telegraf 的开发者与运维人员：通过官方 Docker 镜像，在本地拉起一个可用的指标采集代理，用一份最简 TOML 配置同时启用 CPU、内存两个输入插件和 file 输出插件，把采集到的指标打印到 STDOUT。读完本文你将掌握 Telegraf「安装 → 配置 → 启动 → 调试 → 扩展」的完整闭环，并理解指标从输入到输出的底层数据管道原理，具备独立把 Telegraf 接入自己监控体系的能力。

一、先认识 Telegraf

Telegraf 是一个用 Go 编写的指标采集代理（agent），负责「收集（collecting）、处理（processing）、聚合（aggregating）、写入（writing）」metrics、日志及其它任意数据。它编译为单一静态二进制，无外部运行时依赖，使用 TOML 作为配置语言。其插件体系庞大——在 plugins/inputs 下可以看到 240 余个输入插件，在 plugins/outputs 下有大量输出插件，覆盖系统监控（CPU、内存、磁盘、网络）、设备（OPC UA、Modbus）、消息队列（Kafka、MQTT、AMQP）、云服务、可观测性后端（Prometheus、OpenTelemetry）等场景。

使用方式非常直接：用户编写一份 TOML 配置，声明要启用的插件及其参数，交给 Telegraf 执行。代理按采集周期（interval）从输入插件取数，按刷新周期（flush interval）把累积的指标批量写入输出插件。如果你想快速体验这一过程，跟随本文即可。

二、安装：拉取官方 Docker 镜像

快速上手最省事的方式是使用 Docker。官方在 Docker Hub 上提供了维护良好的 Telegraf 镜像（同时维护 Debian 与 Alpine 两种基础镜像版本）：

docker pull telegraf

拉取成功后即可使用telegraf镜像名直接运行容器。

如果你的环境不适合使用 Docker，Telegraf 还支持多种安装途径，详见 安装指南：包括预编译二进制下载、Homebrew（brew install telegraf）、InfluxData 的 DEB/RPM 软件源（Ubuntu/Debian 与 RHEL/CentOS 各有对应的源配置命令）、Helm Chart、每日 Nightly 构建，以及git clone后执行make build从源码编译。此外仓库还提供了 custom_builder 工具，可以根据你实际的配置文件裁剪出只包含所需插件的最小化二进制，显著减小体积。

三、理解配置：TOML 与「至少一个输入 + 一个输出」

Telegraf 启动必须有配置，而一份可用的配置至少要满足两个条件：

1. 至少一个输入插件（input）：负责产生数据；
2. 至少一个输出插件（output）：负责接收并写出数据。

配置文件本身是 TOML 格式。TOML 文档 中特别强调了几点容易踩坑的语法规则：

• 数组表（Array of Tables）：定义插件使用的是[[插件名]]语法，这意味着同一个插件可以被定义多次（例如分别连接不同端点的两个相同输出插件）；
• 单表 vs 数组表：[agent]这类单表用于控制 agent 级全局行为，整份配置（含被加载的所有文件）中只能定义一次；而[[inputs.xxx]]数组表可重复出现；
• 内联表（Inline Table）：给插件添加 tag 时，[inputs.cpu.tags]子表必须放在插件定义的末尾，否则其后的键值对会被误解析为 tag。推荐用内联表写法tags = {tag1 = "foo", tag2 = "bar"}规避歧义；
• 字符串转义：基本字符串（双引号）中反斜杠需转义，如 Windows 路径path = "C:\\Program Files\\"；或改用字面量字符串（单引号）path = 'C:\Program Files\'，字面量内不做任何转义。

四、编写第一份配置 config.toml

创建文件config.toml，内容如下：

$ cat config.toml [[inputs.cpu]] [[inputs.mem]] [[outputs.file]]

这份配置启用了两个输入插件（CPU 与内存）和一个输出插件（file）。输入插件负责采集 CPU 与内存的使用信息，而 file 输出插件默认把指标以 InfluxDB line protocol 格式打印到STDOUT。

4.1 inputs.cpu：CPU 使用率采集

从 CPU 插件源码 可以看到，它通过 gopsutil 读取系统 CPU 时间，并在两次采集之间做差值计算，输出usage_user、usage_system、usage_idle、usage_iowait、usage_steal等百分比指标（第一次启动时因缺少基准值会跳过百分比计算）。其完整示例配置见 CPU 示例配置，关键参数包括：

[[inputs.cpu]] ## 是否报告每个物理核心（per-cpu）的统计 percpu = true ## 是否报告系统整体 CPU 统计 totalcpu = true ## 若为 true，额外采集原始 CPU 时间（time_user、time_system 等） collect_cpu_time = false ## 若为 true，计算并报告所有非 idle CPU 状态之和（注意 time_active 包含 iowait） report_active = false ## 若为 true 且系统信息可用，为指标添加 core_id 与 physical_id 标签 core_tags = false

4.2 inputs.mem：内存指标采集

内存插件源码 在不同平台输出不同字段集合：所有平台都输出total、available、used、used_percent、available_percent基础字段；在 Linux 上还会额外输出active、buffered、cached、free、dirty、swap_total、swap_free、slab等扩展字段（可在插件配置中设置collect_extended = true进一步采集）。

4.3 outputs.file：把指标写到文件或 STDOUT

file 输出插件源码 中，"stdout"是一个被特殊处理的"文件"名：当files列表为空或包含"stdout"时，指标被写入标准输出。其完整示例配置见 file 示例配置，可用的参数包括：

[[outputs.file]] ## 写入目标文件，"stdout" 是被特殊处理的伪文件 files = ["stdout", "/tmp/metrics.out"] ## 是否使用批量序列化格式（适合非按行分隔的输出格式） # use_batch_format = false ## 按时间轮转日志文件，0 表示不按时间轮转 # rotation_interval = "0h" ## 按大小轮转日志文件，0 表示不按大小轮转 # rotation_max_size = "0MB" ## 保留的最大轮转归档数，-1 表示不清理 # rotation_max_archives = 5 ## 输出数据格式，默认 influx（InfluxDB line protocol） data_format = "influx" ## 压缩算法：zstd / gzip / zlib，留空表示不压缩 # compression_algorithm = "" ## 压缩级别，-1 表示使用各算法默认级别 # compression_level = -1

4.4 关于「插件可重复定义」

原文档特别提醒：插件定义是 TOML 的数组表，因此同一个插件可以定义多次。这在需要连接不同端点时非常实用——例如两个[[inputs.snmp]]分别采集不同网络设备，或两个[[outputs.influxdb]]写入不同数据库。

五、启动：用 Docker 运行 Telegraf

镜像拉取完成、配置文件就绪后，执行以下命令启动：

docker run --rm --volume $PWD/config.toml:/etc/telegraf/telegraf.conf telegraf

命令要点说明：

• --volume $PWD/config.toml:/etc/telegraf/telegraf.conf：把当前目录下的config.toml挂载到容器内 Telegraf 的默认配置路径/etc/telegraf/telegraf.conf；
• --rm：容器退出后自动清理；
• 镜像默认入口即 Telegraf 主程序，启动后按挂载的配置运行。

5.1 启动日志里有什么

启动后，终端会先打印一系列初始化信息。对照 启动入口源码（runAgent函数），这些日志依次包含：

• 版本信息：I! Starting Telegraf <版本号> brought to you by InfluxData the makers of InfluxDB；
• 可用插件统计：I! Available plugins: <N> inputs, ...；
• 本次实际加载的插件清单：I! Loaded inputs: ...、I! Loaded outputs: ...；
• 启用的全局标签：I! Tags enabled: ...；
• 若检测到已弃用插件或选项，会打印W! Deprecated ...警告。

如果配置中缺少输出或输入，启动会直接报错退出——telegraf.go 中明确做了「no outputs found」与「no inputs found」的校验。此外 agent 配置模板 展示了大量可调项：默认采集间隔interval = "10s"、默认刷新间隔flush_interval = "10s"、批大小metric_batch_size = 1000、缓冲上限metric_buffer_limit = 10000、round_interval、collection_jitter、hostname覆盖等，这些都以[agent]单表形式写在配置中。

5.2 看到指标输出

初始化日志打完后（大约数秒内），指标便会开始打印到 STDOUT，形如 InfluxDB line protocol：

cpu,cpu=cpu0,host=your-host usage_user=4.2,usage_system=2.8,usage_idle=90.7,usage_iowait=0.5 1726123456789012345 mem,host=your-host total=16777216000,available=8388608000,used=8388608000,used_percent=50.0,available_percent=50.0 1726123456789012345

（以上为格式示意，具体字段取值取决于你的机器。）其中cpu、mem是度量名（measurement），cpu=cpu0、host=...是标签（tag），usage_*、total、used_percent等是字段（field），末尾为纳秒级时间戳。

5.3 背后的数据管道：指标如何从输入流向输出

打印出来的每一行指标，都经历了 agent 核心运行逻辑 中描述的管道化处理流程：

1. 采集（Gather）：runInputs为每个输入插件创建定时器（默认 10s 一次，round_interval开启时会对齐到整点），循环调用插件的Gather方法，见 gatherLoop；若某次采集超过一个周期仍未完成，会打印W! Collection took longer than expected警告；
2. 处理与聚合（可选）：指标依次经过处理器（processor）与聚合器（aggregator）链；
3. 写入（Flush）：flushLoop按flush_interval（默认 10s）周期性地把缓冲区内的指标批量交给输出插件的Write方法，见 flushLoop。停机时还会执行最后一次 flush（日志I! [agent] Hang on, flushing any cached metrics before shutdown），尽量不丢数据。

这也解释了为什么指标不是每毫秒都在刷新，而是以「采集周期 + 刷新周期」的节奏成批出现。

六、调试技巧：先--test再上线

正式投入监控前，建议先用 Telegraf 的测试模式验证配置。在不带--test正常运行时，agent 会持续循环采集；而telegraf --test模式只执行一次采集并立即把结果打印到标准输出后退出（相关逻辑见 telegraf.go 与 agent.go，测试模式下输出插件会被绕过）。在 Docker 环境可这样验证：

docker run --rm --volume $PWD/config.toml:/etc/telegraf/telegraf.conf telegraf --test

如果配置解析有问题或插件初始化失败，错误信息会直接打印在终端，方便快速迭代。这是排查「为什么没数据」的首选手段。

七、下一步：从 Quick Start 走向生产级监控

走出这份快速上手后，可以沿着以下路线继续深入（对应原文档的 Next steps 指引）：

1. 选定数据来源：浏览完整的 输入插件列表，按需接入系统（磁盘、网络、进程）、中间件（MySQL、Redis、Kafka）、云服务或自定义 HTTP/Exec 采集；
2. 选定数据去向：浏览 输出插件列表，把指标写入 InfluxDB、Prometheus、Kafka、文件或任意 HTTP 端点；
3. 掌握更多部署方式：阅读 安装指南 了解二进制、软件包、Kubernetes 等生产部署路径，阅读 配置文档 深入了解 agent 全局参数（采集间隔、批大小、缓冲、日志轮转、状态持久化等）；
4. 处理任意数据：如果需要把日志或任意格式数据送入 Telegraf，阅读 解析数据指南，它覆盖了 JSON、CSV、grok、line protocol 等各类解析器；
5. 进阶玩法：可进一步阅读 聚合器与处理器说明 了解数据聚合变换，或浏览 metric 模块 与 models 源码理解指标模型与运行态封装。

至此，你已经完成了「拉镜像 → 写配置 → 跑起来 → 看指标 → 会调试」的完整循环。下一步，就是把这份最小配置替换为适合你生产环境的真实插件组合了。

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