深入解读 prometheus/procfs:在 Grafana Tempo 中读取 /proc 与 /sys 系统指标的标准库
深入解读 prometheus/procfs:在 Grafana Tempo 中读取 /proc 与 /sys 系统指标的标准库
本文以 Grafana Tempo 仓库中 vendored 的 prometheus/procfs 使用文档 为主体,系统讲解这一 Go 库如何从 Linux 伪文件系统 /proc 与 /sys 中检索系统、内核与进程指标:包括核心 FS 类型的使用范式、包组织结构、构建测试方法以及测试 fixture 的维护流程。读完本文,你将掌握 procfs 的基本调用模型,并理解它作为 Tempo 间接依赖(v0.21.1)在可观测性底座中扮演的角色。
procfs 是什么:从伪文件系统读取内核数据的 Go 工具库
prometheus/procfs 是 Prometheus 生态中用于检索 Linux 系统指标的 Go 库。正如其 README 所述,它提供的函数从两个伪文件系统中收集数据:
/proc:进程与系统运行信息(进程状态、CPU 统计、内存、文件描述符等);/sys:内核导出的设备与子系统信息(块设备、网络等)。
在 Grafana Tempo 中,该库以间接依赖(// indirect)形式出现,版本为 v0.21.1,记录于 go.mod 与 vendor/modules.txt。它实际由 Prometheus 客户端库 client_golang 的进程指标采集器所使用(见 process_collector_procfsenabled.go 中的 procfs.NewDefaultFS() 调用),用于为 Tempo 自身暴露进程级的 CPU、内存与文件描述符指标——这正是一个分布式追踪后端实现"最小化依赖、高可用监控"的基础设施层。
需要特别注意的是,procfs 是 Linux 特有的库:它直接解析 /proc 与 /sys 下的内核接口文件,因此只在 Linux 主机上提供完整功能。README 也给出明确警告:该库仍处于演进中(work in progress),API 可能在无警告的情况下发生不兼容变更。
快速上手:初始化挂载点并读取统计信息
procfs 的核心抽象是一个 FS 类型,它代表 /proc、/sys 或两者的路径。绝大多数场景下,你只需要初始化 /proc 挂载点,然后直接调用读取函数。README 给出的最小示例如下:
fs, err := procfs.NewFS("/proc")
stats, err := fs.Stat()
NewFS(mountPoint string)返回一个绑定到指定挂载点的FS实例;如果挂载点目录无法读取或不是目录,会返回错误;fs.Stat()解析/proc/stat,返回内核与系统级统计。
如果目标路径恰好是系统默认挂载点 /proc,还可以用更简洁的 NewDefaultFS()。从 fs.go 的源码可以看到默认挂载点常量定义:
// DefaultMountPoint is the common mount point of the proc filesystem.
DefaultMountPoint = fs.DefaultProcMountPoint
底层实现(internal/fs/fs.go)中统一定义了各伪文件系统的默认挂载路径,除 /proc 外还包括 /sys、/sys/kernel/config 与 /sys/fs/selinux:
DefaultProcMountPoint = "/proc"
DefaultSysMountPoint = "/sys"
DefaultConfigfsMountPoint = "/sys/kernel/config"
DefaultSelinuxMountPoint = "/sys/fs/selinux"
初始化时 NewFS 会调用 os.Stat 校验挂载点存在且为目录,随后通过 Path(p ...string) 方法拼接文件路径(internal/fs/fs.go)。此外,NewFS 还会调用 isRealProc 检查挂载点是否为真实的 proc 文件系统,这一机制对在容器或测试环境中挂载模拟 /proc 的场景尤为重要。
同时需要 /proc 与 /sys 的场景:blockdevice 子包
部分子系统同时依赖两个伪文件系统。README 以 blockdevice 为例——磁盘块设备信息需要同时从 /proc/diskstats 与 /sys/block 读取:
fs, err := blockdevice.NewFS("/proc", "/sys")
stats, err := fs.ProcDiskstats()
这类子包不再用单个挂载点初始化,而是同时传入 /proc 与 /sys 的路径,封装了跨文件系统聚合的复杂度,调用方无需关心数据究竟来自哪个伪文件系统。
包组织结构:按数据来源与信息类型划分
README 明确了本项目的组织原则,即同时依据两点划分包:
- 数据来源:来自
/proc还是/sys(或两者); - 信息类型:进程信息、块设备信息、网络信息等。
具体来说:
- 绝大多数进程信息由根级
procfs包提供,例如进程状态、命令行参数、环境变量、内存映射、文件描述符与各种限制; - 块设备信息(如磁盘统计)由
blockdevice子包提供; - 仓库中还包含
sys风格的只读封装(见 vendor/github.com/prometheus/procfs 目录下的stat.go、meminfo.go、loadavg.go、net_dev.go、mdstat.go等数十个解析文件,以及internal/fs与internal/util两个内部辅助包)。
这种划分让使用者可以按需引入:只关心 CPU 统计就引入根包,关心磁盘就引入 blockdevice,避免无谓的代码膨胀。
核心 API 速览:从 FS 到 Proc 的调用链
除了 README 中的 FS.Stat() 示例,包文档 doc.go 给出了面向单个进程的完整用法,这是理解 API 层次的关键入口:
p, err := procfs.Self()
if err != nil {
log.Fatalf("could not get process: %s", err)
}
stat, err := p.Stat()
if err != nil {
log.Fatalf("could not get process stat: %s", err)
}
fmt.Printf("command: %s\n", stat.Comm)
fmt.Printf("cpu time: %fs\n", stat.CPUTime())
fmt.Printf("vsize: %dB\n", stat.VirtualMemory())
fmt.Printf("rss: %dB\n", stat.ResidentMemory())
整个调用链可分为两个层次:
- 系统/内核层(
FS方法):解析/proc/stat、/proc/meminfo、/proc/loadavg、/proc/net/*等全局文件。以 stat.go 中的Stat结构体为例,它聚合了启动时间、CPU 总计与按核统计、中断、上下文切换、进程创建数、运行/阻塞进程数以及 softirq 统计等字段;其解析函数parseCPUStat在读取原始数值后会除以userHZ完成从时钟 tick 到秒的换算(stat.go),调用方拿到的直接是物理时间单位。 - 进程层(
Proc方法):通过/proc/<pid>/目录下的文件按进程读取。常用方法包括Proc.CmdLine()(解析命令行参数,见 proc.go)、Proc.Comm()(进程名,见 proc.go)、Proc.Stat()(进程 CPU 与内存统计,见 proc_stat.go)以及Proc.Limits()(进程资源限制,见 proc_limits.go)。procfs.Self()则直接指向调用进程自身,非常适合做自监控。
构建与测试:作为库被集成,使用 make test 验证
procfs 定位为"被其他应用集成"的库,本身不产出可分发的二进制文件,这一点与 Grafana Tempo 对它的使用方式完全一致——Tempo 只是通过 Go module 机制将其编译进自身可执行文件。
仓库内大部分 API 都配有单元测试,可通过仓库根目录的 Makefile 运行:
make test
测试依赖一套随仓库分发的测试 fixture:这些 fixture 收录了大量来自真实 /proc 与 /sys 的示例文件,并以 ttar 归档形式打包,在测试过程中自动解压。这样即使在没有 Linux 环境的开发机上,测试也能基于固定的样本文件稳定运行。
更新测试 Fixture:完整工作流
当 procfs 需要新增或修正某个解析逻辑时,通常需要先扩充样本数据。README 给出了完整的 fixture 维护流程:
第 1 步:解包现有 fixture。删除旧的 testdata/fixtures 目录,再通过 make test(或 make testdata/fixtures/.unpacked)触发自动解包:
rm -rf testdata/fixtures
make test
第 2 步:修改样本文件。在解包出的 testdata/fixtures 目录中增删或修改需要的 /proc、/sys 示例文件。
第 3 步:重新打包。运行 make update_fixtures,将修改后的目录重新压缩为新的 fixtures.ttar 归档。
第 4 步:校验差异。用 git diff testdata/fixtures.ttar 检查归档变更是否符合预期,确认无误后再提交。
这套流程保证了"解析代码—测试样本—归档文件"三者始终同步,是维护内核接口解析库时值得借鉴的工程实践。
在 Grafana Tempo 中的实际定位与注意事项
结合本仓库的实际情况,使用 procfs 时有几点值得注意:
- 它是间接依赖:Tempo 并未直接调用 procfs,而是经 client_golang 的 process collector 间接使用,用于采集自身进程的 CPU、内存与文件描述符指标。因此在 go.mod 中它被标记为
// indirect,升级需跟随上游client_golang的版本约束。 - 平台限制:解析
/proc、/sys的代码只能在 Linux 上编译运行,跨平台构建时需依赖对应的构建约束与平台特化文件(如 cpuinfo_x86.go、cpuinfo_others.go 的分支实现)。 - API 稳定性:README 明确声明该库 API 可能随时发生不兼容变更,集成方应通过 vendor 锁定版本,Tempo 的 vendor 目录正是这种做法的体现——即使上游 API 变化,构建依然可复现。
总而言之,prometheus/procfs 是一套结构清晰、测试完备的 Linux 系统指标读取库:FS 类型统一了 /proc 与 /sys 的访问入口,根包与 blockdevice 等子包按信息类型分工,ttar fixture 机制则保证了解析逻辑的可测试性。理解它的使用与组织方式,既能帮助你读懂 Tempo 依赖树中的这一底层组件,也能为自行实现系统级指标采集提供直接可复用的范式。