Skip to content

[FEATURE] 为 SnapshotDB 表创建常用查询列的索引(子任务 #72-1) #73

Closed

Description

@codeasier

功能描述

SnapshotDb.create_block_table / create_trace_entry_table 在建表后完全没有创建任何索引(只有 id 主键自带索引)。而查询模板大量使用以下列做 WHERE / ORDER BY / 聚合,对几十万行的表全部退化为全表扫描。

本 issue 是 #72 的子任务,单独聚焦「建索引」这一最高 ROI 的修复点。

使用场景

  • 任何 pt-snap query 调用,特别是 leak_detection / active_blocks_at_event / memory_peak / allocator_gap
  • 在 MCP server 中反复执行查询模板

期望的实现方式

涉及列

表 需要索引的列 使用该列的模板
block_{device} allocEventId leak_detection, active_blocks_at_event
block_{device} freeEventId leak_detection, active_blocks_at_event
block_{device} size leak_detection, active_blocks_at_event
trace_entry_{device} allocated memory_peak, allocator_gap
trace_entry_{device} active memory_peak, allocator_gap
trace_entry_{device} reserved memory_peak, allocator_gap

实现要点

SqliteTable.create_index 方法已存在(sqlite_meta.py:258),但 SnapshotDb.create_block_table / create_trace_entry_table 从未调用它。

建议在两个建表方法末尾追加:

def create_trace_entry_table(self, device: int = 0):
    self.create_table(
        SqliteTable(self.get_trace_table_name_by_device(device), _TRACE_ENTRY_TABLE_COLUMNS),
        delete_if_exists=True,
    )
    table = self.get_trace_entry_table(device)
    for col in ("allocated", "active", "reserved"):
        table.create_index(self.conn, col)

def create_block_table(self, device: int = 0):
    self.create_table(
        SqliteTable(self.get_block_table_name_by_device(device), _BLOCK_TABLE_COLUMNS),
        delete_if_exists=True,
    )
    table = self.get_block_table(device)
    for col in ("allocEventId", "freeEventId", "size"):
        table.create_index(self.conn, col)

注意事项

  • 索引创建发生在 import 写入阶段,会增加少量导入耗时,但后续每次查询都受益。需权衡:可考虑在导入完成后批量建索引,而非建表时立即建。
  • 已存在的旧 db 文件没有索引,需考虑兼容方案(首次打开时懒建索引,或文档说明需重新 import)。
  • 复合查询条件(如 allocEventId <= X AND freeEventId > Y)可考虑复合索引,但先以单列索引起步。

涉及代码:

  • src/pt_snap_cli/vendor/memsnapdump/tools/adaptors/database/snapshot_db.py
  • src/pt_snap_cli/vendor/memsnapdump/util/sqlite_meta.py:SqliteTable.create_index

验收标准

  • create_block_table 后自动创建 allocEventId / freeEventId / size 索引
  • create_trace_entry_table 后自动创建 allocated / active / reserved 索引
  • 新增测试验证索引存在(PRAGMA index_list / index_info)
  • 现有测试全部通过,特别是 tests/test_contract_cli_mcp.py
  • 对大快照(10w+ 行)做查询耗时对比,确认显著下降

父 issue

#72

Activity

  1. codeasier commented on Jul 27, 2026

    @codeasier
    OwnerAuthor

    已对本 issue 的各项断言做了代码核实和实测(500k trace_entry 行 + 300k block 行,Python 3.13 / SQLite 3.51),结论如下。

    结论总览

    建议 是否属实 实测影响
    create_index 存在但从未调用 ✅ 确认 —
    trace_entry 的 allocated / active / reserved 索引 ✅ 应加 memory_peak 快 ~24000x,allocator_gap 快 ~8000x
    block 的 size 索引 ❌ 不应加 leak_detection 慢 10x,active_blocks_at_event 慢 4x
    block 的 allocEventId 索引 ❌ 效益为零 被 planner 完全忽略
    block 的 freeEventId 索引 ⚠️ 有争议 leak_detection 快 1.5x,但 active_blocks_at_event 慢 2x

    create_index 确实只在 sqlite_meta.py:258 定义、全仓库零调用(rg create_index 仅 1 处匹配);列名与 defs.py 中 EventFieldDefs / BlockFieldDefs 完全对得上。所以问题描述的现象是真的,但「六列都建单列索引」这个具体方案有一半是负收益。

    逐条说明

    trace_entry:强烈建议加

    memory_peak 的 6 个子查询全部升级为 covering index scan,MAX(allocated) 这类走 SQLite 的 MIN/MAX 优化变成 O(1)。allocator_gap 的 filtered CTE 被 SQLite 展平(并未物化成临时表),同样吃到 covering index。两个模板在 500k 行上分别从 ~130ms、~110ms 降到 <0.1ms。

    block:这里是方案的问题

    leak_detection 和 active_blocks_at_event 都以 ORDER BY size DESC 结尾。加上 size 索引后,planner 会选它来省掉排序,但这是个非覆盖索引,每行都要回表取 address / allocEventId / freeEventId,总代价反而高于全表扫 + 内存排序:

    -- leak_detection,无索引:20.6 ms
    SCAN block_0 | USE TEMP B-TREE FOR ORDER BY
    
    -- leak_detection,按本 issue 建议建三列索引后:207.2 ms
    SEARCH block_0 USING INDEX idx_block_0_size (size>?)
    

    active_blocks_at_event 同样从 54ms 退化到 241ms(计划里多出 USE TEMP B-TREE FOR LAST TERM OF ORDER BY,因为单列 size 索引无法满足 ORDER BY size DESC, id ASC 的混合方向)。

    补充两点验证:

    • 跑过 ANALYZE 也一样,planner 在有/无 sqlite_stat1 两种情况下都选了这个更慢的计划,不是统计信息缺失导致的误判。
    • min_size 调到 8MB(命中 9167 行)仍然慢 7x;只有把 min_size 拉到 16MB、命中 0 行时索引才明显有利。默认 min_size=0 恰好是最差情况。

    allocEventId 索引在两个 block 查询的执行计划里从未出现——size 索引一旦存在就把它挤掉了。freeEventId 索引在不建 size 索引时能让 leak_detection 触发 MULTI-INDEX OR 优化(20.6ms → 13.8ms,1.5x),但同时让 active_blocks_at_event 从 54ms 掉到 149ms(OR 分支展开成三段索引搜索)。净收益不明确。

    代价方面:六列索引让 db 从 43.8MB 涨到 76.8MB(+75%)。

    实现时序:建议不要放在建表方法里

    SnapshotDbHandler.__init__(snapshot2db.py:27-28)在建表后、批量写入之前就返回了。如果按 issue 的代码片段把 create_index 放进 create_trace_entry_table / create_block_table,索引会在整个 import 写入期间存在,每 1000 条 commit 都要维护索引,直接推高 import 耗时。issue 的「注意事项」里其实已经提到「可考虑在导入完成后批量建索引」,但给出的代码片段和这条注意事项是矛盾的——建议以后者为准。

    实测在数据写完后一次性建六个索引只要 0.47s,放在 flush() 之后代价可以忽略。

    旧 db 兼容:懒建索引在当前架构下不可行

    注意事项提到「首次打开时懒建索引」,但 Context 以只读 URI 打开数据库(context.py:119,file:{db_path}?mode=ro),查询路径物理上无法写入索引。这条需要换方案:要么在 SnapshotDb(写入路径)上提供独立的 ensure_indexes(),要么直接在文档里说明旧 db 需重新 pt-snap import。

    修正后的建议实现

    # snapshot2db.py:在所有 insert flush 完成之后调用一次
    def build_indexes(self):
        for device in self._device_event_cache:
            table = self.db.get_trace_entry_table(device)
            for col in ("allocated", "active", "reserved"):
                table.create_index(self.db.conn, col)
        # block 表:当前模板不从这些单列索引受益(实测有害或无效),暂不建

    如果后续确实要优化 leak_detection / active_blocks_at_event,方向应该是复合/覆盖索引(例如 (size DESC, id) 或把查询用到的列都放进索引让它变成 covering),而不是单列索引;并且需要配合 EXPLAIN QUERY PLAN 逐个模板验证,而非批量加列。

    验收标准修订建议

    • import 完成后自动为 trace_entry_{device} 创建 allocated / active / reserved 索引
    • 移除 block 表 allocEventId / freeEventId / size 三列索引的验收项(实测有害或无效)
    • 新增测试验证 trace 表三列索引存在(PRAGMA index_list)
    • 索引创建位于批量写入之后,而非建表时
    • 对 memory_peak / allocator_gap 做耗时对比,确认显著下降
    • 文档说明旧 db 文件需重新 import 才能获得索引加速
    • 现有测试通过(tests/test_contract_cli_mcp.py 覆盖 leak_detection 的 CLI/MCP 契约,改动不涉及其输出语义,风险低)

    综合判断:问题真实,方向正确,但建议的六列清单需要收窄到 trace_entry 三列,否则最常用的两个 block 模板会出现 4~10x 的性能回退。

  2. codeasier commented on Jul 28, 2026

    @codeasier
    OwnerAuthor

    实施说明更新(基于 PR #78 与当前 main)

    PR #78 已完成 #75 的 SQLite 写入调优并合入,因此本 issue 的实现边界和落点更新如下。

    实现边界

    • PR perf: tune SQLite snapshot imports #78 已在 SnapshotDb 写连接启用 journal_mode=MEMORY、synchronous=OFF 和 64 MiB cache;[FEATURE] 为 SnapshotDB 表创建常用查询列的索引(子任务 #72-1) #73 不再修改写入 PRAGMA。
    • 不在 vendor 的 SnapshotDb.create_trace_entry_table() / create_block_table() 中创建索引,避免批量导入期间持续维护索引。
    • 当前 SnapshotImportBackend.dump_to_db(..., finalize_temp_db=...) 已提供临时数据库发布前的 finalization 扩展点。索引应在 vendored import 成功后、os.replace() 原子发布前,通过该非 vendor 扩展点创建。
    • 索引创建失败必须使 import 失败并阻止临时数据库发布,已有目标数据库保持不变。

    修订后的索引范围

    仅为每个已导入设备的 trace_entry_<device> 创建以下三个索引:

    • allocated
    • active
    • reserved

    不创建 block_<device> 的 allocEventId、freeEventId、size 单列索引。已有实测表明这些索引无收益或会使 leak_detection / active_blocks_at_event 出现明显性能回退。后续如需优化 block 查询,应基于具体模板与 EXPLAIN QUERY PLAN 单独设计复合或覆盖索引。

    与 import metadata/cache 的交互

    当前 import 支持基于 pt_snap_metadata 的结果复用。实现时必须处理“metadata 可用但缺少新索引”的数据库,避免将其继续视为完整缓存命中。可选择:

    1. 提升 IMPORT_FORMAT_VERSION,使旧格式数据库自动触发重新 import;或
    2. 在缓存检查中验证必需索引,缺失时返回 cache miss。

    若索引被定义为导入产物格式的一部分,优先采用提升 IMPORT_FORMAT_VERSION 的方案。

    生命周期注意事项

    vendored SnapshotDbHandler 当前仍依赖 __del__ commit/close。finalizer 会重新打开临时数据库的写连接,因此测试必须覆盖 vendored import 返回后索引连接可正常打开、写入和关闭。若需要显式 close,应作为独立 lifecycle follow-up 处理,避免扩大本 issue 范围。

    修订后的验收标准

    • 索引通过非 vendor finalization 路径创建,位置在批量写入完成后、os.replace() 之前
    • 每个已导入设备的 trace 表包含 allocated / active / reserved 三个索引
    • block 表不创建 allocEventId / freeEventId / size 单列索引
    • 使用 PRAGMA index_list / PRAGMA index_info 验证索引及列映射
    • 覆盖多 device 和显式 --device 导入
    • 索引创建失败时不发布临时数据库,已有目标数据库保持不变
    • 旧格式或缺少索引的缓存数据库不会被错误复用
    • 使用 EXPLAIN QUERY PLAN 验证 memory_peak / allocator_gap 能利用 trace 索引
    • 对无索引、trace 三索引、原始六索引三种配置做专项性能对比,并记录 DB 大小
    • pytest、ruff check . 及 tests/test_contract_cli_mcp.py 全部通过

    该修订替代 issue 正文中“六列索引且在建表方法末尾创建”的建议实现。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions