From bbe91aa7a6fb84c5be04609b67d108364bb0454b Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 3 Oct 2026 00:44:17 +0800 Subject: [PATCH] fix(skills): use bounded replacement windows for leak candidates --- docs/en/querying.md | 46 ++++- docs/zh/querying.md | 39 +++- skills/pt-snap-memory-leak/SKILL.md | 41 +++- .../pt-snap-memory-leak/SKILL.md | 41 +++- tests/test_leak_query_window.py | 183 ++++++++++++++++++ 5 files changed, 336 insertions(+), 14 deletions(-) create mode 100644 tests/test_leak_query_window.py diff --git a/docs/en/querying.md b/docs/en/querying.md index be4c3a3..14dba95 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -80,6 +80,42 @@ the target device with the command-level `--device` option, not inside `--params not confirmed leaks. Read field units and interpretation limits with `pt-snap query --template-info leak_detection`. +### Retrieving a complete candidate window + +`leak_detection` accepts `min_size` and `limit`, but **no `offset`**. Passing +`offset` is rejected (`INVALID_PARAMETER` in CLI JSON, `TemplateRenderError` +in the Python API). `has_more: true` signals incomplete results; it does not +promise offset pagination. + +Start with a bounded query. If full coverage is needed, obtain an exact count +while keeping the returned window bounded: + +```bash +pt-snap query '' --device --template-use leak_detection --params '{"min_size":1024}' -n 100 --exact-total --json +``` + +Exact `total` counts matching **rows**, not bytes or GiB, and ignores `limit`. +If it is zero, report no matching candidates without rerunning with `-n 0` +(which means unlimited). If it is positive and affordable within your +memory/output budget, rerun once with `-n ` using the same +database, device, and filters: + +```bash +pt-snap query '' --device --template-use leak_detection --params '{"min_size":1024}' -n --json +``` + +Remove any explicit `limit` from `--params`, or raise it to the same count; +otherwise a smaller `limit` still caps the enlarged window. Verify `returned` +equals the exact count and both `has_more` and `truncated` are false. **Replace** +the earlier rows with the new result; never append overlapping windows or add +their counts/bytes. The API follows the same workflow with `exact_total=True` +and a positive `max_rows`. + +If the full result exceeds the budget, keep a bounded sample and report that +candidate/byte coverage is incomplete. An exact row count does not provide the +total candidate bytes. Increasing `min_size` changes the analysis scope and +requires a new count; it cannot establish completeness for the original scope. + ## Parameter Validation `--params` is validated against the template before any SQL is rendered: @@ -239,9 +275,13 @@ caps such as `top_n` stay their own parameters; they do not rewrite `semantics_version`, `interpretation_limits`, and field semantics from `output_schema`. -`event`, `block`, `allocation`, and `leak_detection` paginate with a stable -`id` tie-break after the primary sort. Continue a truncated `limit` / -`offset` listing with the same sort keys and a higher `offset` (or `-n`). +`event`, `block`, and `allocation` support `offset` pagination with a stable +`id` tie-break after the primary sort. Continue their truncated `limit` / +`offset` listings with the same sort keys and a higher `offset`. +`leak_detection` also has a stable `id` tie-break, but has no `offset`; +use the [complete candidate window](#retrieving-a-complete-candidate-window) +workflow above. Increasing `-n` replaces the earlier window rather than +fetching a disjoint next page. `has_more` does not imply offset support. `active_memory_callstack_at_event` has no `offset`; `-n` cannot raise the CTE `top_n` cap. Continue that template by increasing `top_n`. diff --git a/docs/zh/querying.md b/docs/zh/querying.md index fdbd909..422b72c 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -79,6 +79,36 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' 仍存活的候选,不是已确认泄漏。用 `pt-snap query --template-info leak_detection` 读取字段单位与解释限制。 +### 获取完整候选窗口 + +`leak_detection` 只接受 `min_size` 与 `limit`,**没有 `offset`**。传入 +`offset` 会被拒绝(CLI JSON 返回 `INVALID_PARAMETER`,Python API 抛出 +`TemplateRenderError`)。`has_more: true` 表示结果不完整,不保证支持 offset 分页。 + +先执行有界查询。需要完整候选集时,在保持返回窗口有界的前提下获取精确计数: + +```bash +pt-snap query '' --device --template-use leak_detection --params '{"min_size":1024}' -n 100 --exact-total --json +``` + +精确 `total` 是匹配的**行数**,不是字节数或 GiB,且忽略 `limit`。若为零, +报告没有匹配候选即可,不要再用 `-n 0` 查询(它表示不限制)。只有总数为正且 +内存/输出预算可承受时,才使用同一数据库、设备和过滤条件,通过 +`-n ` 单次获取该行数: + +```bash +pt-snap query '' --device --template-use leak_detection --params '{"min_size":1024}' -n --json +``` + +删除 `--params` 中显式的 `limit`,或同步增大到该总数;否则较小的 `limit` +仍会限制扩大后的窗口。确认 `returned` 等于精确计数,且 `has_more` 与 +`truncated` 均为 false。用新结果**替换**旧结果,不要追加重叠窗口或累加各次 +计数/字节数。API 采用相同流程,使用 `exact_total=True` 和正数 `max_rows`。 + +完整结果超出预算时,保留有界样本并明确报告候选/字节覆盖不完整。精确行数 +无法给出候选总字节数。增大 `min_size` 会改变分析范围,需要重新计数,不能 +据此声称已经覆盖原始范围的全部结果。 + ## 参数校验 `--params` 会在渲染任何 SQL 之前按模板定义进行校验: @@ -224,9 +254,12 @@ QueryService 调用的共享预算(页面查询与可选 COUNT 共用),作 `--template-info --json` 包含 `semantics_version`、`interpretation_limits` 以及 `output_schema` 上的字段语义。 -`event`、`block`、`allocation` 与 `leak_detection` 在主排序后用 `id` 做稳定 -次序。带 `limit` / `offset` 的截断列表应带着相同排序键提高 `offset` -(或 `-n`)续页。`active_memory_callstack_at_event` 没有 `offset`,`-n` +`event`、`block` 与 `allocation` 支持 `offset` 分页,在主排序后用 `id` 做稳定 +次序。它们带 `limit` / `offset` 的截断列表应带着相同排序键提高 `offset` 续页。 +`leak_detection` 也有稳定的 `id` 次序,但没有 `offset`,应遵循上文的 +[完整候选窗口流程](#获取完整候选窗口)。增大 `-n` 是替换先前窗口,不是获取 +不重叠的下一页。`has_more` 不代表支持 offset。 +`active_memory_callstack_at_event` 没有 `offset`,`-n` 也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 续页。 `--json` 失败时 stdout 为空,stderr 为: diff --git a/skills/pt-snap-memory-leak/SKILL.md b/skills/pt-snap-memory-leak/SKILL.md index 9af2fd9..8dedbc1 100644 --- a/skills/pt-snap-memory-leak/SKILL.md +++ b/skills/pt-snap-memory-leak/SKILL.md @@ -101,15 +101,48 @@ Treat a large `reserved - active` gap without corresponding active growth as an ### 2. Find end-of-trace dynamic candidates Run an initial ranked query, keeping the result bounded. Prefer `--json`. Default -`total` equals this page's `returned` count; do not treat it as the full -matching set. If `has_more` or `truncated` is true, continue with `offset` or a -larger `-n` instead of concluding from the first page. Add `--exact-total` only -when a matching-row count is required. `--timeout` is independent of `-n`. +`total` equals this window's `returned` count; do not treat it as the full +matching set. `leak_detection` accepts only `min_size` and `limit`: it has no +`offset`, and both CLI and API reject that unknown parameter. `has_more` or +`truncated` means the result is incomplete, not that offset paging is supported. +`--timeout` is independent of `-n`. ```bash pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --json ``` +If the result is incomplete and a full candidate set is needed: + +1. Repeat with the same database, device, and `min_size`, adding `--exact-total`: + + ```bash + pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --exact-total --json + ``` + + The exact `total` is a matching **row count**, not bytes or GiB. The count + ignores `limit`; it does not make the returned rows complete. +2. If `total` is zero, report no matching candidates and stop this candidate + listing. Do not pass zero to `-n`: `-n 0` means unlimited, not an empty window. +3. Only when the positive exact total is affordable within the memory/output + budget, request that many rows in one bounded window. Replace `` + below with that count. Remove any explicit `limit` from `--params` (as below), + or raise it to the same count; a smaller explicit `limit` still caps `-n`. + + ```bash + pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n --json + ``` + +4. Verify `returned` equals the exact count and both `has_more` and `truncated` + are false before claiming completeness. The enlarged result **replaces** the + earlier rows; never append windows or add their counts/bytes together, because + every rerun starts at the same ranked beginning. + +If the full count exceeds the budget, retain a bounded sample and explicitly +report incomplete candidate/byte coverage. An exact row count alone does not +give total candidate bytes. A higher `min_size` can narrow a follow-up query, +but changes the scope and requires a new count; do not call that the original +complete set. Never use an unlimited window to bypass the budget. + `leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from the `leak_detection` entry in `pt-snap capabilities --json`; do not treat candidates as confirmed leaks. Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`. diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md index 9af2fd9..8dedbc1 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md @@ -101,15 +101,48 @@ Treat a large `reserved - active` gap without corresponding active growth as an ### 2. Find end-of-trace dynamic candidates Run an initial ranked query, keeping the result bounded. Prefer `--json`. Default -`total` equals this page's `returned` count; do not treat it as the full -matching set. If `has_more` or `truncated` is true, continue with `offset` or a -larger `-n` instead of concluding from the first page. Add `--exact-total` only -when a matching-row count is required. `--timeout` is independent of `-n`. +`total` equals this window's `returned` count; do not treat it as the full +matching set. `leak_detection` accepts only `min_size` and `limit`: it has no +`offset`, and both CLI and API reject that unknown parameter. `has_more` or +`truncated` means the result is incomplete, not that offset paging is supported. +`--timeout` is independent of `-n`. ```bash pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --json ``` +If the result is incomplete and a full candidate set is needed: + +1. Repeat with the same database, device, and `min_size`, adding `--exact-total`: + + ```bash + pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n 100 --exact-total --json + ``` + + The exact `total` is a matching **row count**, not bytes or GiB. The count + ignores `limit`; it does not make the returned rows complete. +2. If `total` is zero, report no matching candidates and stop this candidate + listing. Do not pass zero to `-n`: `-n 0` means unlimited, not an empty window. +3. Only when the positive exact total is affordable within the memory/output + budget, request that many rows in one bounded window. Replace `` + below with that count. Remove any explicit `limit` from `--params` (as below), + or raise it to the same count; a smaller explicit `limit` still caps `-n`. + + ```bash + pt-snap query '' --device --template-use leak_detection --params '{"min_size":}' -n --json + ``` + +4. Verify `returned` equals the exact count and both `has_more` and `truncated` + are false before claiming completeness. The enlarged result **replaces** the + earlier rows; never append windows or add their counts/bytes together, because + every rerun starts at the same ranked beginning. + +If the full count exceeds the budget, retain a bounded sample and explicitly +report incomplete candidate/byte coverage. An exact row count alone does not +give total candidate bytes. A higher `min_size` can narrow a follow-up query, +but changes the scope and requires a new count; do not call that the original +complete set. Never use an unlimited window to bypass the budget. + `leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from the `leak_detection` entry in `pt-snap capabilities --json`; do not treat candidates as confirmed leaks. Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`. diff --git a/tests/test_leak_query_window.py b/tests/test_leak_query_window.py new file mode 100644 index 0000000..34b9eb9 --- /dev/null +++ b/tests/test_leak_query_window.py @@ -0,0 +1,183 @@ +"""Issue #160: bounded leak windows replace earlier results, not offset pages.""" + +import json +import shlex +import sqlite3 +from pathlib import Path + +import pytest +from typer.testing import CliRunner + +from pt_snap_cli.api import SnapshotAnalyzer +from pt_snap_cli.cli import app +from pt_snap_cli.core import TemplateRenderError + +ROOT = Path(__file__).resolve().parents[1] +runner = CliRunner() +CANDIDATE_COUNT = 325 +CANDIDATE_BYTES = sum(1024 * (1 + i % 3) for i in range(1, CANDIDATE_COUNT + 1)) + + +@pytest.fixture +def leak_db(tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_DB_PATH", raising=False) + monkeypatch.delenv("PT_SNAP_QUERY_TIMEOUT", raising=False) + monkeypatch.setattr(Path, "home", lambda: tmp_path) + path = tmp_path / "leak-window.db" + with sqlite3.connect(path) as conn: + conn.executescript(""" + CREATE TABLE dictionary (`table` TEXT, `column` TEXT, `key` TEXT, `value` TEXT); + CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY, callstack TEXT); + CREATE TABLE block_0 ( + id INTEGER PRIMARY KEY, address INTEGER, size INTEGER, + allocEventId INTEGER, freeEventId INTEGER + ); + INSERT INTO block_0 VALUES + (-1, 1, 8192, -1, -1), + (1000, 2, 8192, 1000, 1001), + (1002, 3, 512, 1002, -1); + """) + conn.executemany( + "INSERT INTO block_0 VALUES (?, ?, ?, ?, ?)", + [ + (i, i * 4096, 1024 * (1 + i % 3), i, None if i % 2 else -1) + for i in range(1, CANDIDATE_COUNT + 1) + ], + ) + return path + + +def query_both(path, params, max_rows, exact_total=False): + """Run the same real SQLite query through CLI JSON and the public API.""" + args = [ + "query", + str(path), + "--device", + "0", + "--template-use", + "leak_detection", + "--params", + json.dumps(params), + "-n", + str(max_rows), + "--json", + ] + if exact_total: + args.append("--exact-total") + result = runner.invoke(app, args) + assert result.exit_code == 0, result.output + payload = json.loads(result.stdout) + analyzer = SnapshotAnalyzer(db_path=path, device_id=0) + try: + api = analyzer.execute_query( + "leak_detection", params=params, max_rows=max_rows, exact_total=exact_total + ) + finally: + analyzer.invalidate_context_cache() + for key in ("rows", "total", "returned", "total_is_exact", "has_more", "truncated"): + assert payload[key] == api[key] + return payload + + +@pytest.mark.parametrize("offset", [0, 100]) +def test_leak_offset_is_rejected_by_cli_and_api(leak_db, offset): + params = {"min_size": 1024, "limit": 100, "offset": offset} + result = runner.invoke( + app, + [ + "query", + str(leak_db), + "--device", + "0", + "--template-use", + "leak_detection", + "--params", + json.dumps(params), + "--json", + ], + ) + assert result.exit_code == 1 + assert result.stdout == "" + error = json.loads(result.stderr)["error"] + assert error["code"] == "INVALID_PARAMETER" + analyzer = SnapshotAnalyzer(db_path=leak_db, device_id=0) + try: + with pytest.raises(TemplateRenderError) as exc: + analyzer.execute_query("leak_detection", params=params) + finally: + analyzer.invalidate_context_cache() + assert error["message"] == str(exc.value) + assert "Unknown parameter(s) for template 'leak_detection': offset" in str(exc.value) + + +@pytest.mark.parametrize("synchronize_limit", [False, True]) +def test_exact_count_then_replace_window_after_fixing_explicit_limit(leak_db, synchronize_limit): + params = {"min_size": 1024, "limit": 100} + initial = query_both(leak_db, params, 100) + assert initial["total"] == initial["returned"] == 100 + assert initial["total_is_exact"] is False + assert initial["has_more"] is initial["truncated"] is True + + counted = query_both(leak_db, params, 100, exact_total=True) + assert counted["total"] == CANDIDATE_COUNT + assert counted["total_is_exact"] is True + assert counted["returned"] == 100 + assert counted["rows"] == initial["rows"] + + capped = query_both(leak_db, params, counted["total"]) + assert capped["rows"] == initial["rows"] + assert capped["has_more"] is capped["truncated"] is True + assert capped["effective_params"]["limit"] == 100 + + if synchronize_limit: + params["limit"] = counted["total"] + else: + del params["limit"] + complete = query_both(leak_db, params, counted["total"]) + assert complete["returned"] == complete["total"] == counted["total"] + assert complete["has_more"] is complete["truncated"] is False + assert complete["rows"][:100] == initial["rows"] # Overlap, not a next page. + assert {row["id"] for row in complete["rows"]} == set(range(1, CANDIDATE_COUNT + 1)) + assert sum(row["size"] for row in complete["rows"]) == CANDIDATE_BYTES + + +def test_empty_count_uses_positive_bounded_window(leak_db): + empty = query_both(leak_db, {"min_size": 16384}, 100, exact_total=True) + assert empty["total"] == empty["returned"] == 0 + assert empty["rows"] == [] + assert empty["total_is_exact"] is True + assert empty["has_more"] is empty["truncated"] is False + assert empty["effective_params"]["limit"] == 100 + + +def test_exact_count_does_not_make_budget_limited_rows_complete(leak_db): + sample = query_both(leak_db, {"min_size": 1024}, 20, exact_total=True) + assert sample["total"] == CANDIDATE_COUNT + assert sample["returned"] == 20 + assert sample["has_more"] is sample["truncated"] is True + assert sum(row["size"] for row in sample["rows"]) < CANDIDATE_BYTES + + +def test_skill_step_two_commands_fetch_one_complete_replacement(leak_db): + """Execute the shipped guidance, so a future invalid offset example fails.""" + text = (ROOT / "skills/pt-snap-memory-leak/SKILL.md").read_text() + step = text.split("### 2. Find end-of-trace dynamic candidates", 1)[1].split("### 3.", 1)[0] + commands = [line.strip() for line in step.splitlines() if line.strip().startswith("pt-snap ")] + assert len(commands) == 3 + results = [] + for command in commands: + command = command.replace("", str(leak_db)) + command = command.replace("", "0").replace("", "1024") + if "" in command: + assert results[-1]["total_is_exact"] is True + command = command.replace("", str(results[-1]["total"])) + result = runner.invoke(app, shlex.split(command)[1:]) + assert result.exit_code == 0, result.output + results.append(json.loads(result.stdout)) + initial, counted, complete = results + assert initial["returned"] == counted["returned"] == 100 + assert counted["total"] == complete["returned"] == CANDIDATE_COUNT + assert complete["rows"][:100] == initial["rows"] + assert complete["has_more"] is complete["truncated"] is False + assert sum(row["size"] for row in complete["rows"]) == CANDIDATE_BYTES