Go runtime/metrics 读取不到自定义名称时怎么查版本

如果你把 /app/orders:events 这样的业务名称直接交给 runtime/metrics.Read，读不到并不是“少调用了一次注册函数”，而是 API 职责就不包含自定义指标。runtime/metrics 只读取 Go 运行时已经导出的指标；当前二进制支持哪些名称，要以 metrics.All() 返回的集合为准。

排查顺序很简单：先用 runtime.Version() 记录实际运行版本，再从 metrics.All() 查完整名称和单位；名称不在集合中就不要继续调用 Read，业务指标应放到独立的应用指标采集层。

先确认：runtime/metrics 不是自定义指标注册表

这个包在 Go 1.16 引入，用来以稳定接口读取由 Go runtime 导出的实现定义指标。它没有“注册一个新名称，再让 runtime 负责维护数值”的 API。也就是说，metrics.Read 的任务是采样已有名称，不是创建名称。

名称还必须是完整键，通常包括以斜杠开头的路径和冒号后的单位，例如 /sched/goroutines:goroutines。把路径写对但漏掉单位，或者把某个监控系统导出的名称当成 runtime 名称，同样会得到未知值。

用 runtime.Version 和 metrics.All 判断版本差异

不要先打开某个版本的网页列表，再假设生产二进制一定相同。runtime.Version() 记录的是实际运行时版本，metrics.All() 记录的是这个二进制真正支持的描述集合。两者一起输出，排查“本机有、容器没有”会更直接。

下面的示例故意放入一个不存在的业务名称。它先筛选支持集合，再调用 Read，这样版本缺失和业务自定义不会混在一次采样里：

package main

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

func main() {
    // 记录实际运行时版本，避免把编译环境当成部署环境。
    fmt.Println("Go version:", runtime.Version())

    supported := make(map[string]metrics.Description)
    for _, desc := range metrics.All() {
        // Name 是包含路径和单位的完整指标键。
        supported[desc.Name] = desc
    }

    wanted := []string{
        "/sched/goroutines:goroutines",
        "/app/orders:events", // 业务名称：runtime/metrics 不会替它注册。
    }
    samples := make([]metrics.Sample, 0, len(wanted))
    for _, name := range wanted {
        if _, ok := supported[name]; !ok {
            // 当前版本不支持就跳过，避免把缺失项当成零值。
            fmt.Println("unsupported:", name)
            continue
        }
        samples = append(samples, metrics.Sample{Name: name})
    }

    metrics.Read(samples)
    for _, sample := range samples {
        // KindBad 不应调用 Uint64 或 Float64，否则会误判结果。
        switch sample.Value.Kind() {
        case metrics.KindUint64:
            fmt.Println(sample.Name, sample.Value.Uint64())
        case metrics.KindFloat64:
            fmt.Println(sample.Name, sample.Value.Float64())
        case metrics.KindFloat64Histogram:
            fmt.Println(sample.Name, "histogram")
        default:
            fmt.Println(sample.Name, "unsupported kind")
        }
    }
}

让跨版本采样变成可降级的逻辑

运行时指标集合允许随 Go runtime 演进，也可能因实现不同而不同。因此采集器不要把某个名称写成永远存在的硬编码前提。更稳妥的做法是：启动时建立 All() 索引，按业务真正需要的名称过滤；缺失项打日志或标记为 unavailable，其余指标继续上报。

如果某项指标对功能至关重要，可以把版本差异收窄到构建标签或单独适配层；如果只是观测增强项，就应该允许缺失。尤其不要把“没有这个指标”转换成数值 0，因为 0 和 unavailable 在监控告警里含义完全不同。

业务自定义指标应该放在哪里

例如订单数、缓存命中数、业务耗时等名称属于应用领域，不属于 Go runtime。可以在业务代码中使用独立的指标库维护 Counter、Gauge 或 Histogram，再由现有导出层暴露；runtime/metrics 继续负责 Go 自身的 GC、调度、内存等运行时信息。两类数据可以在监控系统里汇合，但不要在 API 层混为一谈。

最终排查清单只有四项：运行版本是否是部署现场的版本；名称是否来自当前 All()；路径和单位是否完整；业务自定义指标是否走了独立采集器。按这个顺序检查，通常不需要反复改 Read 调用。

相关问题

为什么只写指标路径仍然读不到？

Description.Name 是包含单位的完整键，路径和单位缺一不可；直接从 metrics.All() 复制完整名称最稳妥。

版本升级后某个 runtime 指标消失怎么办？

先记录 runtime.Version() 并重新枚举 metrics.All()，确认是名称变化、实现差异还是采集代码拼写问题，再决定适配或降级。

可以把 KindBad 当作零值上报吗？

不建议。KindBad 表示名称未知，应该记录 unavailable 或跳过，否则监控会把“没有采到”误读成“当前为零”。