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
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,11 @@ group percentages use included bytes after filtering and ranking. See the

## Agent Skills

For long diagnostic stacks, opt into `stack_bytes` on `event` or
`active_memory_callstack_at_event`, or `report peak-memory --stack-bytes 256`.
See [compact callstack text](docs/en/querying.md#compact-callstack-text) for
identity, byte-budget metadata and full-text retrieval.

Install bundled diagnostic workflows with `pt-snap skill install`. Agent integration uses skills plus the CLI; there is no MCP server. See the [Agent Skills guide](docs/en/skills.md).

Ascend NPU capture can proceed without `pt-snap` when the host has loaded
Expand Down
4 changes: 4 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ included bytes 为分母。解读有上限的分组结果前,请参阅

## Agent Skills

诊断长调用栈时,可在 `event` 或 `active_memory_callstack_at_event` 上显式设置
`stack_bytes`,或使用 `report peak-memory --stack-bytes 256`。
身份、字节预算元数据及完整文本检索方式见[紧凑调用栈文本](docs/zh/querying.md#紧凑调用栈文本)。

使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。

宿主已加载 `pt-snap-ascend-npu-collect` 时,没有 `pt-snap` 也能进行昇腾 NPU 采集;
Expand Down
50 changes: 50 additions & 0 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,56 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--timeout` | Wall-clock budget for one `query` / `QueryService` call (page query and optional `--exact-total` COUNT share it) via a SQLite progress handler. `<= 0` disables. Default: `PT_SNAP_QUERY_TIMEOUT` or unlimited. The environment variable applies to every template query, including `report peak-memory`. |
| `--json` | Emit machine-readable JSON (execute, `--list`, and `--template-info`) |

## Compact callstack text

`event` and `active_memory_callstack_at_event` accept the explicit opt-in
`stack_bytes` parameter. `report peak-memory` accepts `--stack-bytes` for its
callstack groups. The default `-1` (or any negative value) preserves full text
and the existing row shape. `0` returns identity-only stack text; a positive
value returns a UTF-8-safe prefix of at most that many bytes per callstack.

```bash
pt-snap query '<db_path>' --device 0 --template-use event --params '{"action":0,"limit":1000,"stack_bytes":256}' --json
pt-snap query '<db_path>' --device 0 --template-use active_memory_callstack_at_event --params '{"event_id":100,"top_n":20,"stack_bytes":256}' --json
pt-snap report peak-memory '<db_path>' --device 0 --stack-bytes 256 --json
```

Replace the path, device and event with values from your database. The Python
API uses the same parameter through
`analyzer.execute_query("event", params={"stack_bytes": 256, "limit": 1000})`.
Discover support and field definitions through `capabilities --json` or template
info; other templates do not accept this parameter.

Each compact row adds `stack_id`, `stack_kind`, `stack_event_id`, `stack_bytes`
(effective budget), `stack_original_bytes` and `stack_truncated`. Numbers and
`category` remain unchanged. The budget applies only to the UTF-8 text value:
JSON escaping, identity and other metadata consume additional bytes. It is
neither a hard response-size cap nor a model-token budget. A short prefix may
end within a frame; retrieve full text before interpreting omitted frames.

`stack_truncated` signals **text shortening**, independently of the query's
`has_more`, `truncated`, `total` and `total_is_exact`, which still describe the
evidence row set. A complete row set can contain shortened text. Report row
limits retain their existing semantics; text summaries do not prove coverage.

Within the same unchanged database/device, use `stack_id` for identity: v1 uses
the SHA-256 of the full captured text; v2 uses the actual `callstackId` (identical
text can have different IDs). Missing, static and preexisting attribution use
separate category identities. Never merge groups by the prefix or display label.
`stack_kind` distinguishes captured text from synthetic/missing attribution.

For a captured stack, use its `stack_event_id` with the **same database/device**
and omit `stack_bytes` to retrieve the full text:

```bash
pt-snap query '<db_path>' --device 0 --template-use event --params '{"id":123}' --json
```

Replace `123` with the returned locator. This representative event is not the
group identity. Missing/static/preexisting groups have no captured allocation
stack to retrieve; omit `stack_bytes` on the original query to see their full
display labels. Results are read-only and summaries do not change the database.

## Query Templates

Templates are organized into three categories. Use `pt-snap capabilities --json` for the full catalog (CLI version, every template contract, and bundled skills), or `pt-snap query --list` to see names and descriptions. Filter with `--category`.
Expand Down
43 changes: 43 additions & 0 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,49 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--timeout` | 一次 `query` / `QueryService` 调用的墙钟预算(页面查询与可选 `--exact-total` COUNT 共用),经 SQLite progress handler 生效。`<= 0` 表示关闭。默认:`PT_SNAP_QUERY_TIMEOUT` 或不限制。该环境变量作用于所有模板查询,包括 `report peak-memory`。 |
| `--json` | 输出机器可读 JSON(执行、`--list` 与 `--template-info`) |

## 紧凑调用栈文本

`event` 和 `active_memory_callstack_at_event` 支持显式启用的 `stack_bytes`
参数;`report peak-memory` 可用 `--stack-bytes` 控制调用栈分组文本。
默认 `-1`(或任意负数)保留完整文本及原有行结构。`0` 仅保留栈身份信息,
正数返回不超过指定 UTF-8 字节数的有效文本前缀。

```bash
pt-snap query '<db_path>' --device 0 --template-use event --params '{"action":0,"limit":1000,"stack_bytes":256}' --json
pt-snap query '<db_path>' --device 0 --template-use active_memory_callstack_at_event --params '{"event_id":100,"top_n":20,"stack_bytes":256}' --json
pt-snap report peak-memory '<db_path>' --device 0 --stack-bytes 256 --json
```

请替换为数据库实际路径、设备与事件。Python API 使用相同参数:
`analyzer.execute_query("event", params={"stack_bytes": 256, "limit": 1000})`。
通过 `capabilities --json` 或模板详情确认支持情况和字段定义;其他模板不接受此参数。

每条紧凑行增加 `stack_id`、`stack_kind`、`stack_event_id`、`stack_bytes`
(生效预算)、`stack_original_bytes` 和 `stack_truncated`。数值与 `category`
保持不变。预算只限制 UTF-8 文本值;JSON 转义、身份及其他元数据会额外占用字节。
这既不是整包输出大小硬上限,也不是模型 token 预算。前缀可能在一帧中间结束,
解释被省略的帧前应取回完整文本。

`stack_truncated` 表示**文本缩略**,独立于查询的 `has_more`、`truncated`、
`total`、`total_is_exact`;后者仍描述证据行集合。完整行集合也可能包含缩略文本。
报告行数限制保留既有语义,文本摘要不能证明证据覆盖完整。

在同一未变化的数据库/设备内用 `stack_id` 判断身份:v1 使用完整采集文本的 SHA-256,
v2 使用真实 `callstackId`(相同文本可以有不同 ID)。missing、static、preexisting
归因分别使用独立分类身份。禁止按前缀或显示标签合并分组。
`stack_kind` 区分真实采集文本与合成/缺失归因。

对真实采集栈,在**同一数据库/设备**下使用返回的 `stack_event_id`,省略
`stack_bytes` 即可取回完整文本:

```bash
pt-snap query '<db_path>' --device 0 --template-use event --params '{"id":123}' --json
```

把 `123` 替换为返回的定位事件;此代表事件不是分组身份。missing/static/preexisting
分组没有可取回的采集分配栈;在原查询中省略 `stack_bytes` 可查看完整显示标签。
查询保持只读,摘要不会改动数据库。

## 查询模板

模板分为三个分类。用 `pt-snap capabilities --json` 一次查看完整清单(CLI 版本、全部模板契约和随包 skill),或用 `pt-snap query --list` 查看名称与描述。用 `--category` 过滤。
Expand Down
17 changes: 17 additions & 0 deletions skills/pt-snap-memory-fragmentation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,23 @@ Stop the report phase and report the exact failure if it fails or the options
used below are absent. A complete successful help result from the same
CLI/Python environment and version may be reused.

## Optional compact stack evidence

When long stacks dominate output bytes, confirm `stack_bytes` in the catalog
for `event` / `active_memory_callstack_at_event` and `--stack-bytes` in report
help. Opt into `stack_bytes: 256` on those queries or `--stack-bytes 256` on
reports. Other templates do not support it. Retain `stack_id`, `stack_kind`,
`stack_event_id`, `stack_bytes`, `stack_original_bytes`, `stack_truncated`,
category, numbers and completeness. The budget is UTF-8 text bytes, not model
tokens or a hard JSON response cap. Text shortening is distinct from row
truncation; continue checking `has_more`, `truncated` and `total_is_exact`.
Never merge groups by shortened text or synthetic labels: equal v2 text can
have distinct IDs. Retrieve a captured stack through `event(id=stack_event_id)`
without `stack_bytes`, on the same unchanged database/device. Check that event
contract first; missing/static/preexisting groups have no captured allocation
stack. Reuse shared-event attribution only in presentation while preserving
each metric's counters, identities and completeness evidence.

## Diagnostic Workflow

### 1. Establish separate peaks and same-event gaps
Expand Down
16 changes: 16 additions & 0 deletions skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,22 @@ target's overview or device.

Confirm these templates exist in the capabilities catalog before diagnosis: `memory_peak`, `allocator_gap`, `event`, `block`, `leak_detection`, `active_memory_callstack_at_event`, `active_blocks_at_event`, `preexisting_live`, `freed_block_lifetime`. If the catalog or overview fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template.

## Optional compact stack evidence

For long stack text, check the capabilities catalog for `stack_bytes` on `event`
or `active_memory_callstack_at_event` before adding `stack_bytes: 256` to their
params. This is not a `leak_detection` parameter. Retain `stack_id`, `stack_kind`,
`stack_event_id`, effective `stack_bytes`, `stack_original_bytes`,
`stack_truncated`, category, numbers and completeness. UTF-8 text bytes are not
model tokens or a hard JSON response cap. Text shortening does not change
`has_more`, `truncated` or `total_is_exact` and does not complete a ranked window.
Never merge groups by shortened text: equal v2 text may have distinct IDs and
captured text may match synthetic labels. Retrieve full captured text with the
catalog's `event` query using `id=stack_event_id`, omit `stack_bytes`, and keep
the same unchanged database/device. Missing/static/preexisting groups have no
captured allocation stack. Keep per-block `(id, allocEventId)` matching for
survival evidence; a stack identity is not a block identity.

## Diagnostic Workflow

### 1. Establish trace boundaries and memory peaks
Expand Down
20 changes: 20 additions & 0 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,26 @@ Stop and report the exact failure if it fails or the options used below are
absent. A complete successful help result from the same CLI/Python environment
and version may be reused.

## Optional compact stack evidence

When long stacks dominate output bytes, first confirm `stack_bytes` in the
catalog for `event` / `active_memory_callstack_at_event` and `--stack-bytes` in
report help. Opt into `stack_bytes: 256` in those query params or append
`--stack-bytes 256` to a report. Other templates do not support this parameter.
Keep `stack_id`, `stack_kind`, `stack_event_id`, effective `stack_bytes`,
`stack_original_bytes`, `stack_truncated`, category, numbers and completeness
in the evidence. UTF-8 bytes are not model tokens or a hard JSON response cap.
`stack_truncated` describes text shortening, not dropped evidence rows; a row
cap and `has_more` / `truncated` must still be checked separately.

Never identify or merge groups by shortened text: v2 IDs can differ even for
identical text, and synthetic labels can match captured text. For a captured
stack, retrieve full text via `event` with `id` equal to `stack_event_id`, omit
`stack_bytes`, and use the same unchanged database/device. Check the event
contract before retrieval; missing/static/preexisting attribution has no captured
allocation stack. Keep these identities even when presenting a shared event's
attribution once for multiple metrics; retain each metric's counters and gaps.

## Full-Trace Workflow

`pt-snap report peak-memory` is full-trace only. Run it once for each metric so
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,23 @@ Stop the report phase and report the exact failure if it fails or the options
used below are absent. A complete successful help result from the same
CLI/Python environment and version may be reused.

## Optional compact stack evidence

When long stacks dominate output bytes, confirm `stack_bytes` in the catalog
for `event` / `active_memory_callstack_at_event` and `--stack-bytes` in report
help. Opt into `stack_bytes: 256` on those queries or `--stack-bytes 256` on
reports. Other templates do not support it. Retain `stack_id`, `stack_kind`,
`stack_event_id`, `stack_bytes`, `stack_original_bytes`, `stack_truncated`,
category, numbers and completeness. The budget is UTF-8 text bytes, not model
tokens or a hard JSON response cap. Text shortening is distinct from row
truncation; continue checking `has_more`, `truncated` and `total_is_exact`.
Never merge groups by shortened text or synthetic labels: equal v2 text can
have distinct IDs. Retrieve a captured stack through `event(id=stack_event_id)`
without `stack_bytes`, on the same unchanged database/device. Check that event
contract first; missing/static/preexisting groups have no captured allocation
stack. Reuse shared-event attribution only in presentation while preserving
each metric's counters, identities and completeness evidence.

## Diagnostic Workflow

### 1. Establish separate peaks and same-event gaps
Expand Down
16 changes: 16 additions & 0 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 @@ -100,6 +100,22 @@ target's overview or device.

Confirm these templates exist in the capabilities catalog before diagnosis: `memory_peak`, `allocator_gap`, `event`, `block`, `leak_detection`, `active_memory_callstack_at_event`, `active_blocks_at_event`, `preexisting_live`, `freed_block_lifetime`. If the catalog or overview fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template.

## Optional compact stack evidence

For long stack text, check the capabilities catalog for `stack_bytes` on `event`
or `active_memory_callstack_at_event` before adding `stack_bytes: 256` to their
params. This is not a `leak_detection` parameter. Retain `stack_id`, `stack_kind`,
`stack_event_id`, effective `stack_bytes`, `stack_original_bytes`,
`stack_truncated`, category, numbers and completeness. UTF-8 text bytes are not
model tokens or a hard JSON response cap. Text shortening does not change
`has_more`, `truncated` or `total_is_exact` and does not complete a ranked window.
Never merge groups by shortened text: equal v2 text may have distinct IDs and
captured text may match synthetic labels. Retrieve full captured text with the
catalog's `event` query using `id=stack_event_id`, omit `stack_bytes`, and keep
the same unchanged database/device. Missing/static/preexisting groups have no
captured allocation stack. Keep per-block `(id, allocEventId)` matching for
survival evidence; a stack identity is not a block identity.

## Diagnostic Workflow

### 1. Establish trace boundaries and memory peaks
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,26 @@ Stop and report the exact failure if it fails or the options used below are
absent. A complete successful help result from the same CLI/Python environment
and version may be reused.

## Optional compact stack evidence

When long stacks dominate output bytes, first confirm `stack_bytes` in the
catalog for `event` / `active_memory_callstack_at_event` and `--stack-bytes` in
report help. Opt into `stack_bytes: 256` in those query params or append
`--stack-bytes 256` to a report. Other templates do not support this parameter.
Keep `stack_id`, `stack_kind`, `stack_event_id`, effective `stack_bytes`,
`stack_original_bytes`, `stack_truncated`, category, numbers and completeness
in the evidence. UTF-8 bytes are not model tokens or a hard JSON response cap.
`stack_truncated` describes text shortening, not dropped evidence rows; a row
cap and `has_more` / `truncated` must still be checked separately.

Never identify or merge groups by shortened text: v2 IDs can differ even for
identical text, and synthetic labels can match captured text. For a captured
stack, retrieve full text via `event` with `id` equal to `stack_event_id`, omit
`stack_bytes`, and use the same unchanged database/device. Check the event
contract before retrieval; missing/static/preexisting attribution has no captured
allocation stack. Keep these identities even when presenting a shared event's
attribution once for multiple metrics; retain each metric's counters and gaps.

## Full-Trace Workflow

`pt-snap report peak-memory` is full-trace only. Run it once for each metric so
Expand Down
12 changes: 12 additions & 0 deletions src/pt_snap_cli/cli_output.py
Original file line number Diff line number Diff line change
Expand Up @@ -142,19 +142,19 @@
else:
typer.echo(" Attribution: complete for the effective filters.")
typer.echo(
f" Parameters: include_static={report.effective_params.get('include_static')}, "

Check warning on line 145 in src/pt_snap_cli/cli_output.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Implicit string concatenation not allowed (reportImplicitStringConcatenation)
f"min_size={report.effective_params.get('min_size')}, "
f"top_n={report.effective_params.get('top_n')}"
)
typer.echo(
f" Percentage denominator: {report.percent_denominator}={report.included_bytes} bytes "

Check warning on line 150 in src/pt_snap_cli/cli_output.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Implicit string concatenation not allowed (reportImplicitStringConcatenation)
"(included groups after filtering/top_n; not all active memory or block counts)."
)
coverage = (
f"{report.coverage_percent:.4f}%" if report.coverage_percent is not None else "unknown"
)
typer.echo(
f" Active coverage at event {report.event_id}: {coverage} "

Check warning on line 157 in src/pt_snap_cli/cli_output.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Implicit string concatenation not allowed (reportImplicitStringConcatenation)
f"(included={report.included_bytes} bytes, active={report.active_bytes_at_event} bytes)."
)
if not report.callstack_groups:
Expand All @@ -165,6 +165,18 @@
f" [{index}] {row.get('category')} {row.get('size_bytes')} bytes, {row.get('block_count')} blocks ({row.get('percent_of_active_blocks')}%)"
)
typer.echo(f" {row.get('callstack')}")
if "stack_id" in row:
typer.echo(
f" stack_id={row['stack_id']} kind={row.get('stack_kind')} "

Check warning on line 170 in src/pt_snap_cli/cli_output.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Implicit string concatenation not allowed (reportImplicitStringConcatenation)
f"stack_truncated={row.get('stack_truncated')} "
f"stack_bytes={row.get('stack_bytes')} "
f"stack_original_bytes={row.get('stack_original_bytes')}"
)
if row.get("stack_kind") == "captured":
typer.echo(
" Full text: query event with "

Check warning on line 177 in src/pt_snap_cli/cli_output.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Implicit string concatenation not allowed (reportImplicitStringConcatenation)
f"id={row.get('stack_event_id')}, omit stack_bytes, same database/device."
)


def print_skill_listings(listings: list[SkillListing]) -> None:
Expand Down
8 changes: 8 additions & 0 deletions src/pt_snap_cli/cli_reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,13 @@ def report_peak_memory(
"--limit", "-n", help="Maximum dynamic callstack groups (static/preexisting are extra)"
),
] = 20,
stack_bytes: Annotated[
int,
typer.Option(
"--stack-bytes",
help="Opt-in UTF-8 byte budget per callstack (0: identity only; negative: full text). Not a response byte cap or token budget.",
),
] = -1,
json_output: Annotated[bool, _json_flag()] = False,
) -> None:
"""Generate a peak memory attribution report."""
Expand All @@ -76,6 +83,7 @@ def report_peak_memory(
metric=metric,
include_static=include_static,
limit=limit,
stack_bytes=stack_bytes,
)
except ValueError as e:
_error(str(e), code=INVALID_PARAMETER, hint="Use --metric active, allocated, or reserved.")
Expand Down
5 changes: 5 additions & 0 deletions src/pt_snap_cli/core/query_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
)
from pt_snap_cli.core.focus_service import FocusService
from pt_snap_cli.core.models import QueryResult, TemplateInfo, TemplateParameter, TemplateSummary
from pt_snap_cli.core.stack_summary import summarize_stacks
from pt_snap_cli.query.executor import QueryExecutionError as ExecutorQueryExecutionError
from pt_snap_cli.query.executor import QueryExecutor
from pt_snap_cli.query.executor import QueryTimeoutError as ExecutorQueryTimeoutError
Expand Down Expand Up @@ -255,6 +256,10 @@ def execute_query(
raise QueryExecutionError(str(exc)) from exc

template_obj = get_query(template)
if template_obj is not None and "stack_bytes" in template_obj.parameters:
stack_bytes = template_obj.validate_params(query_params)["stack_bytes"]
if isinstance(stack_bytes, int) and stack_bytes >= 0:
summarize_stacks(rows, stack_bytes, ctx.callstack_layout)
return QueryResult(
total=total,
returned=returned,
Expand Down
Loading
Loading