Go runtime/metrics 怎样筛选支持的指标描述

如果采集器直接写死一串 runtime 指标名称，换 Go 版本或换实现后很容易遇到“读不到”或类型不匹配。更稳妥的做法是先调用 metrics.All() 获取当前运行时支持的 []metrics.Description，再按名称、描述和类型筛选。All 返回的是能力目录，筛选结果才是本次要创建的 Sample。

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

为什么要先看 All 返回的 Description

runtime/metrics 的指标用字符串名称标识，名称通常由路径和单位组成，例如 /memory/classes/heap/free:bytes。Go 官方文档明确建议通过 All 获取支持指标，以适应运行时指标集合随实现演进而变化的情况。

metrics.Description 里最适合做筛选的字段有四个：Name 是完整指标名，Description 是英文说明，Kind 是值类型，Cumulative 表示单值或直方图桶是否按累计量增长。它们共同回答“这个指标是什么、能不能被当前采集器理解、是否适合算速率”。

按名称和描述筛选支持的指标

实际项目通常先按名称前缀缩小范围，再用描述关键词做人工可读的补充筛选。下面的函数只处理当前运行时真实返回的目录，不依赖某个版本的固定指标数量。

package main

import (
	"fmt"
	"strings"
	"runtime/metrics"
)

func findMetrics(prefix, keyword string) []metrics.Description {
	var result []metrics.Description
	for _, desc := range metrics.All() {
		// 名称筛选保留单位后缀，避免把不同单位误合并。
		if prefix != "" && !strings.HasPrefix(desc.Name, prefix) {
			continue
		}
		// Description 是英文说明，只把它作为补充条件，不替代 Name 判断。
		if keyword != "" && !strings.Contains(strings.ToLower(desc.Description), strings.ToLower(keyword)) {
			continue
		}
		result = append(result, desc)
	}
	return result
}

func main() {
	for _, desc := range findMetrics("/memory/classes/", "memory") {
		// 先打印目录信息，后续再决定是否创建 Sample。
		fmt.Printf("%s kind=%v cumulative=%t\\n", desc.Name, desc.Kind, desc.Cumulative)
	}
}

这里的边界是“筛选支持的描述”，不是读取指标值。All() 返回的切片可能为空，或者在不同 Go 实现中出现不同集合；因此不要把数组下标、固定总数和某个指标一定存在写进业务逻辑。

用 Kind 和 Cumulative 再筛一遍

如果采集器只支持整数计数，可以在名称筛选后保留 KindUint64；如果要计算变化速率，再优先选择 Cumulative 为 true 的指标。直方图不是一个普通浮点数，不能直接调用 Float64()。

func selectReadable(descs []metrics.Description, allowHistogram bool) []metrics.Description {
	selected := make([]metrics.Description, 0, len(descs))
	for _, desc := range descs {
		// 当前采集器按 ValueKind 白名单取值，未知类型先跳过。
		readable := desc.Kind == metrics.KindUint64 || desc.Kind == metrics.KindFloat64
		if allowHistogram && desc.Kind == metrics.KindFloat64Histogram {
			readable = true
		}
		if !readable {
			continue
		}
		// 累计指标适合在相邻采样之间计算增量或速率。
		if !desc.Cumulative {
			continue
		}
		selected = append(selected, desc)
	}
	return selected
}

Cumulative 不是“值越大越好”的标记，而是告诉你是否可以把相邻采样看成累计量来计算速率。对非累计指标，保留它们也有意义，但应按当前值解释，不能套用累计量公式。

筛选结果如何变成可读取的 Sample

选出描述后，把每个 Name 放进 metrics.Sample，再调用 metrics.Read。读取时一定根据 Value.Kind() 分支，否则对错误类型调用取值方法会触发 panic。

func readSelected(descs []metrics.Description) {
	if len(descs) == 0 {
		// 没有匹配项时直接结束，避免创建无意义的空采样请求。
		return
	}

	samples := make([]metrics.Sample, len(descs))
	for i, desc := range descs {
		// Sample.Name 必须来自 All 返回的支持目录。
		samples[i].Name = desc.Name
	}
	metrics.Read(samples)

	for _, sample := range samples {
		switch sample.Value.Kind() {
		case metrics.KindUint64:
			fmt.Printf("%s=%d\\n", sample.Name, sample.Value.Uint64())
		case metrics.KindFloat64:
			fmt.Printf("%s=%f\\n", sample.Name, sample.Value.Float64())
		case metrics.KindFloat64Histogram:
			// 直方图需要读取 Buckets 和 Counts，不能当成单个浮点数。
			hist := sample.Value.Float64Histogram()
			fmt.Printf("%s buckets=%d\\n", sample.Name, len(hist.Buckets))
		case metrics.KindBad:
			// 名称不在支持目录或实现发生变化时，不读取具体值。
			fmt.Printf("%s is unsupported\\n", sample.Name)
		}
	}
}

跨 Go 版本时要留意哪些边界

最重要的兼容策略是“动态发现、按能力读取”。指标集合可能演进，不同 Go 实现之间也可能不完全相交；因此把固定名称作为硬编码采集清单，会让程序在新旧环境中出现空值或 KindBad。如果某个关键指标必须存在，再把缺失视为配置错误，并配合构建标签或明确的版本策略处理。

常见问题

为什么不直接维护一份固定指标名称列表？

因为 runtime/metrics 的支持集合会随运行时实现演进，固定列表只能代表某个环境。先用 All() 发现，再按字段筛选，兼容性更好。

KindBad 是不是说明指标值为零？

不是。KindBad 表示该名称没有得到可用的指标类型，应该把它当成“不支持或名称失效”处理，而不是当作数值零。

筛选时只看 Name 够不够？

不一定。Kind 决定读取方式，Cumulative 决定是否适合算速率，Description 则帮助你避免只凭路径名称误选指标。