故障注入#

一个 仅用于测试/诊断 的适配器，它包装了一个真实的内部适配器，并在加载读取时确定性地丢弃键，模拟部分 L2 检索失败。它测试了 CacheBlend 的 分段前缀 恢复路径——一个健康缓存从未产生的间隙找到集（命中 … 未命中 … 命中）——而无需实际故障的后端。

警告

切勿在生产环境中启用。它会悄无声息地使读取失败，因此它提供的任何 KV 都是故意不完整的。

包装的后端作为完整的适配器规范在 inner 下提供（任何注册的 type），因此它保留自己的配置、逐出、持久化和序列化设置。故障仅适用于加载读取：丢失的键在查找时被报告为存在，但其加载失败（忠实的“L2 检索错误”）；预取控制器通过修剪掩码释放加载失败的锁。其他所有操作（存储、查找、解锁、删除、使用）都直接传递给内部适配器。

字段：

  • inner（必需）：用于包装后端的完整适配器规范，例如 {"type": "fs_native", "base_path": "/dev/shm/l2"}。

  • gap_tail_ratios: 始终丢弃的位置，以负载长度的尾部距离比例给出，范围在 [0, 1] 之间（0.0 = 最后一个块，0.5 = 中间，1.0 = 第一个）。与工作负载无关，并且在上下文长度上自我缩放。默认 []。

  • gap_indices: 始终丢弃的精确头相对任务位置。默认 []。

  • rate: 每个键的丢弃概率在 [0, 1] 范围内，通过键的稳定种子哈希计算。默认值为 0.0（直通）。

  • seed: rate 哈希的种子（给定种子时是确定性的）。默认值为 0。

默认值是直接传递的；至少设置 gap_tail_ratios、gap_indices 或 rate 之一以丢弃任何内容。

丢弃一个稳定的中间前缀间隙（CacheBlend 分段前缀重现），包装一个 fs_native 后端：

--l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_tail_ratios": [0.5]}'

要实际测试 CacheBlend 的 分段前缀恢复，将间隙与服务器标志 --enable-segmented-prefix 配对（仅适用于 CacheBlend — --engine-type blend）。丢弃的中间块会产生一个带间隙的查找集；启用分段前缀后，前缀部分 保留间隙后的块（加载前缀 + 尾部）并仅重计算 丢弃的间隙，而不是在间隙处截断前缀：

lmcache server … \
    --l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_tail_ratios": [0.5]}' \
    --enable-segmented-prefix

随机丢弃约 10% 的加载（根据种子确定）：

--l2-adapter '{"type": "fault_inject", "inner": {"type": "fs", "base_path": "/data/l2"}, "rate": 0.1, "seed": 7}'

丢弃一个确切的加载位置（精确的单缺口重现）：

--l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_indices": [12]}'

在启动时，适配器记录 FaultInjectL2Adapter ACTIVE (rate=… seed=… gap_indices=… gap_tail_ratios=[…]) wrapping <inner> -- 仅用于测试/诊断。，并且 report_status() 在 fault_inject 子字典下报告活动故障配置。