Grafana Mimir 背后的 CPU 数量探测库:numcpus 的跨平台实现与实战指南

原创2026-10-14 21:50:541,640 阅读
文章标签:时序数据库后端数据存储可观测性云原生

Grafana Mimir 背后的 CPU 数量探测库:numcpus 的跨平台实现与实战指南

导读

在 Grafana Mimir 这类需要精确感知宿主机算力资源的长时存储服务中,程序经常需要回答"这台机器到底有多少个 CPU"这一类问题。numcpus(README)正是为此而生的 Go 库:它以极小的 API 面,统一提供 Linux、Darwin、各 BSD、Solaris/Illumos 与 Windows 平台上的 CPU 数量查询能力,区分 online / offline / present / possible / configured / kernel maximum 等六种不同的 CPU 语义。阅读本文后,你将掌握 numcpus 全部公共 API 的语义与跨平台实现原理,能够直接在自己的 Go 服务中用它编写精确的 CPU 探测逻辑,并理解它在 Grafana Mimir 依赖树中承担的角色。

一、库的定位:一个函数一个语义的 CPU 计数工具

numcpus 的包注释(见 numcpus.go)将其定位描述为:提供系统中 CPU 数量的信息,可获取 online(在线)、offline(离线)、present(现存)、possible(可能)、configured(已配置)或 kernel maximum(内核上限)等不同口径的 CPU 数量。

它不是运行时探针,不提供 CPU 利用率采样,也完全不依赖 cgo;所有实现都基于操作系统原生接口(sysfs、sysctl、sysconf 或 Windows API)与标准库、golang.org/x/sys 完成。这使它特别适合用于:

  • 服务启动时按 CPU 数量自动设置并发度、Worker 池大小;
  • 容器/宿主机环境中判断可调度 CPU 规模,辅助资源配置决策;
  • 需要区分"在线 CPU"与"配置 CPU"这类细微差异的系统监控与容量规划。

值得注意的是,该库的设计哲学是"每种语义一个函数",调用者按需精确选择口径,而不是笼统地拿到一个"CPU 总数"。

二、公共 API 全景:六种数量口径与四种列表接口

numcpus 的完整公共 API 定义在 numcpus.go 中,全部函数签名均为 func xxx() (int, error) 或 func ListXxx() ([]int, error)。语义对比如下:

函数 语义 平台支持
GetConfigured() 系统中配置的 CPU 数量,与 Unix 上 getconf _SC_NPROCESSORS_CONF 返回值一致 Linux、BSD、Solaris、Windows
GetKernelMax() 内核配置允许的最大 CPU 数量 仅 Linux、Windows(FreeBSD 亦支持)
GetOffline() 离线 CPU 数量(被热插拔下线或超过内核上限的 CPU) 仅 Linux
GetOnline() 在线且被调度器调度使用的 CPU 数量 全部受支持平台
GetPossible() 可能存在的 CPU 数量(已分配资源、若存在即可上线) Linux、BSD、Solaris、Windows
GetPresent() 系统中实际存在的 CPU 数量 Linux、BSD、Solaris、Windows
ListOffline() / ListOnline() / ListPossible() / ListPresent() 分别返回对应 CPU 集合的编号列表 []int 仅 Linux

四种 List* 接口在 Linux 之外不可用:源码通过构建标签隔离,numcpus_list_unsupported.go 使非 Linux 平台的 listOffline、listOnline、listPossible、listPresent 一律返回 ErrNotSupported。

库的公共错误只有一个——ErrNotSupported,当某个函数在特定平台上不受支持时返回(numcpus.go)。因此跨平台代码的正确姿势是:总是检查 error,并对 ErrNotSupported 给出降级策略,而不是假定函数一定可用。

三、跨平台实现原理:五套操作系统后端

3.1 Linux:直接读取 sysfs CPU 拓扑文件

Linux 后端(numcpus_linux.go)的根目录固定为 /sys/devices/system/cpu,并直接读取其中的 online、offline、possible、present 四个属性文件以及 kernel_max 文件。这些文件的内容是典型的 CPU range 表示法,例如 0-3,8-11 表示 0~3 与 8~11 号 CPU。

countCPURange(numcpus_linux.go)负责把这种表示法解析为数量:以逗号切分各段,段内用 - 区分起止编号,解析出 last - first + 1 个 CPU;并专门处理了空文件合法的情形——例如 offline 文件为空即表示当前没有离线 CPU,此时返回 0 而非报错。listCPURange(numcpus_linux.go)则以同样规则展开为完整的 CPU 编号切片。

两个容易被忽略的实现细节:

  • getConfigured 并不读取任何文件,而是 Readdir 扫描 /sys/devices/system/cpu 目录,统计所有名为 cpuN(cpu 后跟十进制数字)的子目录数量(numcpus_linux.go),这也正是它要与 getconf _SC_NPROCESSORS_CONF 对齐的缘由;
  • getOnline 优先调用 sched_getaffinity(0) 获取当前进程的 CPU 亲和性集合(numcpus_linux.go),只在亲和性查询失败时才回退到读取 online 文件。这意味着在 CPU 绑定的容器场景下,GetOnline() 返回的是进程实际可用的 CPU 数,而非宿主机全部在线 CPU——这对资源受限环境下的并发度决策意义重大。

3.2 BSD / Darwin:hw.ncpu 与 hw.ncpuonline sysctl

BSD 系列后端(numcpus_bsd.go)通过 golang.org/x/sys/unix 读取 sysctl:

  • GetConfigured、GetPossible、GetPresent 均读 hw.ncpu;
  • GetOnline 在 NetBSD / OpenBSD 上优先读 hw.ncpuonline,失败时回退 hw.ncpu,其余 BSD 与 Darwin 直接读 hw.ncpu(numcpus_bsd.go);
  • GetKernelMax 仅在 FreeBSD 上支持,读 kern.smp.maxcpus,其余平台返回 ErrNotSupported;
  • GetOffline 在所有 BSD/Darwin 平台均不支持。

3.3 Solaris / Illumos:sysconf 系统调用

Solaris 后端(numcpus_solaris.go)从 /usr/include/sys/unistd.h 中摘取了三个常量:_SC_NPROCESSORS_CONF = 14、_SC_NPROCESSORS_ONLN = 15、_SC_NPROCESSORS_MAX = 516,并据此调用 unix.Sysconf。其中 GetConfigured、GetPossible、GetPresent 都对应 _SC_NPROCESSORS_CONF,GetOnline 对应 _SC_NPROCESSORS_ONLN,GetKernelMax 对应 _SC_NPROCESSORS_MAX。

3.4 Windows:处理器组感知的 Win32 API

Windows 后端(numcpus_windows.go)使用 windows.GetActiveProcessorCount(windows.ALL_PROCESSOR_GROUPS) 与 windows.GetMaximumProcessorCount(...)。通过传入 ALL_PROCESSOR_GROUPS,即使系统包含多个处理器组,也能得到跨组的完整计数。GetConfigured、GetOnline、GetPossible、GetPresent 共用前者,GetKernelMax 用后者,GetOffline 不支持。

3.5 其余平台:统一返回 ErrNotSupported

对于上述平台之外的系统,构建标签 !darwin && !dragonfly && !freebsd && !linux && !netbsd && !openbsd && !solaris && !windows 会命中 numcpus_unsupported.go,全部 get* 函数固定返回 ErrNotSupported,保证库在任何 Go 构建环境下都能编译通过。

四、快速上手:完整可运行示例

原文档给出的用法示例(README)可以直接作为工程起点。下面是在其基础上补充了全部 API 与降级处理的最小演示程序:

package main

import (
	"fmt"
	"os"

	"github.com/tklauser/numcpus"
)

func main() {
	// 在线且被调度器调度的 CPU 数量
	online, err := numcpus.GetOnline()
	if err != nil {
		fmt.Fprintf(os.Stderr, "GetOnline: %v\n", err)
	}
	fmt.Printf("online CPUs: %v\n", online)

	// 可能存在的 CPU 数量(已分配资源)
	possible, err := numcpus.GetPossible()
	if err != nil {
		fmt.Fprintf(os.Stderr, "GetPossible: %v\n", err)
	}
	fmt.Printf("possible CPUs: %v\n", possible)

	// 已配置 CPU 数量,等价于 getconf _SC_NPROCESSORS_CONF
	configured, err := numcpus.GetConfigured()
	if err != nil {
		fmt.Fprintf(os.Stderr, "GetConfigured: %v\n", err)
	}
	fmt.Printf("configured CPUs: %v\n", configured)

	// 离线 CPU 数量(仅 Linux 支持,其他平台返回 ErrNotSupported)
	offline, err := numcpus.GetOffline()
	if err == numcpus.ErrNotSupported {
		fmt.Println("GetOffline: not supported on this platform")
	} else if err != nil {
		fmt.Fprintf(os.Stderr, "GetOffline: %v\n", err)
	} else {
		fmt.Printf("offline CPUs: %v\n", offline)
	}
}

引入依赖:

go get github.com/tklauser/numcpus

在 Linux 上运行上述程序,你会看到形如 online CPUs: 8、possible CPUs: 8、configured CPUs: 8 的输出;若在容器内且进程被限制到部分 CPU,GetOnline() 会反映进程实际可用的 CPU 数(Linux 后端优先走亲和性探测)。

五、在 Grafana Mimir 仓库中的实际角色

numcpus 出现在 Grafana Mimir 的依赖树中,但不是被 Mimir 代码直接调用。在 go.mod 中它以 github.com/tklauser/numcpus v0.11.0 // indirect 标记为间接依赖,真正引用它的是另一个间接依赖 github.com/tklauser/go-sysconf:

即 numcpus 在 Mimir 中承担的是"为 sysconf 兼容层提供 Linux CPU 计数"的底层职能。从更宏观的视角看,Mimir 自身的算力感知更多依赖 Go 标准库的 runtime.NumCPU() 与 runtime.GOMAXPROCS(0):

  • cmd/mimir/main.go 中的 clampGOMAXPROCS() 会在环境变量设置的 GOMAXPROCS 高于 runtime.NumCPU() 时将其钳制回 NumCPU 并输出告警日志;
  • 多个组件的并发度默认值都跟随 GOMAXPROCS,例如 pkg/ingester/ingester.go 的 ingester.compute-workers 参数在取 0 时使用 GOMAXPROCS,pkg/util/workerpool/pool.go 的 worker 池大小默认同样取自 GOMAXPROCS。

理解 numcpus 的 online/possible 语义差异,有助于你更精确地解读这类"并发度由 CPU 数量推导"的服务端配置逻辑。

六、选型建议与注意事项

  1. 按语义选函数,不要一律取"总数":统计 worker 规模优先 GetOnline()(真正可调度);评估硬件规模用 GetPresent() 或 GetConfigured();做热插拔监控才需要 GetOffline() 与 GetKernelMax()。
  2. 始终处理 error:非 Linux 平台上 GetKernelMax、GetOffline 及全部 List* 都返回 ErrNotSupported,跨平台程序必须有降级分支。
  3. 容器场景注意 Linux 特例:GetOnline() 优先返回进程亲和性集合大小,因此在容器限制 CPU 时会得到受限值,这可能正是你想要的,也可能出乎意料,需结合部署环境判断。
  4. 与 runtime.NumCPU() 互补而非替代:runtime.NumCPU() 只能给出进程可用的逻辑 CPU 数,无法区分 online / offline / present / possible 这些细粒度口径;需要这些区分度时再引入 numcpus。

七、深入阅读

  • 完整 API 与文档注释:numcpus.go
  • Linux 实现(sysfs 解析与亲和性探测):numcpus_linux.go
  • BSD / Darwin sysctl 实现:numcpus_bsd.go
  • Solaris / Illumos 实现:numcpus_solaris.go
  • Windows 实现:numcpus_windows.go
  • 在 Mimir 依赖树中的调用链:sysconf_linux.go
  • 原文档在仓库中的位置:README,其中 References 指向的 Linux 内核 sysfs CPU 属性文档与 CPU 拓扑文档,是理解 /sys/devices/system/cpu 各属性文件语义的权威参考资料。
登录后查看全文
mimir