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
23 changes: 19 additions & 4 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ live at `event_id` are also included:
### 3. Attribute active memory to callstacks at that event

```bash
pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}'
pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' -n 22 --json
```

This query:
Expand All @@ -188,8 +188,21 @@ This query:
- emits static and preexisting memory as dedicated groups instead of inventing a callstack

`top_n` only bounds dynamic callstack groups; `static` and
`preexisting_live_at_event` groups are always returned and are never pushed out
by larger dynamic groups.
`preexisting_live_at_event` groups, when included and present, are exempt from
that inner filter. The outer `-n` cap still applies to all output rows and can
drop special groups or dynamic top groups. For finite positive `top_n=N` with
`include_static=true`, use `-n N+2` (substitute the computed integer: `top_n=1`
needs `-n 3`, and `top_n=20` needs `-n 22`). This preserves the ranked result,
not necessarily the full dynamic set. The representative block query has its
own `limit` / `-n` cap; it does not need two extra rows.

At fixed `top_n`, increasing `-n` preserves common rows and their percentages:
the denominator is the included groups' bytes after inner ranking but before
the outer row cap. A clipped listing need not sum to 100%. Increasing `top_n`
can change the denominator. Check completeness flags before claiming full
coverage; a full ranking window conservatively sets `has_more=true` even when
there are exactly N dynamic groups. Widen the window or use `--exact-total`
to resolve that uncertainty.

### 4. Compare peak event gaps across metrics

Expand Down Expand Up @@ -283,7 +296,9 @@ 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`.
CTE `top_n` cap. Widen that template by increasing `top_n`, keeping `-n` at
least `top_n + 2` with static inclusion. Replace the previous ranked result;
do not concatenate or sum overlapping windows.

On `--json` failure, stdout is empty. stderr is:

Expand Down
14 changes: 10 additions & 4 deletions docs/en/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ The result contains:
| --- | --- |
| `total` | Matching-row `COUNT` when `exact_total=True`; otherwise the returned-row count |
| `returned` | Number of rows included in `rows` |
| `has_more` | True when a later page exists (extra-row probe on a trailing `LIMIT`, or a full inner `top_n` window) |
| `truncated` | True when this response is not the complete matching set |
| `has_more` | True when more rows exist, or conservatively when an inner `top_n` window is full (even if exactly N groups exist) |
| `truncated` | True when this response is incomplete or completeness is unconfirmed by a full inner ranking window |
| `total_is_exact` | True when `total` is a `COUNT`, or when the page is the complete matching set |
| `timeout_s` | Effective execution timeout in seconds, or `None` when unbounded |
| `device_id` | Device selected for execution |
Expand All @@ -193,8 +193,14 @@ is a wall-clock budget for one `execute_query()` call in seconds (or
`PT_SNAP_QUERY_TIMEOUT`); the page query and optional COUNT share it. The
same environment variable applies to every template query, including
`report peak-memory`. It does not change the row cap. Continue
`active_memory_callstack_at_event` by increasing `top_n`; `-n` cannot
raise that CTE cap.
`active_memory_callstack_at_event` by increasing `top_n`; `max_rows` (CLI `-n`)
cannot raise that CTE cap. For finite positive `top_n=N` with
`include_static=True`, set `max_rows=N+2` to retain up to two special groups
alongside the dynamic top N. This prevents outer truncation, not inner ranking
incompleteness. A full window alone does not prove more groups exist; widen it
or use `exact_total=True` to check. Replace earlier windows rather than summing
them. At fixed `top_n`, changing `max_rows` does not change common rows'
percentages; changing `top_n` can change their denominator.

Rows contain raw SQLite values. Template `output_schema` metadata is not applied
automatically; use the optional [ResultMapper API](result-mapper-api.md) when
Expand Down
18 changes: 15 additions & 3 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ pt-snap query --template-use active_blocks_at_event --params '{"event_id": 1234,
### 3. 对该时刻的活跃内存做调用栈归因

```bash
pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}'
pt-snap query --template-use active_memory_callstack_at_event --params '{"event_id": 1234, "include_static": true, "top_n": 20}' -n 22 --json
```

这个查询会:
Expand All @@ -175,7 +175,18 @@ pt-snap query --template-use active_memory_callstack_at_event --params '{"event_
- 按分配调用栈做聚合
- 对静态内存和 preexisting 内存单独分组,而不是伪造调用栈

`top_n` 只限制动态调用栈分组的数量;`static` 和 `preexisting_live_at_event` 分组始终返回,不会被更大的动态分组挤出结果。
`top_n` 只限制动态调用栈分组的数量;启用包含且实际存在的 `static` 和
`preexisting_live_at_event` 分组不受这层内部筛选限制。外层 `-n` 仍限制所有
输出行,可能裁掉特殊组或动态 top 组。对于有限正整数 `top_n=N` 且
`include_static=true`,使用 `-n N+2`(代入计算后的整数:`top_n=1` 配
`-n 3`,`top_n=20` 配 `-n 22`)。这只保证排名结果不被二次裁剪,不保证
动态全集完整。代表 block 查询有独立的 `limit` / `-n` 上限,不需要额外两行。

固定 `top_n` 时,增大 `-n` 不改变共有行及其百分比:分母是内部排名后、
外层行数截断前所包含分组的字节数。裁剪后的列表百分比之和可能不足 100%。
增大 `top_n` 则可能改变分母。宣称完整覆盖前应检查完整性标志;排名窗口已满
会保守地设置 `has_more=true`,即使动态组恰好只有 N 个。扩大窗口或使用
`--exact-total` 可消除这种不确定性。

### 4. 比较不同指标的峰值与 gap

Expand Down Expand Up @@ -260,7 +271,8 @@ QueryService 调用的共享预算(页面查询与可选 COUNT 共用),作
[完整候选窗口流程](#获取完整候选窗口)。增大 `-n` 是替换先前窗口,不是获取
不重叠的下一页。`has_more` 不代表支持 offset。
`active_memory_callstack_at_event` 没有 `offset`,`-n`
也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 续页。
也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 扩大窗口,并在包含静态组时
保持 `-n` 至少为 `top_n + 2`。新排名结果替换旧结果,不要拼接或累加重叠窗口。

`--json` 失败时 stdout 为空,stderr 为:

Expand Down
12 changes: 8 additions & 4 deletions docs/zh/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,8 @@ for row in result["rows"]:
| --- | --- |
| `total` | `exact_total=True` 时为匹配集合的 `COUNT`;否则等于已返回行数 |
| `returned` | `rows` 中实际返回的行数 |
| `has_more` | 还有后续页时为 true(尾部 `LIMIT` 多取一行,或内部 `top_n` 窗口已满) |
| `truncated` | 本次响应不是完整匹配集合时为 true |
| `has_more` | 存在更多行时为 true;内部 `top_n` 窗口已满时也会保守地设为 true(即使恰好只有 N 个组) |
| `truncated` | 本次响应不完整,或内部排名窗口已满而完整性未确认时为 true |
| `total_is_exact` | `total` 来自 `COUNT`,或本页就是完整匹配集合时为 true |
| `timeout_s` | 生效的执行超时秒数;未限制时为 `None` |
| `device_id` | 本次执行选择的设备 |
Expand All @@ -178,8 +178,12 @@ analyzer 设备;未设置显式 analyzer 数据库时,再使用已解析项
`execute_query()` 调用的墙钟预算(秒),也可由 `PT_SNAP_QUERY_TIMEOUT`
提供;页面查询与可选 COUNT 共用该预算。该环境变量作用于所有模板查询,
包括 `report peak-memory`。它不改变行数上限。
`active_memory_callstack_at_event` 应增大 `top_n` 续页,`-n` 无法突破
CTE 上限。
`active_memory_callstack_at_event` 应增大 `top_n` 扩大窗口,`max_rows`(CLI `-n`)
无法突破 CTE 上限。对于有限正整数 `top_n=N` 且 `include_static=True`,设置
`max_rows=N+2` 可在动态 top N 之外保留最多两个特殊组。这可避免外层二次截断,
但不保证内部排名完整。窗口已满本身不证明存在更多组;扩大窗口或使用
`exact_total=True` 可确认。新窗口替换旧窗口,不要累加。固定 `top_n` 时,
改变 `max_rows` 不改变共有行的百分比;改变 `top_n` 则可能改变分母。

查询行包含原始 SQLite 值,不会自动应用模板的 `output_schema` metadata。需要转换后的值
或模型映射时,使用可选的 [ResultMapper API](result-mapper-api.md)。
Expand Down
55 changes: 39 additions & 16 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,16 @@ Require one coherent database/device pair:

Also obtain:

- `<LIMIT>`: maximum callstack groups and representative blocks. Default to 20
only when the user has not requested another value.
- `<LIMIT>`: finite positive dynamic callstack group cap (`top_n`, or report
`--limit`). Default to 20 only when the user has not requested another value.
- `<GROUP_ROWS>`: total callstack query output row cap (`-n`). With
`include_static=true`, compute `<LIMIT> + 2` before command substitution to
reserve space for up to two special groups (20 dynamic groups → 22 rows;
1 dynamic group → 3 rows). This prevents outer truncation of the ranked result,
but does not guarantee that all dynamic groups fit within `top_n`.
- `<BLOCK_LIMIT>`: separate finite positive representative block cap (template
`limit` and `-n`). Default to 20 unless the user requests another value; the
callstack query's two extra rows do not apply to this block listing.
- `<METRIC>`: the metric whose event needs representative blocks. If the user
requests all three metrics, inspect each metric's own event.
- Optional inclusive `<START_ID>` and `<END_ID>` for a bounded event range.
Expand All @@ -46,9 +54,11 @@ observations.

Validate every value before substituting it into a command:

- `<DEVICE>`, `<LIMIT>`, `<START_ID>`, `<END_ID>`, and every `<EVENT_ID>` must
- `<DEVICE>`, `<LIMIT>`, `<GROUP_ROWS>`, `<BLOCK_LIMIT>`, `<START_ID>`, `<END_ID>`, and every `<EVENT_ID>` must
match `^[0-9]+$` after trimming whitespace. Reject any other value and ask the
user or the query output again.
- Require `<LIMIT>`, `<GROUP_ROWS>`, and `<BLOCK_LIMIT>` to be greater than zero.
Substitute the computed `<GROUP_ROWS>` as decimal digits, not shell arithmetic.
- Treat `<DB>` as an opaque filesystem path. Reject values containing quotes,
`$`, backticks, or other shell metacharacters instead of escaping them.
- Prefer argument-array execution where the host agent supports it; otherwise
Expand Down Expand Up @@ -192,12 +202,12 @@ Use `active_blocks_at_event` at the chosen metric's peak event, not at the end o
the trace and not at another metric's event:

```bash
pt-snap query "<DB>" --device <DEVICE> --template-use active_blocks_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "limit": <LIMIT>}' -n <LIMIT>
pt-snap query "<DB>" --device <DEVICE> --template-use active_blocks_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "limit": <BLOCK_LIMIT>}' -n <BLOCK_LIMIT> --json
```

If all three peaks need block examples, run this once per distinct metric event
and label the event/metric association. Reuse results when metrics share an
event. Prefer `--json`. Keep `<LIMIT>` and `-n` positive; if `has_more` or
event. Keep `<BLOCK_LIMIT>` and `-n` positive; if `has_more` or
`truncated` is true, do not treat the listing as complete. Default `total`
equals `returned` unless `--exact-total` is set.

Expand All @@ -221,14 +231,24 @@ Choose the requested metric's returned event, then run point-in-time
attribution there:

```bash
pt-snap query "<DB>" --device <DEVICE> --template-use active_memory_callstack_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "top_n": <LIMIT>}' -n <LIMIT>
pt-snap query "<DB>" --device <DEVICE> --template-use active_blocks_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "limit": <LIMIT>}' -n <LIMIT>
pt-snap query "<DB>" --device <DEVICE> --template-use active_memory_callstack_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "top_n": <LIMIT>}' -n <GROUP_ROWS> --json
pt-snap query "<DB>" --device <DEVICE> --template-use active_blocks_at_event --params '{"event_id": <EVENT_ID>, "include_static": true, "limit": <BLOCK_LIMIT>}' -n <BLOCK_LIMIT> --json
```

`active_memory_callstack_at_event` has no `offset`, and `-n` cannot raise the
CTE `top_n` cap. If `has_more` or `truncated` is true on that template,
increase `top_n` (keep `-n` at least as large) instead of treating the ranked
page as the full dynamic set.
CTE `top_n` cap. Check `has_more`, `truncated`, and `total_is_exact` after every
query. If completeness is unconfirmed, first ensure `-n` is at least `top_n + 2`
with static inclusion, then increase `top_n` and recompute `<GROUP_ROWS>` when
full dynamic coverage is needed. A full ranking window sets `has_more=true`
conservatively: it does not prove that more groups exist. Widen the window or
use `--exact-total` to resolve that uncertainty; a count equal to `returned`
can clear the signal. Each wider query replaces the earlier ranked window;
do not concatenate or sum overlapping results.

At fixed `top_n`, raising `-n` preserves common rows and their percentages.
The percentage denominator includes the inner-ranked groups before the outer
row cap, so a clipped listing need not sum to 100%. Increasing `top_n` can
change that denominator; do not carry percentages across ranking windows.

The selected event must be one returned by the bounded `memory_peak` and
`allocator_gap` results. The point-in-time queries do not accept range bounds;
Expand Down Expand Up @@ -266,10 +286,12 @@ their event ID carries the range selection forward.
treat those as unknown dynamic attribution rather than dropping them.
Use `category` to distinguish synthetic groups; a display label alone is not
a unique group identity (captured literal labels remain separate).
- The callstack template always returns `static` and
`preexisting_live_at_event` groups regardless of `top_n`; when dynamic groups
exceed `top_n`, the smallest dynamic groups are dropped while these special
groups remain in the output.
- With `include_static=true`, eligible `static` and
`preexisting_live_at_event` groups are exempt from the inner `top_n` filter.
This is not an exemption from the outer `-n` row cap, which can drop special
groups or dynamic top groups according to the final size ordering. Reserve
up to two extra output rows using `<GROUP_ROWS>`; absent special categories
are not fabricated.

### Claims

Expand All @@ -289,7 +311,8 @@ their event ID carries the range selection forward.
Return a concise report with these sections:

1. **Scope**: absolute SnapshotDB path, device, full trace or inclusive event
range, static inclusion, limit, and selected metric/event.
range, static inclusion, dynamic group cap, total group row cap,
representative block cap, completeness flags, and selected metric/event.
2. **Separate peaks**: active, allocated, and reserved values with each metric's
own earliest peak event ID.
3. **Same-event gaps**: counters and `reserved - active` / `reserved - allocated`
Expand Down Expand Up @@ -324,5 +347,5 @@ and do not run point-in-time attribution with a fabricated event ID.
callstack strings.
- Do not turn point-in-time active-block attribution into leak, fragmentation,
cache-ownership, or OOM root-cause claims.
- Keep listing queries bounded with `<LIMIT>` and `-n`. Prefer `--json` and do
- Keep listing queries bounded with their separate group/block caps and `-n`. Prefer `--json` and do
not treat a page as complete when `has_more` or `truncated` is true.
Loading
Loading