From b807fab6cbe2b9b42b1a53580d07d20e4823667f Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 3 Oct 2026 22:02:19 +0800 Subject: [PATCH 1/2] feat(queries): add opt-in callstack byte-budget summaries --- README.md | 5 + README_zh.md | 4 + docs/en/querying.md | 50 ++++ docs/zh/querying.md | 43 ++++ skills/pt-snap-memory-fragmentation/SKILL.md | 17 ++ skills/pt-snap-memory-leak/SKILL.md | 16 ++ skills/pt-snap-memory-peak-breakdown/SKILL.md | 20 ++ .../pt-snap-memory-fragmentation/SKILL.md | 17 ++ .../pt-snap-memory-leak/SKILL.md | 16 ++ .../pt-snap-memory-peak-breakdown/SKILL.md | 20 ++ src/pt_snap_cli/cli_output.py | 12 + src/pt_snap_cli/cli_reports.py | 8 + src/pt_snap_cli/core/query_service.py | 5 + src/pt_snap_cli/core/report_service.py | 2 + src/pt_snap_cli/core/stack_summary.py | 33 +++ .../query/templates/basic/event.yaml | 41 ++++ .../active_memory_callstack_at_event.yaml | 53 +++++ tests/query/test_stack_summary.py | 225 ++++++++++++++++++ tests/test_contract_cli_api.py | 50 ++++ 19 files changed, 637 insertions(+) create mode 100644 src/pt_snap_cli/core/stack_summary.py create mode 100644 tests/query/test_stack_summary.py diff --git a/README.md b/README.md index eb903e5..2f28e83 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README_zh.md b/README_zh.md index dccdcba..264544d 100644 --- a/README_zh.md +++ b/README_zh.md @@ -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 采集; diff --git a/docs/en/querying.md b/docs/en/querying.md index e82512e..074496f 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -28,6 +28,56 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ | `--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 '' --device 0 --template-use event --params '{"action":0,"limit":1000,"stack_bytes":256}' --json +pt-snap query '' --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 '' --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 '' --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`. diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 8caed81..6ad5ad8 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -28,6 +28,49 @@ pt-snap query [DB_PATH] [--template-use ] [--params ] \ | `--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 '' --device 0 --template-use event --params '{"action":0,"limit":1000,"stack_bytes":256}' --json +pt-snap query '' --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 '' --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 '' --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` 过滤。 diff --git a/skills/pt-snap-memory-fragmentation/SKILL.md b/skills/pt-snap-memory-fragmentation/SKILL.md index 5dff8be..0aba201 100644 --- a/skills/pt-snap-memory-fragmentation/SKILL.md +++ b/skills/pt-snap-memory-fragmentation/SKILL.md @@ -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 diff --git a/skills/pt-snap-memory-leak/SKILL.md b/skills/pt-snap-memory-leak/SKILL.md index 74ac545..0ef7176 100644 --- a/skills/pt-snap-memory-leak/SKILL.md +++ b/skills/pt-snap-memory-leak/SKILL.md @@ -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 diff --git a/skills/pt-snap-memory-peak-breakdown/SKILL.md b/skills/pt-snap-memory-peak-breakdown/SKILL.md index 6b937ba..8267c8b 100644 --- a/skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -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 diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-fragmentation/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-fragmentation/SKILL.md index 5dff8be..0aba201 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-fragmentation/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-fragmentation/SKILL.md @@ -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 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 74ac545..0ef7176 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 @@ -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 diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md index 6b937ba..8267c8b 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -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 diff --git a/src/pt_snap_cli/cli_output.py b/src/pt_snap_cli/cli_output.py index 375d8ad..92994ec 100644 --- a/src/pt_snap_cli/cli_output.py +++ b/src/pt_snap_cli/cli_output.py @@ -165,6 +165,18 @@ def print_peak_memory_report(report: PeakMemoryReport) -> None: 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')} " + 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 " + f"id={row.get('stack_event_id')}, omit stack_bytes, same database/device." + ) def print_skill_listings(listings: list[SkillListing]) -> None: diff --git a/src/pt_snap_cli/cli_reports.py b/src/pt_snap_cli/cli_reports.py index 7e384fe..b9abd25 100644 --- a/src/pt_snap_cli/cli_reports.py +++ b/src/pt_snap_cli/cli_reports.py @@ -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.""" @@ -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.") diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index a2b9d6e..d0ff782 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -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 @@ -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, diff --git a/src/pt_snap_cli/core/report_service.py b/src/pt_snap_cli/core/report_service.py index f618f84..7761eb7 100644 --- a/src/pt_snap_cli/core/report_service.py +++ b/src/pt_snap_cli/core/report_service.py @@ -39,6 +39,7 @@ def peak_memory_report( include_static: bool = True, limit: int = 20, start_dir: Path | None = None, + stack_bytes: int = -1, ) -> PeakMemoryReport: if metric not in _EVENT_ID_BY_METRIC: raise ValueError( @@ -59,6 +60,7 @@ def peak_memory_report( "include_static": include_static, "min_size": 0, "top_n": limit, + **({"stack_bytes": stack_bytes} if stack_bytes >= 0 else {}), } if event_id is None: diff --git a/src/pt_snap_cli/core/stack_summary.py b/src/pt_snap_cli/core/stack_summary.py new file mode 100644 index 0000000..1667f72 --- /dev/null +++ b/src/pt_snap_cli/core/stack_summary.py @@ -0,0 +1,33 @@ +"""Opt-in text summaries; row selection and attribution are left intact.""" + +from __future__ import annotations + +import hashlib + + +def summarize_stacks(rows: list[dict[str, object]], budget: int, layout: str | None) -> None: + """Summarize each stack in place using UTF-8 bytes, not model tokens. + + SQL supplies the attribution kind, v2 ID and a representative event before + display text is shortened. IDs are scoped to the same database/device. + v1 groups by full text; v2 must never be identified by a text digest. + """ + for row in rows: + text = row.get("callstack") + kind = row["stack_kind"] + if kind == "captured": + if layout == "v2": + row["stack_id"] = f"v2:id:{row['stack_id']}" + else: + assert isinstance(text, str) + row["stack_id"] = "v1:sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest() + else: + row["stack_id"] = f"category:{kind}" + encoded = text.encode("utf-8") if isinstance(text, str) else b"" + row["stack_bytes"] = budget + row["stack_original_bytes"] = len(encoded) + row["stack_truncated"] = len(encoded) > budget + if len(encoded) > budget: + # Dropping an incomplete final code point preserves valid Unicode. + # No ellipsis is appended: the flag, not an ambiguous label, marks loss. + row["callstack"] = encoded[:budget].decode("utf-8", errors="ignore") diff --git a/src/pt_snap_cli/query/templates/basic/event.yaml b/src/pt_snap_cli/query/templates/basic/event.yaml index 97e1c3d..9b4b9e0 100644 --- a/src/pt_snap_cli/query/templates/basic/event.yaml +++ b/src/pt_snap_cli/query/templates/basic/event.yaml @@ -5,6 +5,11 @@ queries: devices: - all parameters: + stack_bytes: + type: int + default: -1 + required: false + description: "Opt-in UTF-8 byte budget per callstack text (0 for identity only; negative for unchanged full output). Not a JSON byte cap or token budget. Summary fields are present only when enabled." id: type: int default: null @@ -89,6 +94,11 @@ queries: active, reserved, callstack + {% if stack_bytes >= 0 %} + , NULL AS stack_id, + CASE WHEN NULLIF(callstack, '') IS NULL THEN 'missing' ELSE 'captured' END AS stack_kind, + CASE WHEN NULLIF(callstack, '') IS NOT NULL THEN id END AS stack_event_id + {% endif %} FROM {{ device_trace_table }} WHERE 1=1 {% if id is not none %}AND id = {{ id }}{% endif %} @@ -118,6 +128,11 @@ queries: SELECT callstack FROM callstack WHERE callstack.id = {{ device_trace_table }}.callstackId ) AS callstack + {% if stack_bytes >= 0 %} + , callstackId AS stack_id, + CASE WHEN NULLIF((SELECT callstack FROM callstack WHERE callstack.id = {{ device_trace_table }}.callstackId), '') IS NULL THEN 'missing' ELSE 'captured' END AS stack_kind, + id AS stack_event_id + {% endif %} FROM {{ device_trace_table }} WHERE 1=1 {% if id is not none %}AND id = {{ id }}{% endif %} @@ -152,3 +167,29 @@ queries: type: int - column: callstack type: str + - column: stack_id + type: str + interpretation_limits: + - "Opt-in stack_bytes >= 0 only. Database/device-scoped identity: v1 full-text SHA-256, v2 callstackId, or a distinct category identity for missing attribution. Never merge by shortened callstack text." + - column: stack_kind + type: str + interpretation_limits: + - "Opt-in only: captured or missing. Empty/NULL or absent joined stacks are missing; whitespace and literal synthetic-looking labels remain captured." + - column: stack_event_id + type: int + interpretation_limits: + - "Opt-in only. Retrieve full captured text with event(id=stack_event_id), omitting stack_bytes, on the same database/device." + - column: stack_bytes + type: int + units: bytes + interpretation_limits: + - "Opt-in only. Effective UTF-8 byte budget per callstack value, excluding JSON escaping and metadata; not a whole-response cap or model-token count." + - column: stack_original_bytes + type: int + units: bytes + interpretation_limits: + - "Opt-in only. Original UTF-8 callstack text length before shortening." + - column: stack_truncated + type: bool + interpretation_limits: + - "Opt-in only. Text was shortened; independent of result truncated/has_more/total_is_exact, which describe evidence rows." diff --git a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml index 275a281..baf0eac 100644 --- a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml +++ b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml @@ -12,6 +12,11 @@ queries: - "Missing dynamic callstacks form one group before top_n ranking. This includes empty strings, NULL text or IDs, and missing joined allocation events or callstack records; their category remains dynamic_live_at_event." - "Event IDs are ordering markers, not elapsed time." parameters: + stack_bytes: + type: int + default: -1 + required: false + description: "Opt-in UTF-8 byte budget per callstack text (0 for identity only; negative for unchanged full output). Not a JSON byte cap or token budget. Summary fields are present only when enabled." event_id: type: int required: true @@ -58,6 +63,13 @@ queries: WHEN b.category = 'preexisting_live_at_event' THEN '[preexisting live] allocEventId=-1' ELSE COALESCE(NULLIF(t.callstack, ''), '[missing callstack]') END AS callstack, + {% if stack_bytes >= 0 %} + NULL AS stack_id, + CASE WHEN b.category != 'dynamic_live_at_event' THEN b.category + WHEN NULLIF(t.callstack, '') IS NULL THEN 'missing' + ELSE 'captured' END AS stack_kind, + CASE WHEN b.category = 'dynamic_live_at_event' AND NULLIF(t.callstack, '') IS NOT NULL THEN MIN(t.id) END AS stack_event_id, + {% endif %} b.category, COUNT(*) AS block_count, SUM(b.size) AS size_bytes, @@ -72,6 +84,7 @@ queries: ranked_dynamic AS ( SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -85,6 +98,7 @@ queries: ) SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -95,6 +109,7 @@ queries: FROM ( SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -106,6 +121,7 @@ queries: UNION ALL SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -141,6 +157,13 @@ queries: WHEN b.category = 'preexisting_live_at_event' THEN '[preexisting live] allocEventId=-1' ELSE COALESCE(NULLIF(cs.callstack, ''), '[missing callstack]') END AS callstack, + {% if stack_bytes >= 0 %} + CASE WHEN b.category = 'dynamic_live_at_event' AND NULLIF(cs.callstack, '') IS NOT NULL THEN t.callstackId END AS stack_id, + CASE WHEN b.category != 'dynamic_live_at_event' THEN b.category + WHEN NULLIF(cs.callstack, '') IS NULL THEN 'missing' + ELSE 'captured' END AS stack_kind, + CASE WHEN b.category = 'dynamic_live_at_event' AND NULLIF(cs.callstack, '') IS NOT NULL THEN MIN(t.id) END AS stack_event_id, + {% endif %} b.category, COUNT(*) AS block_count, SUM(b.size) AS size_bytes, @@ -159,6 +182,7 @@ queries: ranked_dynamic AS ( SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -172,6 +196,7 @@ queries: ) SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -182,6 +207,7 @@ queries: FROM ( SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -193,6 +219,7 @@ queries: UNION ALL SELECT callstack, + {% if stack_bytes >= 0 %}stack_id, stack_kind, stack_event_id,{% endif %} category, block_count, size_bytes, @@ -203,6 +230,32 @@ queries: ) ORDER BY size_bytes DESC, block_count DESC, callstack ASC output_schema: + - column: stack_id + type: str + interpretation_limits: + - "Opt-in stack_bytes >= 0 only. Database/device-scoped identity: v1 full-text SHA-256, v2 callstackId, or category identity. Missing, static, preexisting and captured literal labels stay distinct. Never merge by display text." + - column: stack_kind + type: str + interpretation_limits: + - "Opt-in only: captured, missing, static, or preexisting_live_at_event." + - column: stack_event_id + type: int + interpretation_limits: + - "Opt-in only. Representative captured allocation event; retrieve full text with event(id=stack_event_id), omitting stack_bytes, on the same database/device. NULL for synthetic/missing groups. This locator is not the group identity." + - column: stack_bytes + type: int + units: bytes + interpretation_limits: + - "Opt-in only. Effective UTF-8 byte budget per callstack value, excluding JSON escaping and metadata; not a whole-response cap or model-token count." + - column: stack_original_bytes + type: int + units: bytes + interpretation_limits: + - "Opt-in only. Original UTF-8 callstack text length before shortening." + - column: stack_truncated + type: bool + interpretation_limits: + - "Opt-in only. Text was shortened; evidence rows, numbers, categories and completeness flags are unchanged." - column: callstack type: str units: text diff --git a/tests/query/test_stack_summary.py b/tests/query/test_stack_summary.py new file mode 100644 index 0000000..39f7649 --- /dev/null +++ b/tests/query/test_stack_summary.py @@ -0,0 +1,225 @@ +"""Compact text must not compact evidence or collapse attribution identities.""" + +from __future__ import annotations + +import json +import sqlite3 +from contextlib import closing +from dataclasses import asdict +from pathlib import Path + +import pytest +from typer.testing import CliRunner + +from pt_snap_cli.cli import app +from pt_snap_cli.core.query_service import QueryService +from pt_snap_cli.core.report_service import ReportService +from pt_snap_cli.query.registry import QueryRegistry, _load_all_templates + +LONG_STACK = '训练.py:12 forward("模型🚀")\n' * 800 + + +@pytest.fixture(autouse=True) +def isolated(tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("PT_SNAP_DB_PATH", raising=False) + monkeypatch.setattr(Path, "home", lambda: tmp_path) + QueryRegistry.reset() + _load_all_templates() + yield + QueryRegistry.reset() + _load_all_templates() + + +@pytest.fixture(params=["v1", "v2"]) +def stack_db(tmp_path, request): + layout = request.param + path = tmp_path / f"{layout}.db" + texts = [LONG_STACK, LONG_STACK, "[missing callstack]", " ", "", None] + with closing(sqlite3.connect(path)) as conn, conn: + conn.execute("CREATE TABLE dictionary (`table`, `column`, `key`, `value`)") + column = "callstack TEXT" if layout == "v1" else "callstackId INTEGER" + conn.execute( + "CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY, action INTEGER, " + "address INTEGER, size INTEGER, stream INTEGER, allocated INTEGER, " + f"active INTEGER, reserved INTEGER, {column})" + ) + if layout == "v2": + conn.execute("CREATE TABLE callstack (id INTEGER PRIMARY KEY, callstack TEXT)") + conn.executemany("INSERT INTO callstack VALUES (?, ?)", enumerate(texts, 1)) + for index, text in enumerate(texts + [None, None], 1): + # 7: dangling callstack ID; 8: NULL ID; both are missing attribution. + value = text if layout == "v1" else (index if index < 8 else None) + conn.execute( + "INSERT INTO trace_entry_0 VALUES (?, 4, ?, 100, 0, ?, ?, 10000, ?)", + (index, index * 4096, index * 100, index * 100, value), + ) + conn.execute( + "CREATE TABLE block_0 (id INTEGER PRIMARY KEY, address INTEGER, " + "size INTEGER, requestedSize INTEGER, state INTEGER, " + "allocEventId INTEGER, freeEventId INTEGER)" + ) + conn.executemany( + "INSERT INTO block_0 VALUES (?, ?, ?, ?, 1, ?, ?)", + [(i, i * 4096, i * 100, i * 90, i, -1) for i in range(1, 10)] + + [(10, 40960, 1000, 900, -1, -1), (11, 45056, 1100, 990, -1, 1000)], + ) + return path, layout + + +@pytest.mark.parametrize("budget", [0, 1, 7, 256]) +@pytest.mark.parametrize( + "template,params", + [("event", {}), ("active_memory_callstack_at_event", {"event_id": 100, "top_n": -1})], +) +def test_summary_preserves_evidence_and_full_retrieval(stack_db, budget, template, params): + path, layout = stack_db + service = QueryService() + try: + full = service.execute_query(template, params, db_path=path, device_id=0) + compact = service.execute_query( + template, {**params, "stack_bytes": budget}, db_path=path, device_id=0 + ) + assert {k: v for k, v in asdict(full).items() if k != "rows"} == { + k: v for k, v in asdict(compact).items() if k != "rows" + } + for original, summary in zip(full.rows, compact.rows, strict=True): + assert { + k: v for k, v in summary.items() if not k.startswith("stack_") and k != "callstack" + } == {k: v for k, v in original.items() if k != "callstack"} + assert not any(k.startswith("stack_") for k in original) + text = original["callstack"] + original_bytes = len(text.encode("utf-8")) if text is not None else 0 + assert summary["stack_original_bytes"] == original_bytes + assert summary["stack_bytes"] == budget + assert summary["stack_truncated"] == (original_bytes > budget) + assert len((summary["callstack"] or "").encode("utf-8")) <= budget + assert "�" not in (summary["callstack"] or "") + if summary["stack_kind"] == "captured": + fetched = service.execute_query( + "event", {"id": summary["stack_event_id"]}, db_path=path, device_id=0 + ).rows[0] + assert fetched["callstack"] == text + assert summary["stack_id"].startswith(layout + ":") + assert len(json.dumps(compact.rows).encode()) < len(json.dumps(full.rows).encode()) / 10 + finally: + service.close() + + +def test_group_identity_includes_layout_id_and_special_categories(stack_db): + path, layout = stack_db + service = QueryService() + try: + groups = service.execute_query( + "active_memory_callstack_at_event", + {"event_id": 100, "top_n": -1, "stack_bytes": 256}, + db_path=path, + device_id=0, + ).rows + assert len({g["stack_id"] for g in groups}) == len(groups) + assert {g["stack_kind"] for g in groups} == { + "captured", + "missing", + "static", + "preexisting_live_at_event", + } + long_groups = [g for g in groups if g["stack_original_bytes"] == len(LONG_STACK.encode())] + assert len(long_groups) == (1 if layout == "v1" else 2) + if layout == "v2": + assert {g["stack_id"] for g in long_groups} == {"v2:id:1", "v2:id:2"} + same_labels = [g for g in groups if g["callstack"] == "[missing callstack]"] + assert len(same_labels) == 2 + assert {g["stack_kind"] for g in same_labels} == {"captured", "missing"} + missing = next(g for g in same_labels if g["stack_kind"] == "missing") + assert missing["block_count"] == 5 # empty, NULL text, dangling/NULL IDs, absent event + assert missing["stack_event_id"] is None + finally: + service.close() + + +@pytest.mark.parametrize("exact_total", [False, True]) +@pytest.mark.parametrize( + "template,params", + [ + ("event", {"limit": 3, "offset": 1}), + ("active_memory_callstack_at_event", {"event_id": 100, "top_n": 2}), + ], +) +def test_summary_preserves_incomplete_windows(stack_db, exact_total, template, params): + path, _ = stack_db + service = QueryService() + try: + full = service.execute_query( + template, params, db_path=path, max_rows=2, exact_total=exact_total + ) + compact = service.execute_query( + template, + {**params, "stack_bytes": 0}, + db_path=path, + max_rows=2, + exact_total=exact_total, + ) + assert compact.truncated + assert {k: v for k, v in asdict(full).items() if k != "rows"} == { + k: v for k, v in asdict(compact).items() if k != "rows" + } + finally: + service.close() + + +@pytest.mark.parametrize("metric", ["active", "allocated", "reserved"]) +def test_report_uses_shared_summary_and_exposes_text_markers(stack_db, metric): + path, _ = stack_db + service = ReportService() + try: + full = asdict(service.peak_memory_report(path, device_id=0, metric=metric)) + compact = asdict( + service.peak_memory_report(path, device_id=0, metric=metric, stack_bytes=7) + ) + assert {k: v for k, v in compact.items() if k != "callstack_groups"} == { + k: v for k, v in full.items() if k != "callstack_groups" + } + args = [ + "report", + "peak-memory", + str(path), + "--device", + "0", + "--metric", + metric, + "--stack-bytes", + "7", + ] + result = CliRunner().invoke(app, args + ["--json"]) + assert result.exit_code == 0, result.output + assert json.loads(result.output) == compact + text = CliRunner().invoke(app, args) + assert text.exit_code == 0, text.output + assert "stack_truncated=True" in text.output + assert "stack_bytes=7" in text.output + assert "Full text: query event" in text.output + finally: + service.close() + + +def test_332_long_events_reduce_bytes_without_dropping_rows(stack_db): + path, layout = stack_db + with closing(sqlite3.connect(path)) as conn, conn: + conn.executemany( + "INSERT INTO trace_entry_0 VALUES (?, 0, 0, 4096, 0, 0, 0, 4096, ?)", + [(i, LONG_STACK if layout == "v1" else 1) for i in range(100, 432)], + ) + service = QueryService() + try: + full = service.execute_query("event", {"action": 0, "limit": 1000}, db_path=path) + compact = service.execute_query( + "event", {"action": 0, "limit": 1000, "stack_bytes": 256}, db_path=path + ) + full_bytes = len(json.dumps(asdict(full), ensure_ascii=False).encode("utf-8")) + compact_bytes = len(json.dumps(asdict(compact), ensure_ascii=False).encode("utf-8")) + assert full.returned == compact.returned == 332 + assert compact.total_is_exact and not compact.truncated and not compact.has_more + assert compact_bytes < full_bytes / 20 + print(f"{layout}: full={full_bytes} B compact={compact_bytes} B") + finally: + service.close() diff --git a/tests/test_contract_cli_api.py b/tests/test_contract_cli_api.py index 65bb194..9149593 100644 --- a/tests/test_contract_cli_api.py +++ b/tests/test_contract_cli_api.py @@ -32,6 +32,56 @@ pytestmark = pytest.mark.usefixtures("owned_service_instances") +@pytest.mark.parametrize("template", ["event", "active_memory_callstack_at_event"]) +def test_stack_summary_cli_api_and_catalog_contract(contract_db: Path, template: str): + with closing(sqlite3.connect(contract_db)) as conn, conn: + conn.execute( + "INSERT INTO trace_entry_0 VALUES (1, 4, 4096, 2048, 0, 2048, 2048, 4096, ?)", + ("训练.py:42 forward\n" * 1000,), + ) + params = {"stack_bytes": 17} + if template == "active_memory_callstack_at_event": + params["event_id"] = 1 + with SnapshotAnalyzer(db_path=contract_db, device_id=0) as analyzer: + api_result = analyzer.execute_query(template, params=params) + cli_result = runner.invoke( + app, + [ + "query", + str(contract_db), + "--device", + "0", + "--template-use", + template, + "--params", + json.dumps(params), + "--json", + ], + ) + assert cli_result.exit_code == 0, cli_result.output + payload = json.loads(cli_result.output) + for key in ("rows", "total", "returned", "has_more", "truncated", "total_is_exact"): + assert payload[key] == api_result[key] + assert payload["effective_params"]["stack_bytes"] == 17 + assert any(row["stack_truncated"] for row in api_result["rows"]) + info = analyzer.get_template_info(template) + assert info["parameters"]["stack_bytes"]["default"] == -1 + fields = {field["column"] for field in info["output_schema"]} + assert { + "stack_id", + "stack_kind", + "stack_event_id", + "stack_bytes", + "stack_original_bytes", + "stack_truncated", + } <= fields + catalog = runner.invoke(app, ["capabilities", "--json"]) + assert catalog.exit_code == 0, catalog.output + entry = next(t for t in json.loads(catalog.output)["templates"] if t["name"] == template) + assert entry["output_schema"] == info["output_schema"] + assert entry["parameters"] == info["parameters"] + + def create_contract_db(db_path: Path) -> Path: """Create a tiny snapshot database shared by CLI and API contract paths.""" conn = sqlite3.connect(str(db_path)) From fc7adc3b67ce1266af1674364a781364542ba742 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 3 Oct 2026 22:06:40 +0800 Subject: [PATCH 2/2] test(reports): verify compact stacks preserve coverage and completeness --- tests/query/test_stack_summary.py | 35 +++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/tests/query/test_stack_summary.py b/tests/query/test_stack_summary.py index 39f7649..60b36fc 100644 --- a/tests/query/test_stack_summary.py +++ b/tests/query/test_stack_summary.py @@ -168,17 +168,29 @@ def test_summary_preserves_incomplete_windows(stack_db, exact_total, template, p @pytest.mark.parametrize("metric", ["active", "allocated", "reserved"]) -def test_report_uses_shared_summary_and_exposes_text_markers(stack_db, metric): +@pytest.mark.parametrize("limit", [1, 20], ids=["capped", "complete"]) +@pytest.mark.parametrize("budget", [0, 7]) +def test_report_uses_shared_summary_and_exposes_text_markers(stack_db, metric, limit, budget): path, _ = stack_db service = ReportService() try: - full = asdict(service.peak_memory_report(path, device_id=0, metric=metric)) + full = asdict(service.peak_memory_report(path, device_id=0, metric=metric, limit=limit)) compact = asdict( - service.peak_memory_report(path, device_id=0, metric=metric, stack_bytes=7) + service.peak_memory_report( + path, device_id=0, metric=metric, limit=limit, stack_bytes=budget + ) ) - assert {k: v for k, v in compact.items() if k != "callstack_groups"} == { - k: v for k, v in full.items() if k != "callstack_groups" - } + assert { + k: v for k, v in compact.items() if k not in {"callstack_groups", "effective_params"} + } == {k: v for k, v in full.items() if k not in {"callstack_groups", "effective_params"}} + assert compact["effective_params"] == {**full["effective_params"], "stack_bytes": budget} + assert compact["has_more"] is compact["truncated"] is (limit == 1) + for original, summary in zip( + full["callstack_groups"], compact["callstack_groups"], strict=True + ): + assert { + k: v for k, v in summary.items() if k != "callstack" and not k.startswith("stack_") + } == {k: v for k, v in original.items() if k != "callstack"} args = [ "report", "peak-memory", @@ -187,8 +199,10 @@ def test_report_uses_shared_summary_and_exposes_text_markers(stack_db, metric): "0", "--metric", metric, + "--limit", + str(limit), "--stack-bytes", - "7", + str(budget), ] result = CliRunner().invoke(app, args + ["--json"]) assert result.exit_code == 0, result.output @@ -196,8 +210,11 @@ def test_report_uses_shared_summary_and_exposes_text_markers(stack_db, metric): text = CliRunner().invoke(app, args) assert text.exit_code == 0, text.output assert "stack_truncated=True" in text.output - assert "stack_bytes=7" in text.output - assert "Full text: query event" in text.output + assert f"stack_bytes={budget}" in text.output + assert ("partial / possibly incomplete" in text.output) is (limit == 1) + assert ("Full text: query event" in text.output) is any( + row["stack_kind"] == "captured" for row in compact["callstack_groups"] + ) finally: service.close()