当前位置：首页 > news >正文

【OceanBase诊断调优】—— KVCache 排查手册

news 2026/2/7 11:33:42

原文链接：OceanBase分布式数据库-海量数据笔笔算数

本文介绍 KVcache 相关问题的排查方法。

KVCache 相关概念

在进行排查前，需要了解几个概念。

pin

一个 cache 块 ( memblock ) 被 pin 住，表示它正在被引用。

cache 的由多个定长的块组成，每个块称为一个 memblock 。每个 memblock 中存放了多个 KV ，使用者通过 KV 指针来读取 KV 。容易理解，在使用指针的过程中，需要保证指针的安全，也即需要 pin 住存放 KV 的 memblock ，保证它不被释放。cache 内部通过引用计数来实现，cache 每向外吐出一个 KV 指针，都要对 KV 所在的 memblock 的引用计数加 1 ( pin 住这个 memblock ) ，当不再使用 KV 指针时，引用计数减 1 。也就是说，当引用计数大于 0 时，说明有人正在读其中的内存，那这个 memblock 就不能被释放，反之如果等于 0 ，则释放是安全的。

简而言之，如果一个 memblock 被 pin 住，那么它不能被释放。
sync wash

sync wash 指 cache 腾出自身内存给租户使用的过程。从 1 可知，如果一个 memblock 没有被 pin ，那么它是可以被释放的。sync wash 就是 cache 找到没有被 pin 的 memblock ，释放内存，腾给租户使用。
cache 大小无上限

cache 的大小在一个租户内是无上限的。为了最大化利用租户内存，在租户内不限制 cache 的大小，理论上 cache 最大可以占满一个租户的内存。但是 cache 的内存比较特殊，在租户需要内存时，会触发 cache 的 sync wash ，腾出内存给租户使用。

常见问题

ret=-4273 can not find enough memory block to wash

首先 4273 不是 cache 的问题，4273 报错表示在 sync wash 过程中发现 cache 中所有的 memblock 都被 pin 了，没有内存可以释放。导致 4273 的原因可能有：

cache 本身已经被榨干了，没有内存可以 wash ，所以就找不到不被 pin 的 memblock。
cache 本身还有内存，但是都被 pin 住了，无法 wash 出来；这个原因又分为两种情况：
- 确实有需要较多 cache 的 SQL 在执行。
- cache handle 引用计数有泄漏。

排查的思路就是逐步确认是哪个原因导致的 4273 ，步骤如下：

查看当时 cache 的大小。

* 通过 MEMORY 日志，memory 日志可以看到租户的 cache_hold ，这个字段记录了 cache 的总大小。
* 通过 CACHE 日志，可以看到当时各个 cache 的大小。
* 通过虚拟表 `__all_virtual_kvcache_info`，各版本都有，但是是实时数据，需要在案发时查询。

如果此时 cache 大小很少，说明此时 cache 本身已经被榨干，wash 不出内存符合预期，应该查看当时租户的内存分布，看看其他 mod 是否符合预期，否则进入第二步。

判断是否存在泄漏。

这一步是通过查看 cache 的大小能否降下来，来区分是 cache handle 引用计数有泄漏还是确实有需要较多 cache 的 SQL 在执行。

对于 OceanBase 数据库 V4.0 及以后版本，可以停止所有查询后尝试手动 flush cache ，如果 cache 能降下来，则说明没有泄漏，是确实有需要较多 cache 的 SQL 在执行导致。

手动 flush 需要直连到 OBServer 节点上执行，如果可以 flush 干净 ( 可能需要手动 flush 多次 ) ，则表示没有泄漏，对比 flush 前后 __all_virtual_kvcache_info 表中 size 的变化来判断。也可以通过查询 __all_virtual_kvcache_store_memblock 虚拟表来直接查看所有 memblock 引用计数，看是否有异常。
```
select * from __all_virtual_kvcache_store_memblock where ... order by ref_count desc limit 10;
```
对于 OceanBase 数据库 V4.0 之前版本，只能通过日志查看在 4273 报错后，cache 的大小是否降下去过，如果能降下去，则说明一定没有泄漏，如果没降下去过，则无法判断。( 因为之前版本手动 flush 并不会立即释放 cache 的内存，而是通过降低其访问热度，通过后台 wash 线程慢慢刷出去。 )

如果是较多 cache 的 SQL 在执行导致，规避方案是，将 cache 用量较大的操作分散在租户内存压力较小的时候执行，如果仍有报错，尝试对租户内存进行扩容，增大内存。如果是 cache handle 引用计数有泄漏导致，则需要复现问题，排查泄漏的路径。

cache 占用内存较高

如前文所述，cache 在租户内是无上限的，所以理论上无论 cache 占多大内存，只要能被 sync wash ，就是符合预期的。判断能否 sync wash 出来需要参考问题 1 中判断 cache 大小能否降下来的方法，能降下来就是能 sync wash 出来。

cache 预热

OceanBase 数据库 V4.0 及以后的版本支持 cache 预热功能，之前版本没有此功能。为缓解 compaction 后的性能抖动，在 compaction 时会将新生成的微块放入 cache 中，进行预热。预热并不会将所有新生成的微块都预热进 cache ，而是根据租户的内存情况进行预热。现有策略下，data block cache 使用租户空闲内存的 5% ，index block 使用租户空闲内存的 2% 。 data block 和 index block 按照不同的优先级被预热进 cache ，按照中间层索引树的等级分配不同的优先级，越接近根节点的 block 优先级越高。

wash

cache 腾出自身内存的过程称为 wash ，cache 的 wash 行为分为同步 wash 和异步 wash 两种。同步 wash 就是上文提到的 sync wash，同步腾出内存，这里不再赘述。异步 wash 由一个后台 wash 线程完成，wash 线程会定期地根据每个租户的内存压力 ( 包括租户大小、当前 cache 大小、租户当前空闲内存等 ) 计算出租户应该 wash 出的 cache size ，然后再根据每个 memblock 的访问热度从低到高 wash 。如果压力不大，计算结果可能是 0，不做 wash ，可以根据如下日志来判断，如果有则表示 wash 线程异步 wash 了 memblock。

COMMON_LOG(INFO, "Wash memory, ","tenant_id", wash_iter->first,"cache_size", tenant_wash_info->cache_size_,"lower_mem_limit", tenant_wash_info->lower_limit_,"upper_mem_limit", tenant_wash_info->upper_limit_,"min_wash_size", tenant_wash_info->min_wash_size_,"max_wash_size", tenant_wash_info->max_wash_size_,"mem_usage", lib::get_tenant_memory_hold(wash_iter->first),"reserve_mem", static_cast<int64_t>((static_cast<double>(tenant_wash_info->upper_limit_)) * tenant_reserve_mem_ratio_),"wash_size", tenant_wash_info->wash_size_);

wash 线程的异步 wash 实际上是减去 memblock 原始的引用计数，等待引用计数减为 0 时执行释放，因此：

异步 wash 并不能立即释放 memblock ，需要等待不被 pin 。
如果有引用计数泄漏泄漏，wash 线程一样不能 wash memblock。

手动 flush

手动 flush cache 表示手动清理指定 cache ，命令如下，目前只能在 sys 租户下执行，需要直连要 flush 的 OBServer 节点。

alter system flush kvcache [tenant tenant_name [cache 'cache_name']];

cache_name 可以在 __all_virtual_kvcache_info 中查到，常用的 cache_name 有：user_block_cache、index_block_cache、user_row_cache、fuse_row_cache、bf_cache。

OceanBase 数据库 V4.0 及以后版本，flush 包含了立即清空的功能，预期情况下，flush 之后 cache 应该是立即被清空（若内存占用太多，flush 只清理一部分内存）。如果发生 4274 的报错，是 cache 较多导致的超时问题，再次 flush 即可。

OceanBase 数据库 V4.0 之前版本，手动 flush 只会清除指定 cache 中 KV 的索引，索引删除后，对应的 KV 就无法再被访问到，其所在的 memblock 的热度就会持续降低，等待 wash 线程将其 wash 出去。

判断手动 flush 是否生效

无论新老版本，手动 flush 一定会清理掉全部的 kv_cnt ，可以观察 flush 前后 kv_cnt 是否清零过来判断手动 flush 是否生效。

select * from __all_virtual_kvcache_info where cache_name = '<cache_name>';

监控 cache handle ，排查引用计数泄漏

OceanBase 数据库 V4.0 及之后版本，如果怀疑或确认 cache 引用计数有泄漏，可以通过如下方法诊断。

binary 需要启用 ENABLE_DEBUG_LOG 编译选项。

打开监控，指定监控的 cache name 。

alter system set leak_mod_to_check = 'cache_name';

查看泄漏 backtrace 。
```
select * from __all_virtual_kvcache_handle_leak_info where tenant_id = tenant_id order by hold_count desc limit 10;
```
在 OceanBase 数据库 V4.3 及以后版本虚拟表更名为 __all_virtual_storage_leak_info，并且新增配置项 _storage_leak_check_mod 用于指定泄漏监控的内容。

这里简单介绍一下监控的实现方法。cache 对外吐出的引用计数都包含在 cache_handle 中，一个 cache_handle hold 住 1 个引用计数，所以在 cache 对外吐出 cache_handle 时，记录一条 backtrace ，在 cache_handle reset 时，消除记录。所以最后遗留下来未释放的 backtrace 很大可能就是泄漏的 backtrace 。

根据记录方式可以知道，只要当前 cache 外部有 cache_handle ，那就会被记录 backtrace ，所以任何路径在持有 cache_handle 期间都会被记录，需要抓到持有时间过长或不符合预期的堆栈才是泄漏的堆栈。

如果事先没有开启 cache handle 监控，可以通过 __all_virtual_kvcache_store_memblock 虚拟表简要确认一下问题，这张表会输出当前 server 上所有 memblock 的信息。 (OceanBase 数据库 V 4.3 及以后版本使用新的虚拟表)
```
select * from __all_virtual_kvcache_store_memblock where ... order by ref_count desc limit 10;
```
关注 ref_count 列，这一列表示 memblock 的当前的引用计数，目前当 memblock 没有被引用时，这里拿到的引用计数为 2 ( 初始引用计数为 1 ，查 memblock 信息时需要先加引用计数做保护，因此为 2 ) 。在确保某 memblock 当前不会被 pin 的前提下，ref_count 大于 2 的 memblock 都可以认为有引用计数泄漏。

泄漏检测扩展 (OceanBase 数据库 V4.3 及以后版本)

OceanBase 数据库 V4.3 及以后版本，新增存储层的泄漏检测功能，目前支持的检测内容有 cache handle、io handle、storage iter ，同时，新增配置项 _storage_leak_check_mod 用于配置泄漏检测的内容，有效值分别为 cache_name / all_cache / io_handle / storage_iter ，默认为空串，设定成空串或其他值时，关闭监控。

同时，__all_virtual_kvcache_handle_leak_info 虚拟表更名为 __all_virtual_storage_leak_info。

检测步骤使用新的配置和虚拟表即可：

binary 需要启用 ENABLE_DEBUG_LOG 编译选项。

打开监控，指定监控的内容。

alter system set _storage_leak_check_mod = 'cache_name' | 'all_cache' | 'io_handle' | 'storage_iter' ;

查看泄漏 backtrace。

select * from __all_virtual_storage_leak_info where ... order by hold_count desc limit 10;