Go runtime/metrics 样本值类型变化时怎样避免解析崩溃

我在给运行时指标采集器加新指标时，最容易踩到的坑不是指标数值变了，而是读取代码把“当前能看到的样本类型”写死了：默认每个值都是 uint64，或者拿到一个不熟悉的指标名后仍然直接调用某个访问器。这样一来，升级 Go、换运行时实现或遇到未支持的指标时，采集器可能先于业务逻辑崩溃。

更稳妥的做法是把类型当作契约读取：先用 metrics.All() 获取描述，再用 Value.Kind() 做运行时分派，只有类型匹配时才调用 Uint64()、Float64() 或 Float64Histogram()。官方文档保证同一个指标名的 kind 不会静默改变；如果语义必须换类型，应当出现新的指标名。真正要防的是指标集合演进、未知指标和读取器对新类型的误判。

官方资料：https://pkg.go.dev/runtime/metrics

先分清“同名类型变化”和“指标集合演进”

runtime/metrics 的指标不是一个永远固定的结构体字段，而是由字符串名称和 Description 描述的集合。Description.Kind 说明该名称对应的值类型，Cumulative 则说明它是否适合计算速率。

官方契约对兼容性很重要：给定指标名的 kind 保证不会改变；如果必须改变，运行时会引入新的指标名和新的 kind。因此不要把标题里的“类型变化”理解成同名指标会悄悄从 uint64 变成直方图。工程上更常见的是以下三种情况：

• 采集器请求了当前运行时不存在的名称，结果是 KindBad。
• 新 Go 版本增加了指标或增加了读取器尚未覆盖的类型。
• 代码只检查名称，不检查值的 kind，误用了访问器。

我会把第一类和第二类记录为兼容事件，把第三类视为采集器缺陷。这个分类能避免把一次正常的运行时演进误报成业务故障。

先按 Kind 分派，再调用对应访问器

访问器本身带有明确的前置条件：Value.Uint64() 只接受 KindUint64，Float64() 只接受 KindFloat64，直方图访问器只接受 KindFloat64Histogram。不满足条件时，访问器会 panic，所以判断必须放在访问器之前。

下面这个读取函数只展示类型路由，不把任何一个指标假设成固定标量。遇到未知类型时返回一个可记录的错误，调用方可以选择跳过单项而保住整批采集。

package metricsreader

import (
    "fmt"
    "runtime/metrics"
)

// ReadValue 只在 Value.Kind 与访问器匹配时读取，避免错误访问器触发 panic。
func ReadValue(sample metrics.Sample) (any, error) {
    // KindBad 通常表示名称在当前运行时中不存在。
    switch kind := sample.Value.Kind(); kind {
    case metrics.KindBad:
        return nil, fmt.Errorf("metric %q is unsupported", sample.Name)
    case metrics.KindUint64:
        // 只有匹配 KindUint64 才能调用 Uint64。
        return sample.Value.Uint64(), nil
    case metrics.KindFloat64:
        // 浮点指标由 Float64 读取，不能复用 uint64 分支。
        return sample.Value.Float64(), nil
    case metrics.KindFloat64Histogram:
        // 直方图返回指针；异步保存前需要深拷贝其内容。
        return sample.Value.Float64Histogram(), nil
    default:
        // 新增 Kind 不应让整批采集崩溃，先保留兼容信号。
        return nil, fmt.Errorf("metric %q has unsupported kind %v", sample.Name, kind)
    }
}

这里的 default 不是为了掩盖错误，而是为了让“运行时增加了读取器不认识的类型”变成可观察事件。若采集器对某个指标有硬依赖，可以在上层把这类错误升级为告警；对可选指标，则跳过并继续处理其它样本。

用 All 建立名称和类型的允许集合

只维护一张手写名称列表，仍然无法判断指标是否存在。更稳的方式是启动或配置变更时遍历 metrics.All()，构建名称到 Description 的映射；采样时只请求实际存在的名称，并把描述里的 kind 保存下来。

package metricsreader

import "runtime/metrics"

// Registry 保存当前运行时公开的指标描述，作为采样器的兼容基线。
type Registry map[string]metrics.Description

// BuildRegistry 从运行时的完整描述表建立名称索引。
func BuildRegistry() Registry {
    registry := make(Registry)
    for _, desc := range metrics.All() {
        // 名称是稳定索引；描述中的 Kind 是后续分派的契约。
        registry[desc.Name] = desc
    }
    return registry
}

// SupportedSamples 过滤掉当前运行时不存在的指标名。
func (r Registry) SupportedSamples(names []string) ([]metrics.Sample, []string) {
    samples := make([]metrics.Sample, 0, len(names))
    missing := make([]string, 0)
    for _, name := range names {
        // 先查描述表，避免把未知名称交给 Read 后才得到 KindBad。
        if _, ok := r[name]; !ok {
            missing = append(missing, name)
            continue
        }
        samples = append(samples, metrics.Sample{Name: name})
    }
    return samples, missing
}

这个索引并不意味着要把所有指标都采集。更实用的做法是保留自己的白名单，再用官方描述表过滤它。这样升级 Go 后，新指标会自然出现在描述表中，但不会未经评估就进入业务指标；白名单里的旧指标如果缺失，则明确记录兼容信号。

采样后再核对描述和实际 Value.Kind

在正常的官方运行时里，同名指标的描述 kind 和采样值 kind 应当一致。把这次核对写出来有两个好处：代码意图更清楚，未来遇到非标准实现、错误注入或采集器数据串线时，也能把问题定位在边界处。

package metricsreader

import (
    "fmt"
    "runtime/metrics"
)

// ReadKnown 在读取前后都核对类型，返回单项错误而不是让批次 panic。
func (r Registry) ReadKnown(samples []metrics.Sample) map[string]any {
    metrics.Read(samples)
    values := make(map[string]any, len(samples))
    for _, sample := range samples {
        desc, ok := r[sample.Name]
        if !ok {
            // 这说明注册表与采样列表不同步，按未知指标处理。
            continue
        }
        if sample.Value.Kind() != desc.Kind {
            // 不要在类型不符时调用任何标量或直方图访问器。
            _ = fmt.Sprintf("metric %q kind mismatch: want %v, got %v", sample.Name, desc.Kind, sample.Value.Kind())
            continue
        }
        value, err := ReadValue(sample)
        if err != nil {
            // 单个指标失败时保留其它指标，错误交给调用方日志系统。
            continue
        }
        values[sample.Name] = value
    }
    return values
}

示例里用 fmt.Sprintf 占位展示了错误生成位置；真实项目应把错误送到结构化日志或返回给调用方，而不是像示例一样丢弃。关键顺序只有一个：先比对 kind，再进入访问器。

直方图和复用切片要一起考虑

metrics.Read 可以复用同一个 []metrics.Sample，但在一次 Read 仍未结束时，不能读取或修改其中的 Value。这个限制同样适用于 Float64Histogram 返回的指针：运行时可能复用底层存储。

如果采集器要把结果交给异步上报队列，就不要直接把直方图指针塞进队列。应在当前读取阶段复制 Buckets 和 Counts，并把需要的累计属性一并转换为自己的数据结构。标量可以直接复制值，但也要先完成 kind 分派。

package metricsreader

import "runtime/metrics"

// HistogramCopy 是脱离 runtime/metrics 底层复用存储的快照。
type HistogramCopy struct {
    Buckets []float64
    Counts  []uint64
}

// CopyHistogram 在 Read 返回后立即深拷贝直方图切片。
func CopyHistogram(h *metrics.Float64Histogram) HistogramCopy {
    // 复制切片，避免下一次 Read 覆盖异步上报仍在使用的数据。
    buckets := append([]float64(nil), h.Buckets...)
    counts := append([]uint64(nil), h.Counts...)
    return HistogramCopy{Buckets: buckets, Counts: counts}
}

把版本差异转成可观察信号

兼容处理的最后一步是区分“可选指标缺失”“出现未覆盖的新类型”和“代码内部类型不一致”。三者都不应该直接让整个进程退出，但严重级别可以不同：可选指标缺失通常是 debug 或 info，新类型应进入升级观察清单，白名单中的关键指标缺失则应触发告警。

我通常会给每条兼容事件带上指标名、期望 kind、实际 kind、Go 版本和采集器版本。这样升级后看到“某指标消失”时，不会把它和访问器 panic 混成一个故障。也不要把官方“同名 kind 不变”的保证误写成“所有版本的指标集合完全相同”。

上线前我会保留的最小检查清单

• 是否从 metrics.All() 或等价描述表确认名称，而不是假设所有 Go 版本都有同一组指标？
• 是否在每个访问器前检查了 Value.Kind()？
• 是否把 KindBad 当作可处理的兼容结果，而不是直接 panic？
• 是否为未知 kind 留了默认分支和结构化日志字段？
• 是否在异步使用直方图前复制了 Buckets 与 Counts？
• 升级 Go 后，是否能从日志区分“指标缺失”“类型未覆盖”和“采集器注册表不一致”？

如果只记住一句话：runtime/metrics 的兼容策略不是把所有样本都转换成一个类型，而是让指标描述、实际 kind、访问器和错误出口彼此对齐。这样同名指标的稳定契约可以被利用，指标集合的变化也不会变成一次无提示的进程崩溃。

相关问题

同一个 runtime/metrics 名称会突然从 uint64 变成 histogram 吗？

按官方兼容契约不会静默改变；如果必须改变，应使用新的指标名称和新的 kind。读取器仍应按 kind 分派，因为指标集合会演进。

为什么请求不存在的指标后没有返回 error？

metrics.Read 会把未知名称对应的值标成 KindBad，调用方需要检查 Value.Kind()，不能直接调用某个访问器。

直方图只读不写，为什么还要复制？

因为底层存储可能在后续 Read 时复用。异步上报需要自己的快照，不能长期持有运行时返回的指针。