Go runtime/metrics 和 expvar 怎么选择暴露指标

如果你在 Go 服务里纠结“运行时指标到底用 runtime/metrics 还是 expvar”，先看指标是谁拥有：Go runtime 自己定义的 GC、内存、调度指标用 runtime/metrics；业务代码维护的请求数、队列长度和开关状态用 expvar。两者可以同时使用，但不要把业务变量硬塞进 runtime/metrics，也不要把运行时指标复制成一堆手工变量。

一、先按指标归属判断工具

选择的分界线不是“哪个 API 更新”，而是指标的所有者。堆对象字节数、GC 辅助 CPU 时间、调度延迟这类信息由运行时产生，应用只负责定期读取，适合 runtime/metrics。订单处理数、缓存命中数、当前排队任务数则是业务代码写入的变量，适合 expvar。

二、用 runtime/metrics 按名称和 Kind 采样

runtime/metrics 在 Go 1.16 引入，接口用字符串 key 描述指标，而不是暴露一个固定字段结构。实际读取时先从 metrics.All() 建立支持集合，再复用 []metrics.Sample 调用 metrics.Read。这样做能避免把某个版本的完整指标清单误当成永久协议。

package main

import (
	"fmt"
	"runtime/metrics"
)

func readHeapObjects() {
	const name = "/memory/classes/heap/objects:bytes"

	// 只读取当前 Go 运行时声明过的指标，避免版本差异被误判为零值。
	supported := false
	for _, desc := range metrics.All() {
		if desc.Name == name {
			supported = true
			break
		}
	}
	if !supported {
		fmt.Println("metric unavailable:", name)
		return
	}

	// 复用 Sample，周期采集时可以减少重复分配。
	sample := []metrics.Sample{{Name: name}}
	metrics.Read(sample)
	if sample[0].Value.Kind() != metrics.KindUint64 {
		fmt.Println("unexpected metric kind:", sample[0].Value.Kind())
		return
	}
	fmt.Println(name, sample[0].Value.Uint64())
}

这里的关键不是记住某一个路径，而是同时检查名称是否存在、Kind 是否匹配。读取 Float64 或直方图时也遵循同一规则；直接调用错误的取值方法会触发 panic。若采集器需要计算速率，还要参考描述中的 Cumulative 属性，不能把所有数值都按瞬时 gauge 处理。

三、用 expvar 发布业务变量

expvar 解决的是另一类问题：让应用把自己拥有的变量用稳定名字公开。expvar.NewInt、NewFloat 和 NewMap 返回可更新对象，expvar.Publish 也可以注册实现了 Var 接口的自定义值。标准 Handler 会把变量序列化成 JSON，默认入口是 /debug/vars。

package main

import (
	"expvar"
	"net/http"
)

var ordersInFlight = expvar.NewInt("orders.inflight")

func registerVars() {
	// 业务变量由应用维护，命名一旦对外使用就应保持稳定。
	http.Handle("/debug/vars", expvar.Handler())
	ordersInFlight.Add(1)
}

func main() {
	registerVars()
	_ = http.ListenAndServe(":8080", nil) // 示例省略生产环境的超时配置。
}

业务变量的优点是语义直接、版本兼容由你控制；代价是你必须定义更新时机、并发语义和命名规范。生产环境通常会把 /debug/vars 放在受控管理端口，或将 expvar.Do 的结果转换到已有的指标协议，避免把调试入口直接暴露给公网。

四、处理版本差异和兼容降级

runtime/metrics 的集合会随 Go runtime 演进，也可能因不同 Go 实现而不同；官方建议从 All 返回的描述中选择支持项。Go 1.16 的发布说明把它定位为读取运行时实现指标的稳定接口，后续版本还会增加新指标。因此，跨版本采集器应把“指标不存在”设计成明确状态，而不是补一个看似正常的 0。

如果你的程序必须支持较老的 Go 版本，先在构建标签或兼容层隔离 runtime/metrics 的导入；同一套导出名称可以由旧实现继续使用 runtime.ReadMemStats 等旧接口填充，但要在文档里说明字段语义可能不完全相同。expvar 则更适合承载这层统一后的业务名称。

五、落地选择清单

可以按下面的顺序做决定：第一，指标是否由 Go runtime 产生；是，就从 runtime/metrics.All 找名称并按 Kind 读取。第二，指标是否由业务代码更新；是，就用 expvar 类型或自定义 Var。第三，是否要兼容多个 Go 版本；是，就保留能力探测和降级状态。最后再把两类结果交给同一个导出适配器，而不是让一个 API 承担所有职责。

相关问题

runtime/metrics 能直接发布业务指标吗？

不能。它读取 runtime 已定义的名称；业务指标应由 expvar 或你的指标适配层维护。

expvar 能替代 runtime/metrics 吗？

不能完全替代。你可以复制部分结果，但会失去运行时指标的类型、单位和版本描述，也容易产生重复采样。

发现指标名称不存在时应该返回什么？

返回“当前运行时不支持”并记录能力状态，不要把未知指标转成零值继续上报。