Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 43 additions & 3 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<db_path>' --device <device_id> --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 <positive_total>` using the same
database, device, and filters:

```bash
pt-snap query '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":1024}' -n <positive_total> --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:
Expand Down Expand Up @@ -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`.

Expand Down
39 changes: 36 additions & 3 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":1024}' -n 100 --exact-total --json
```

精确 `total` 是匹配的**行数**,不是字节数或 GiB,且忽略 `limit`。若为零,
报告没有匹配候选即可,不要再用 `-n 0` 查询(它表示不限制)。只有总数为正且
内存/输出预算可承受时,才使用同一数据库、设备和过滤条件,通过
`-n <positive_total>` 单次获取该行数:

```bash
pt-snap query '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":1024}' -n <positive_total> --json
```

删除 `--params` 中显式的 `limit`,或同步增大到该总数;否则较小的 `limit`
仍会限制扩大后的窗口。确认 `returned` 等于精确计数,且 `has_more` 与
`truncated` 均为 false。用新结果**替换**旧结果,不要追加重叠窗口或累加各次
计数/字节数。API 采用相同流程,使用 `exact_total=True` 和正数 `max_rows`。

完整结果超出预算时,保留有界样本并明确报告候选/字节覆盖不完整。精确行数
无法给出候选总字节数。增大 `min_size` 会改变分析范围,需要重新计数,不能
据此声称已经覆盖原始范围的全部结果。

## 参数校验

`--params` 会在渲染任何 SQL 之前按模板定义进行校验:
Expand Down Expand Up @@ -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 为:
Expand Down
41 changes: 37 additions & 4 deletions skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<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 `<positive_total>`
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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<min_size>}' -n <positive_total> --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`.
Expand Down
41 changes: 37 additions & 4 deletions src/pt_snap_cli/bundled_skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<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 `<positive_total>`
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 '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<min_size>}' -n <positive_total> --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`.
Expand Down
Loading
Loading