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

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 接入自己监控体系的能力。一、先认识 TelegrafTelegraf 是一个用 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镜像名直接运行容器。如果你的环境不适合使用 DockerTelegraf 还支持多种安装途径详见 安装指南包括预编译二进制下载、Homebrewbrew install telegraf、InfluxData 的 DEB/RPM 软件源Ubuntu/Debian 与 RHEL/CentOS 各有对应的源配置命令、Helm Chart、每日 Nightly 构建以及git clone后执行make build从源码编译。此外仓库还提供了 custom_builder 工具可以根据你实际的配置文件裁剪出只包含所需插件的最小化二进制显著减小体积。三、理解配置TOML 与「至少一个输入 一个输出」Telegraf 启动必须有配置而一份可用的配置至少要满足两个条件至少一个输入插件input负责产生数据至少一个输出插件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.cpuCPU 使用率采集从 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 false4.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把指标写到文件或 STDOUTfile 输出插件源码 中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 ## 输出数据格式默认 influxInfluxDB line protocol data_format influx ## 压缩算法zstd / gzip / zlib留空表示不压缩 # compression_algorithm ## 压缩级别-1 表示使用各算法默认级别 # compression_level -14.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 protocolcpu,cpucpu0,hostyour-host usage_user4.2,usage_system2.8,usage_idle90.7,usage_iowait0.5 1726123456789012345 mem,hostyour-host total16777216000,available8388608000,used8388608000,used_percent50.0,available_percent50.0 1726123456789012345以上为格式示意具体字段取值取决于你的机器。其中cpu、mem是度量名measurementcpucpu0、host...是标签tagusage_*、total、used_percent等是字段field末尾为纳秒级时间戳。5.3 背后的数据管道指标如何从输入流向输出打印出来的每一行指标都经历了 agent 核心运行逻辑 中描述的管道化处理流程采集GatherrunInputs为每个输入插件创建定时器默认 10s 一次round_interval开启时会对齐到整点循环调用插件的Gather方法见 gatherLoop若某次采集超过一个周期仍未完成会打印W! Collection took longer than expected警告处理与聚合可选指标依次经过处理器processor与聚合器aggregator链写入FlushflushLoop按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 指引选定数据来源浏览完整的 输入插件列表按需接入系统磁盘、网络、进程、中间件MySQL、Redis、Kafka、云服务或自定义 HTTP/Exec 采集选定数据去向浏览 输出插件列表把指标写入 InfluxDB、Prometheus、Kafka、文件或任意 HTTP 端点掌握更多部署方式阅读 安装指南 了解二进制、软件包、Kubernetes 等生产部署路径阅读 配置文档 深入了解 agent 全局参数采集间隔、批大小、缓冲、日志轮转、状态持久化等处理任意数据如果需要把日志或任意格式数据送入 Telegraf阅读 解析数据指南它覆盖了 JSON、CSV、grok、line protocol 等各类解析器进阶玩法可进一步阅读 聚合器与处理器说明 了解数据聚合变换或浏览 metric 模块 与 models 源码理解指标模型与运行态封装。至此你已经完成了「拉镜像 → 写配置 → 跑起来 → 看指标 → 会调试」的完整循环。下一步就是把这份最小配置替换为适合你生产环境的真实插件组合了。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考