Go Ristretto 怎么开启指标并计算缓存命中比例

我第一次给 Ristretto 加命中率监控时，真正容易混淆的不是公式，而是“指标开关”和“缓存读写”之间的边界：缓存能正常工作，并不代表它已经在记录 Hits 和 Misses。Ristretto v2 需要在创建缓存时把 Config.Metrics 设为 true，之后再从 cache.Metrics 读取统计。

官方地址：https://github.com/dgraph-io/ristretto/

本文只围绕 Go Ristretto 开启指标、读取命中次数和计算缓存命中比例。官方文档把 Ratio() 定义为 Hits 除以 Hits 与 Misses 之和；如果没有任何 Get 访问，比例没有业务解释，不能把它当成“命中率为零”的结论。

我先确认指标到底记录什么

Ristretto v2 的 Config.Metrics 是创建缓存时的开关。它打开后，缓存实例会保留统计数据，cache.Metrics 提供 Hits()、Misses() 和 Ratio() 等方法。这里的命中率只回答 Get 请求是否找到对应键，不等同于 Set 请求是否最终留下了条目。

这一区分对排查很有用：如果指标一直没有变化，先看 Metrics 是否开启；如果 Misses 很高，再看访问键是否稳定、条目是否过期或容量策略是否符合预期。不要把一次 Set 的返回值直接当成“之后一定能 Get 到”。

最小配方：创建时打开 Metrics

我现在会把指标开关和缓存生命周期一起写在初始化代码里。这样后续读取 cache.Metrics 时不会依赖某个隐藏配置，也能在程序退出时及时关闭 Ristretto 的后台资源。

package main

import (
    "fmt"

    "github.com/dgraph-io/ristretto/v2"
)

func main() {
    cache, err := ristretto.NewCache[string, string](&ristretto.Config[string, string]{
        NumCounters: 10_000, // 为访问频率保留计数器，按缓存规模调整
        MaxCost:     1_000,   // 这里把每个条目的 cost 约定为 1
        BufferItems: 64,      // 使用默认级别的缓冲容量，减少并发争用
        Metrics:     true,    // 开启 Hits、Misses 和 Ratio 等运行时指标
    })
    if err != nil {
        panic(err) // 配置不合法时不要继续使用未创建成功的缓存
    }
    defer cache.Close() // 程序退出前停止 Ristretto 的后台协程和通道

    cache.Set("user:1", "Alice", 1) // 写入一个代价为 1 的缓存条目
    cache.Wait()                     // 等待缓冲写入应用后再读取，避免观察到旧状态

    if value, ok := cache.Get("user:1"); ok {
        fmt.Println(value) // 这次 Get 会计为一次命中
    }
    _, _ = cache.Get("user:404") // 未找到的键会计为一次未命中

    fmt.Printf("hits=%d misses=%d ratio=%.2f\\n",
        cache.Metrics.Hits(),   // 读取累计命中次数
        cache.Metrics.Misses(), // 读取累计未命中次数
        cache.Metrics.Ratio(),  // 读取 Hits/(Hits+Misses) 的比例
    )
}

这段配方里最关键的只有三处：Metrics: true 决定是否保留统计，Wait() 保证已提交的缓冲写入对后续 Get 可见，cache.Metrics 是读取累计数据的入口。示例没有把固定数字写成生产结论，真实比例要以你的访问样本为准。

Ratio 和手工公式应该怎样对照

我在日志或监控适配层通常同时保留 Hits、Misses 和 Ratio。Ratio 适合直接展示，Hits 与 Misses 则能帮助判断样本量和问题方向。它们的关系可以写成：

命中比例 = Hits / (Hits + Misses)

例如一段采样期内读到 80 次命中、20 次未命中，比例是 0.8，也就是 80%。如果只有 1 次 Get 且命中，比例会是 100%，但样本量太小，不能据此判断缓存设计已经稳定。

func printCacheRatio(cache *ristretto.Cache[string, string]) {
    hits := cache.Metrics.Hits()   // 读取当前缓存实例的累计命中数
    misses := cache.Metrics.Misses() // 读取当前缓存实例的累计未命中数
    total := hits + misses
    if total == 0 {
        fmt.Println("暂无 Get 样本") // 没有访问时不输出误导性的百分比
        return
    }

    ratio := float64(hits) / float64(total) // 与 Metrics.Ratio() 的定义保持一致
    fmt.Printf("命中比例=%.2f%%，样本数=%d\\n", ratio*100, total)
}

手工公式主要用于把指标送入自定义监控系统，平时可以直接使用 Ratio()。如果两者读数不同，先确认是不是跨越了不同采样时刻，或者在并发请求中分别读取了不同的指标快照。

几个我实际会避开的坑

只设置了 Metrics，却没有产生 Get 样本

打开指标不会自动生成访问数据。只有真正调用 Get，Hits 或 Misses 才有可解释的变化。启动时打印一次 Ratio，通常只能得到空样本状态，不要当成业务缓存命中率。

把 Set 返回 true 当成永久命中保证

Ristretto 的 Set 经过缓冲和准入策略。官方说明指出，新条目可能在缓冲或准入阶段被丢弃，而已有条目的更新语义又不同。因此命中率采样应围绕实际 Get 结果建立，不要只统计 Set 成功次数。

忘记 Metrics 本身有成本

官方配置说明提醒，保留统计会带来开销。开发和压测阶段可以打开它观察数据；对吞吐特别敏感的路径，要把统计成本纳入基准和部署配置，而不是无条件永久开启。

用一个实例的累计值比较所有时间窗口

Hits()、Misses() 和 Ratio() 是当前缓存实例生命周期内的统计。若要做分钟级看板，应在采集端保存前后两次计数并计算增量，或者按业务边界重建实例；不要把累计比例误读成最近一分钟的比例。

最后留下的最小监控写法

如果你的目标只是得到一个可信的 Ristretto 命中比例，可以记住这一张配方卡：

我自己的判断是：Ristretto 指标最适合回答“这段真实 Get 流量命中了多少”，不适合代替缓存容量、淘汰原因和业务新鲜度分析。先把 Metrics 开启、样本边界和累计口径写清楚，再决定是否接入定时上报，通常比一开始堆更多指标更稳。

相关问题

• Ristretto 的 Ratio 为什么一直是 0？ 常见原因是 Metrics 没有开启，或者当前实例还没有产生 Get 样本。
• 调用 Set 后要不要立刻 Wait？ 如果后续代码必须马上通过 Get 观察到这次写入，可以调用 Wait；异步写入场景则应明确接受可见性延迟。
• 命中比例能代表缓存性能吗？ 不能单独代表。它反映 Get 的命中情况，还应结合请求延迟、条目成本和采样窗口判断。