Go问答：runtime/metrics读取运行时指标时为什么没有样本为什么结果为空或不符合预期

用 runtime/metrics 读取运行时指标时，结果为空不一定是 Go 运行时没有数据。最常见的原因是传入了空的 []metrics.Sample、指标名少了单位、指标在当前实现中不存在，或者把直方图的零样本误当成读取失败。

官方地址：https://pkg.go.dev/runtime/metrics

Go runtime/metrics 没有样本通常先看 Sample 切片和指标名

metrics.Read 没有“返回样本列表”这一步，它只修改调用方提供的 Sample。下面这段代码把一个完整的指标名称放进切片，再读取它的类型和值：

package main

import (
	"fmt"
	"runtime/metrics"
)

func main() {
	// 指标名必须包含路径和单位，不能只写“heap/free”。
	samples := []metrics.Sample{{Name: "/memory/classes/heap/free:bytes"}}
	// Read 会把结果写回 samples[0].Value。
	metrics.Read(samples)

	// 先判断 Kind，再调用对应的取值方法，避免类型不匹配导致 panic。
	switch samples[0].Value.Kind() {
	case metrics.KindUint64:
		fmt.Printf("free=%d bytes\n", samples[0].Value.Uint64())
	case metrics.KindBad:
		fmt.Println("metric is not supported")
	default:
		fmt.Printf("unexpected kind=%v\n", samples[0].Value.Kind())
	}
}

如果写成 make([]metrics.Sample, 0)，再调用 Read，函数会直接返回；如果只写了路径而遗漏 :bytes，名称也不会匹配当前的指标描述。排查时先打印 Sample 的 Name 和 Kind，不要先猜数值是不是零。

用 All 和 KindBad 区分空读、错名与不支持

官方建议通过 metrics.All() 获取当前实现支持的名称。运行时指标集合会随实现演进，硬编码关键指标时尤其要保留降级分支。

func readMetric(name string) (metrics.Value, bool) {
	// 用 All 建立支持集合，避免把拼写错误当成“没有样本”。
	supported := make(map[string]struct{}, len(metrics.All()))
	for _, desc := range metrics.All() {
		supported[desc.Name] = struct{}{}
	}
	if _, ok := supported[name]; !ok {
		return metrics.Value{}, false
	}

	// 一个 Sample 对应一个明确的指标名称。
	sample := []metrics.Sample{{Name: name}}
	metrics.Read(sample)
	if sample[0].Value.Kind() == metrics.KindBad {
		// 运行时实现变化时走降级路径，而不是调用错误的取值方法。
		return metrics.Value{}, false
	}
	return sample[0].Value, true
}

这里的两次判断各有作用：All 适合在启动时查看当前可用集合，KindBad 是对单次读取结果的最后保护。真正使用时还要记录指标类型，不能只凭名称决定调用 Uint64 还是 Float64。

数值、直方图和复用切片要分别处理

标量指标可以直接读取对应的 Uint64 或 Float64。直方图返回的是 *metrics.Float64Histogram：Buckets 是边界，Counts 是各桶计数，二者长度相差一。判断“有没有样本”应累加 Counts，而不是只检查指针是否为空。

func histogramSamples(v metrics.Value) uint64 {
	// 只有确认是直方图后才能取出其内部结构。
	if v.Kind() != metrics.KindFloat64Histogram {
		return 0
	}
	h := v.Float64Histogram()
	var total uint64
	for _, count := range h.Counts {
		// Counts 的总和表示当前直方图记录的样本数。
		total += count
	}
	return total
}

另外，复用同一组 Sample 可以减少分配，但不能在一次 Read 尚未完成时并发读取或修改其中的 Value；并发调用要使用不共享底层数组的切片。监控采集器通常按固定周期串行复用一组 Sample，就能同时获得稳定语义和较低开销。

部署前的兼容性检查清单

• 指标名是否来自 metrics.All()，并保留冒号后的单位。
• 是否在取值前检查 Value.Kind()，对 KindBad 有降级策略。
• 是否区分“没有读取对象”和“读取值为零”。
• 直方图是否按 Counts 总和判断样本量，并保留桶边界。
• 周期采集是否避免跨 goroutine 共享同一组 Sample。

把这五项放进采集器的启动日志和单元测试后，runtime/metrics 的空结果就能从“神秘异常”变成可分类的兼容性状态。

常见问题

为什么调用 metrics.Read 后 Value 还是默认状态？

先确认切片长度大于零且每个 Sample 已设置 Name。空切片没有可写入的位置，Read 会直接返回。

KindBad 是否表示 Go 运行时坏了？

通常不是。它表示该名称没有出现在当前实现支持的指标集合中，常见原因是拼写、单位缺失或跨实现差异。

直方图 Counts 为零需要重试吗？

不需要立即重试。它可能准确表示采样期间没有对应事件；只有名称未知或 Kind 不符合预期时，才应回到指标选择和兼容性检查。