Valkey 如何用 HOTKEYS 命令发现并观察高 QPS 热点 key？-编程实验室

Valkey 如何用 HOTKEYS 命令发现并观察高 QPS 热点 key？

【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv

当某个 key 的访问量远高于其他 key 时，它会把压力集中在单分片上。Valkey 的HOTKEYS命令（9.2.0 起提供）会对客户端的 key 访问做采样，并按窗口统计出访问最频繁的 key 及其估算 QPS，让你用一条命令就能回答“最近一个窗口里哪些 key 最热”。

热点检测默认关闭，不消耗任何资源。因此完整路径是：先用三个配置项开启检测，再用HOTKEYS GET读取热点列表、用INFO hotkeys判断报告的可信度，最后用HOTKEYS RESET清理统计状态。这些配置项和窗口语义见 valkey.conf 的 “HOT KEY DETECTION” 章节。

开启检测：hotkeys-top-k、采样比例与窗口长度

valkey.conf中提供三个配置项，控制检测的开关、开销与精度：

hotkeys-top-k（默认0）：要跟踪的最热 key 数量，同时充当开关。0完全禁用检测；任意正值启用检测，并决定 Space-Saving 算法的容量。预期热点较多、想要更长的排名列表时调大它。
hotkeys-sampling-percentage（默认1）：采样百分比，取值 1–100，100表示每次访问都采样。调低可减小高吞吐服务器上的开销，代价是精度下降。
hotkeys-window-seconds（默认1）：报告窗口长度（秒）。访问先累积在“进行中”的 live window 里，HOTKEYS GET报告的是最近一个已完成（冻结）的窗口。

三个配置都支持运行期通过CONFIG SET修改，无需重启。修改后进行中的窗口会重新计数，但最近一个已完成窗口及其产生时的配置会保留，仍在执行的HOTKEYS GET依然能读到它：

valkey-cli config set hotkeys-top-k 16 valkey-cli config set hotkeys-sampling-percentage 100 valkey-cli config set hotkeys-window-seconds 1

用下面的命令确认开关已生效（配置回读值为16）：

valkey-cli config get hotkeys-top-k

采样比例和窗口长度要配合选择，二者共同决定报告的量化步长：最小可报告的非零速率约为100 / (采样百分比 × 窗口秒数)QPS，某个 key 在一个窗口内的期望采样数为qps × 采样百分比 / 100 × 窗口秒数。按默认值（1%、1s），每个报告值都是 100 QPS 的整数倍，只有大约 10k QPS 以上的 key 才有可信的数字。要分辨更低速率的 key，应提高采样百分比和/或加长窗口。

读取热点列表：HOTKEYS GET

valkey-cli hotkeys get

HOTKEYS GET返回最近一个已完成窗口内最热的 key，按估算 QPS 降序排列，复杂度为 O(N)（N 为历史中的热 key 数量）。每个条目是三个字段组成的 map（字段定义见 src/commands/hotkeys-get.json）：

key：key 名称（string）；
db：key 被访问时所在的数据库 id（integer）；
qps：该 key 在最近完成窗口内的每秒访问估算值（integer）。

文档示例（数值仅为格式示意，不是固定预期）：

1) 1) "key" 2) "hot_read_key" 3) "db" 4) (integer) 0 5) "qps" 6) (integer) 21500 2) 1) "key" 2) "hot_write_key" 3) "db" 4) (integer) 0 5) "qps" 6) (integer) 12000

两个直接影响使用方式的行为：

报告的是已完成窗口，不是当前窗口。制造流量后窗口尚未冻结时结果可能为空，需要轮询几次HOTKEYS GET直到结果非空，这正是单元测试 tests/unit/hotkeys.tcl 验证“通过重复访问生成热点 key”的方式：先hotkeys reset，对目标 key 做数百次GET/SET，然后轮询hotkeys get直到非空。读和写共用同一条目，同一个 key 只会出现一次，不按访问类型拆分。
检测关闭时返回空数组而不是报错（与SLOWLOG GET行为一致），轮询方无需匹配错误字符串来区分“未启用”和“没有热点”。

此外，如果服务器停顿到未完成窗口覆盖的时间超过hotkeys-window-seconds的两倍，该窗口的计数会被丢弃（避免把长期平均当成单窗口报告），HOTKEYS GET在下一个窗口完成前返回空结果。

判断报告可信度：INFO hotkeys

INFO hotkeys提供两个字段，帮助判断HOTKEYS GET的结果能信到什么程度：

valkey-cli info hotkeys

hotkeys_last_window_samples：最近完成窗口内的采样观测数 N。Space-Saving 的保证是相对于 N 表述的——只有频率高于 N/K 的 key 才被保证跟踪。用它评估检测下限：N 很小时，排名靠后的条目可信度有限。
hotkeys_last_window_duration_ms：最近完成窗口的实际跨度。窗口由服务器周期任务关闭，因此实际跨度比配置值多一段很小的轮转延迟；报告的 QPS 除以的是实测跨度而非配置长度，这段延迟不会抬高数字。

检测刚启用或刚RESET后还没有完成窗口，该字段为 0，此时HOTKEYS GET也是空结果。

清理统计状态：HOTKEYS RESET 与自动清理

valkey-cli hotkeys reset

HOTKEYS RESET清空所有热点统计与历史，返回OK；随后HOTKEYS GET返回空数组（单元测试对这两个行为均有断言）。

除手动 RESET 外，任何会丢弃整个数据库或 slot 范围的操作也会清空热点状态：FLUSHDB、FLUSHALL、清空数据集的全量同步或 RDB 重载、cluster reset、丢弃 slot。而普通的 key 访问和删除会被当作更新计入：DEL、UNLINK算作一次访问，key 过期和逐出不会清空其状态。

边界行为与限制

以下行为来自 valkey.conf 的说明与 src/hotkeys.c 的实现注释，观察结果前值得了解：

只统计真实客户端流量。记录只发生在客户端真正执行命令时；复制链路、AOF、RDB/AOF 加载不计入，管理性 slot 删除（如CLUSTER FLUSHSLOT、slot 迁移）也不会喂入或挤出采样器。导入流量是用户驱动的负载，会被计入。
内省型查找被跳过。带LOOKUP_NOHOTKEYS标记的查找（OBJECT、DEBUG、cluster redirect 查找）不算访问；EXISTS、TYPE、TTL这类只带LOOKUP_NOTOUCH的客户端读取仍算真实访问。
RENAME / MOVE / SWAPDB 不会重归因。条目按 (key 名, db) 跟踪，这些命令之后旧条目立即停止累计、随窗口轮转消失，所以HOTKEYS GET最多在hotkeys-window-seconds内报告旧名称或旧数据库。
多种数据类型均被跟踪。单元测试覆盖了 string、hash、list、set、zset 上的访问。
HOTKEYS属于 server 命令组，GET与RESET子命令在 ACL 中归入ADMIN、DANGEROUS、SLOW类别，使用受限 ACL 的客户端需要相应权限；HOTKEYS HELP可列出全部子命令。