Go runtime/metrics 怎样判断描述符是否支持直方图样本

Go 的 runtime/metrics 可以返回运行时导出的计数、浮点值和直方图。判断一个描述符是否支持直方图样本，关键不是看名称里有没有某个单词，也不是先调用读取方法再猜类型，而是读取 metrics.Description.Kind，将它与 metrics.KindFloat64Histogram 比较。

官方文档：https://pkg.go.dev/runtime/metrics@go1.27.3

结论：先用 metrics.All() 找到目标描述符并确认 Kind，再用同名 metrics.Sample 调用 metrics.Read。读取结果后还要再次检查 Value.Kind()；只有确实是 KindFloat64Histogram，才能调用 Float64Histogram()。

升级时先看 Description.Kind

runtime/metrics 的指标集合可能随 Go 运行时演进，All() 返回当前实现支持的描述符。描述符里的 Name 是指标名，Description 是说明文字，Kind 表示值的形态，Cumulative 表示是否适合按累计值计算速率。判断直方图只需要关注 Kind：

这也是版本迁移中最稳定的判断边界：某个固定指标的 kind 不应在原名称下悄悄改变；如果值的类型必须改变，运行时会引入新的指标名和 kind。指标是否存在则仍要通过当前实现的描述符集合确认。

用 All 建立直方图描述符索引

如果采集器要兼容多个 Go 版本，可以在初始化阶段扫描 All()，只记录 kind 为直方图的名称。这样既不会依赖某个版本的完整指标清单，也不会把“单位看起来像分布”误判成直方图。

package main

import (
	"fmt"
	"runtime/metrics"
)

func histogramNames() map[string]metrics.Description {
	result := make(map[string]metrics.Description)
	for _, desc := range metrics.All() {
		// 只按官方描述的 Kind 过滤，不用名称后缀猜测类型。
		if desc.Kind == metrics.KindFloat64Histogram {
			result[desc.Name] = desc
		}
	}
	return result
}

func main() {
	for name, desc := range histogramNames() {
		// 保留描述文字，便于采集器输出可读的指标目录。
		fmt.Printf("%s: %s\n", name, desc.Description)
	}
}

这里返回描述符而不是只返回字符串，是为了同时保留 Cumulative 等元数据。若目标名称不在这个索引中，应该把它当作当前运行时不支持，而不是继续调用直方图读取方法。

读取样本前后都检查 Kind

描述符索引解决的是“目标是否被当前运行时声明支持”，真正读取时还要让 Sample.Name 与目标名对应，并检查结果。未知名称经过 Read 后会得到 KindBad；而 Float64Histogram() 在值不是直方图时会 panic，因此不能省略判断。

package main

import (
	"fmt"
	"runtime/metrics"
)

func readHistogram(name string) (*metrics.Float64Histogram, bool) {
	// 先确认当前运行时的描述符声明了直方图类型。
	wanted := false
	for _, desc := range metrics.All() {
		if desc.Name == name {
			wanted = desc.Kind == metrics.KindFloat64Histogram
			break
		}
	}
	if !wanted {
		return nil, false
	}

	samples := []metrics.Sample{{Name: name}}
	// Read 会填充 Value；名称不受支持时 Value.Kind() 会是 KindBad。
	metrics.Read(samples)
	if samples[0].Value.Kind() != metrics.KindFloat64Histogram {
		return nil, false
	}
	return samples[0].Value.Float64Histogram(), true
}

func main() {
	const name = "/sched/pauses/total/gc:seconds"
	histogram, ok := readHistogram(name)
	if !ok {
		fmt.Println("当前运行时不提供直方图样本")
		return
	}
	// Counts[i] 对应 [Buckets[i], Buckets[i+1]) 这个桶的样本权重。
	fmt.Printf("buckets=%d counts=%d\n", len(histogram.Buckets), len(histogram.Counts))
}

Float64Histogram 中，Buckets 是递增的边界，Counts 保存每个区间的权重；正常情况下 len(Counts) == len(Buckets)-1。最小边界可为负无穷，最大边界可为正无穷，所以统计区间时不要把两端强行当成有限值。

迁移清单：指标集合会变，kind 判断不能省

从旧的硬编码采集器迁移到 runtime/metrics 时，可以按下面的顺序收敛风险：

1. 启动时从 All() 建立支持表，把名称存在性和 Kind 分开记录。
2. 只为直方图名称创建 Sample，读取后再次检查 Value.Kind()。
3. 把 Buckets 看成只读边界；文档保证同一指标在进程退出前不会改变，但底层切片可能与其他直方图别名。
4. 如果跨 goroutine 处理结果，先深拷贝 Buckets 和 Counts，不要在另一次 Read 进行时继续使用可能被复用的值。

最容易出现的误区有三个：把指标单位中的 seconds 当成直方图证据；对 KindBad 直接调用读取方法；以及把一次读取得到的直方图指针长期缓存并自行修改。它们分别混淆了命名、类型和存储生命周期。

常见问题

只知道指标名称时，能直接调用 Float64Histogram 吗？

不建议。先从 All() 找到对应描述符，再检查 Description.Kind；调用 Read 后仍要检查 Value.Kind()。

为什么直方图有一个 Buckets 却少一个 Counts？

相邻两个边界定义一个区间，Counts[i] 对应 [Buckets[i], Buckets[i+1])，所以边界数量比桶数量多一个。

读取后能否直接改 Buckets？

不应直接修改。官方文档允许多个直方图共享边界切片；需要自己的边界时复制切片，再在业务侧保存副本。