Go问答：runtime/metrics读取运行时指标时为什么没有样本怎样完成一个可复用的最小示例

在 Go 服务里接入运行时指标时，最容易遇到的误会是：代码调用了 runtime/metrics.Read，但最后遍历不到任何样本，或者样本的值看起来像“空的”。这通常不是运行时没有指标，而是样本切片没有按指标名初始化，或者把未知指标当成了正常数值。

本文只解决一个具体问题：为什么读取 runtime/metrics 时没有样本，以及怎样写出一个可以放进采集器里的最小读取函数。官方文档地址：https://pkg.go.dev/runtime/metrics

结论很直接：metrics.Read 只负责填充你传入的 []metrics.Sample。切片长度为 0 时不会凭空产生样本；样本名必须是完整的运行时指标名；读完后还要用 Value.Kind() 判断值类型，未知名称会得到 metrics.KindBad。

为什么调用 Read 后仍然没有样本

runtime/metrics 的 API 是“先准备样本，再读取”。metrics.Read(samples) 接收的是调用方已经创建好的切片，它不会像查询接口那样根据空参数自动返回全部指标。下面三种情况要分开判断。

所以，排查时第一眼不要看数值，先看切片长度、每个 Sample.Name 和 Sample.Value.Kind()。这三个字段分别回答“有没有请求样本”“请求了什么”和“运行时返回了哪一种值”。

样本名必须先写进 Sample.Name

一个样本对应一个完整指标名。完整名称通常以斜杠开头，并在冒号后带单位，例如 /memory/classes/heap/free:bytes。只写路径、不写单位，或者把说明文字当成名称，都会导致名称无法匹配。

package main

import (
	"fmt"
	"runtime/metrics"
)

func main() {
	// 切片长度决定本次要读取多少个样本。
	samples := make([]metrics.Sample, 2)

	// Name 必须使用 runtime/metrics 支持的完整名称，包含单位。
	samples[0].Name = "/memory/classes/heap/free:bytes"
	samples[1].Name = "/sched/gomaxprocs:threads"

	// Read 只填充已经准备好的样本，不会改变切片长度。
	metrics.Read(samples)

	// 先输出名称和 Kind，便于区分空切片与未知指标。
	for _, sample := range samples {
		// KindBad 表示名称未知或不受当前运行时支持。
		fmt.Printf("name=%s kind=%v\n", sample.Name, sample.Value.Kind())
	}
}

如果把初始化改成 make([]metrics.Sample, 0)，后面的 range 自然不会执行。这个结果不是“运行时指标为空”，而是调用方没有提交任何待填充的样本。

先用 All 判断名称是否属于当前运行时

如果采集器要兼容不同 Go 版本或不同 Go 实现，不建议把一长串指标名直接当成永远存在。metrics.All() 会返回当前运行时支持的指标描述，其中包含名称、值类型和是否累计等信息。

package main

import (
	"fmt"
	"runtime/metrics"
)

func supportedNames() map[string]metrics.Description {
	// 用官方返回的描述构建白名单，避免把不存在的名称交给 Read。
	supported := make(map[string]metrics.Description)
	for _, desc := range metrics.All() {
		// Name 同时包含指标路径和单位，是 Sample.Name 要使用的键。
		supported[desc.Name] = desc
	}
	return supported
}

func main() {
	// 这个名称故意写成不存在的值，用来展示 KindBad 的处理边界。
	name := "/demo/unknown:value"
	desc, ok := supportedNames()[name]
	if !ok {
		// 未出现在 All 的名称不要继续按正常指标读取。
		fmt.Printf("unsupported metric: %s\n", name)
		return
	}
	fmt.Printf("metric=%s kind=%v cumulative=%t\n", desc.Name, desc.Kind, desc.Cumulative)
}

这一步解决的是“名字是否可用”，不是“当前数值是否大于 0”。一个支持的计数指标刚启动时可能就是 0，但它仍然是有效的 KindUint64 样本；不要把数值为 0 误判成没有样本。

读取后必须按 Value.Kind 分派

metrics.Value 不是一个可以直接转成任意数值的接口。常见返回类型包括无符号整数、浮点数和浮点直方图。指标的 Kind 对同一个指标名是稳定的，但不同指标之间不能共用同一个读取方法。

package main

import (
	"fmt"
	"runtime/metrics"
)

func printSample(sample metrics.Sample) {
	// KindBad 先单独处理，避免对未知指标调用错误的访问方法。
	if sample.Value.Kind() == metrics.KindBad {
		fmt.Printf("skip unsupported metric: %s\n", sample.Name)
		return
	}

	// 不同 Kind 必须调用对应的读取方法；直方图不能当成单个浮点数。
	switch sample.Value.Kind() {
	case metrics.KindUint64:
		fmt.Printf("%s=%d\n", sample.Name, sample.Value.Uint64())
	case metrics.KindFloat64:
		fmt.Printf("%s=%.4f\n", sample.Name, sample.Value.Float64())
	case metrics.KindFloat64Histogram:
		h := sample.Value.Float64Histogram()
		fmt.Printf("%s histogram buckets=%d counts=%d\n", sample.Name, len(h.Buckets), len(h.Counts))
	default:
		// 新 Kind 出现时记录并跳过，避免采集器因扩展而崩溃。
		fmt.Printf("%s unexpected kind=%v\n", sample.Name, sample.Value.Kind())
	}
}

直方图返回的是桶边界和桶计数，不能拿 Float64Histogram() 的结果当成一个数打印。采集系统若要计算分位数，应保留桶结构，并按照自己的指标协议转换。

封装一个可复用的最小读取函数

把“准备切片、填名称、调用 Read、检查 Kind”集中到一个函数里，业务代码就不会因为漏写 Name 而得到空样本。下面的函数保留未知指标的位置，调用方可以据此记录兼容性问题。

package main

import (
	"fmt"
	"runtime/metrics"
)

func readMetrics(names ...string) ([]metrics.Sample, error) {
	// 空名称列表表示调用方没有请求任何指标，提前返回明确错误。
	if len(names) == 0 {
		return nil, fmt.Errorf("at least one metric name is required")
	}

	// 切片长度与名称数量一致，Read 才有可填充的目标。
	samples := make([]metrics.Sample, len(names))
	for i, name := range names {
		// 保留调用方原始名称，便于出错时定位是哪一个指标。
		samples[i].Name = name
	}

	// 只读填充，不修改切片长度；同一批次读取的样本共享一次调用。
	metrics.Read(samples)

	for _, sample := range samples {
		// KindBad 说明名称不在当前运行时支持集合中。
		if sample.Value.Kind() == metrics.KindBad {
			return nil, fmt.Errorf("unsupported metric %q", sample.Name)
		}
	}
	return samples, nil
}

func main() {
	// 选择稳定的标准运行时指标，并保留完整的路径与单位。
	samples, err := readMetrics(
		"/memory/classes/heap/free:bytes",
		"/sched/gomaxprocs:threads",
	)
	if err != nil {
		// 生产采集器可以把错误交给日志或降级逻辑，不要直接丢弃上下文。
		fmt.Println("read runtime metrics:", err)
		return
	}

	for _, sample := range samples {
		// 示例只展示无符号整数；通用采集器应继续按 Kind 分派。
		if sample.Value.Kind() == metrics.KindUint64 {
			fmt.Printf("%s=%d\n", sample.Name, sample.Value.Uint64())
		}
	}
}

这个最小封装适合做成采集器的底层函数，但错误策略要结合业务：如果某个指标只是可选项，可以记录后跳过；如果它是核心健康信号，则应让上层知道当前运行时不支持。

把样本接入运维判断时要注意什么

拿到有效样本后，还要理解指标的语义，尤其是 Description.Cumulative。累计指标适合在两次采样之间计算增量或速率；瞬时值适合直接展示；直方图则需要保留桶信息。不要只因为名字里出现 total 就自行推断语义，优先读取 metrics.All() 返回的描述。

常见误区与最后的排查顺序

1. 先打印 len(samples)，确认调用方确实创建了待填充的元素。
2. 再打印每个 Sample.Name，确认是完整路径和单位，而不是自定义标签。
3. 调用 metrics.All() 对照当前支持列表，区分未知名称与有效但数值为零。
4. 最后检查 Value.Kind()，按类型访问数值或直方图，不要用一个分支处理所有指标。

如果采集器需要长期兼容不同 Go 版本，推荐“固定核心指标 + 启动时检查支持情况”的方式：核心指标缺失时显式告警，可选指标缺失时记录并跳过。这样既不会因一个新增或移除的指标让整个采集链路崩溃，也不会把空切片伪装成正常数据。

相关问题

runtime/metrics 的数值为 0 是没有样本吗？

不是。只要 Value.Kind() 不是 KindBad，数值为 0 仍然是有效样本，常见于刚启动的计数器或当前尚未发生事件的指标。

可以直接把 metrics.All 返回的所有指标都长期上报吗？

可以作为探索或诊断，但生产上要考虑直方图体积、指标集合变化和后端标签数量。更稳妥的做法是读取所需白名单，并在启动或配置变更时检查支持情况。

多个 goroutine 可以同时调用 metrics.Read 吗？

可以，但不同调用的样本切片不能共享底层内存。若无法确认切片是否别名，直接为每次读取创建独立切片更安全。

什么时候应该改用 runtime.ReadMemStats？

如果只需要传统的整体内存统计结构，可以比较 runtime.ReadMemStats；如果希望按运行时定义的指标名选择、读取并兼容扩展，runtime/metrics 更适合。

总结

runtime/metrics 没有样本，第一检查点不是运行时，而是调用方准备的 []metrics.Sample：长度为零就不会有任何结果。随后使用完整指标名填充 Name，用 metrics.All() 判断支持关系，用 Value.Kind() 选择正确的访问方法。把这几步封装起来后，空切片、未知指标、零值和类型不匹配就能被清楚地区分，采集器也更容易在 Go 版本变化时保持可用。