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
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,10 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.

`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, use `pt-snap capabilities --json` and `pt-snap overview --json` before diagnosing, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `capabilities`, `overview`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`.

Peak reports expose attribution completeness and same-event active-byte coverage;
group percentages use included bytes after filtering and ranking. See the
[report guide](docs/en/querying.md#report-command) before interpreting a capped breakdown.

## Agent Skills

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).
Expand Down
4 changes: 4 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices

`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,诊断前先用 `pt-snap capabilities --json` 和 `pt-snap overview --json`,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`capabilities`、`overview`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。

峰值报告会返回归因完整性及同事件 active 字节覆盖率;分组百分比以筛选和排名后的
included bytes 为分母。解读有上限的分组结果前,请参阅
[报告指南](docs/zh/querying.md#report-命令)。

## Agent Skills

使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。
Expand Down
19 changes: 19 additions & 0 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,25 @@ The report command combines:

and prints either a human-readable summary or JSON.

The existing `callstack_groups` and `percent_of_active_blocks` values are preserved.
JSON also exposes attribution `has_more`, `truncated`, `total_is_exact`, and
`effective_params` (`event_id`, `include_static`, `min_size`, `top_n`). A full
dynamic `top_n` window is conservatively **possibly incomplete**, even when it
happens to contain every group. Text output labels this as partial. Increase
`--limit` within a finite budget and replace the previous result; do not add
ranked windows together. Static and preexisting groups are extra rows outside
the dynamic `--limit` cap when included.

`included_bytes` sums all returned groups. `percent_denominator: "included_bytes"`
means row percentages are byte shares of this filtered/capped set, not all active
memory or block counts. `active_bytes_at_event` is the active counter at the
**selected metric's event**, including for allocated/reserved reports.
`coverage_percent` is `100 * included_bytes / active_bytes_at_event`; it is `null`
(text: unknown) when that counter is absent or non-positive, or no event exists.
Coverage is not a completeness flag: `--exclude-static` can lower it without
truncation, and reaching the cap can remain possibly incomplete at 100% coverage.
An empty trace returns no groups, zero included bytes, and unknown coverage.

## JSON Output

`--json` writes one JSON object to stdout. Success payloads include
Expand Down
16 changes: 16 additions & 0 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,22 @@ pt-snap report peak-memory /path/to/snapshot.db --json

并输出人类可读摘要或 JSON。

原有 `callstack_groups` 和 `percent_of_active_blocks` 数值保持不变。JSON 还会
返回归因的 `has_more`、`truncated`、`total_is_exact` 和 `effective_params`
(`event_id`、`include_static`、`min_size`、`top_n`)。动态分组恰好填满 `top_n`
窗口时会保守标记为**可能不完整**,即使实际上已包含所有分组;文本输出显示 partial。
可在有限预算内增大 `--limit`,用新结果替换旧结果,不要把不同排名窗口累加。
包含静态内存时,static 和 preexisting 分组是动态 `--limit` 上限之外的额外行。

`included_bytes` 是所有返回分组的字节总和。`percent_denominator: "included_bytes"`
说明行百分比是筛选、截断后集合的字节占比,而非全部 active 内存或块数量的占比。
`active_bytes_at_event` 是**所选 metric 对应事件**的 active counter,对 allocated
和 reserved 报告也一样。`coverage_percent` 为
`100 * included_bytes / active_bytes_at_event`;该 counter 缺失、非正数或没有事件时
为 `null`(文本显示 unknown)。覆盖率不是完整性标志:`--exclude-static` 可以在
没有截断时降低覆盖率,而满窗口即使覆盖率达到 100% 也仍可能不完整。
空 trace 返回空分组、零 included bytes 和未知覆盖率。

## JSON 输出

`--json` 向 stdout 写一个 JSON 对象。成功结果包含 `schema_version`(当前为 `1`)、
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 @@ -335,6 +335,23 @@ those callstacks. Keep static and dynamic active-block groups distinct. The
callstack template has no `offset`; if `has_more` or `truncated` is true,
increase `top_n` instead of treating the ranked page as complete.

For reports, inspect `has_more`, `truncated`, `total_is_exact`, and
`effective_params` too. A full dynamic cap means possibly incomplete, not
proven omissions. Widen report `--limit` (or query `top_n`, with `-n` at least
`top_n + 2` for special groups) at most twice, for example 20 → 40 → 80, within
a finite agreed budget. Replace prior ranked windows; do not sum them or use
unlimited expansion. If still flagged, retain an explicit partial conclusion.
If an older report lacks these fields, use the verified bounded callstack
query rather than assuming completeness.

Preserve report `included_bytes`, `percent_denominator`,
`active_bytes_at_event`, and `coverage_percent`. Row percentages describe
included bytes after filtering/top_n, not all active memory. Coverage uses the
active counter at the selected event, never reserved bytes or an independent
active peak; NULL coverage is unknown. Excluding static/preexisting memory may
lower coverage without truncation, and 100% coverage does not override cap-hit
flags. These values do not measure fragmentation or explain allocator gaps.

Do not use `callstack_analysis` as segment-source attribution. Its query has no
action filter, so it mixes event types and cannot identify which callstack
caused segment mapping, acquisition, retention, cache bytes, or fragmentation.
Expand Down
19 changes: 19 additions & 0 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,25 @@ occurred together. The repeated `peak` and `allocator_gap` sections should agree
across all three reports; the metric-specific `event_id` and `callstack_groups`
are the selected-event breakdown.

Read report `has_more`, `truncated`, `total_is_exact`, and `effective_params`
before claiming a complete composition. A full dynamic `top_n` window means
possibly incomplete, not proven omissions. If either flag is true, widen
`--limit` at most twice (for example 20 → 40 → 80), within a finite agreed
budget; replace prior results rather than summing ranked windows. If still
flagged, report partial attribution and stop expanding. Never default to an
unlimited query. Static/preexisting groups are extra rows outside `top_n`.

Report `included_bytes`, `percent_denominator`, `active_bytes_at_event`, and
`coverage_percent` with the composition. The percentage denominator is included
bytes after filtering/top_n, not all active memory. Coverage uses active bytes
at this selected event even for allocated/reserved peaks; never divide by an
independent active peak or by reserved bytes. NULL coverage is unknown.
`--exclude-static` can lower coverage without truncation; 100% coverage does
not override conservative cap-hit flags. If an older report lacks these fields,
do not assume completeness: use the verified callstack query with a finite
`top_n` and `-n` at least `top_n + 2` to retain both special categories, and
preserve its completeness flags and included-byte denominator.

### Representative blocks

Use `active_blocks_at_event` at the chosen metric's peak event, not at the end of
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,23 @@ those callstacks. Keep static and dynamic active-block groups distinct. The
callstack template has no `offset`; if `has_more` or `truncated` is true,
increase `top_n` instead of treating the ranked page as complete.

For reports, inspect `has_more`, `truncated`, `total_is_exact`, and
`effective_params` too. A full dynamic cap means possibly incomplete, not
proven omissions. Widen report `--limit` (or query `top_n`, with `-n` at least
`top_n + 2` for special groups) at most twice, for example 20 → 40 → 80, within
a finite agreed budget. Replace prior ranked windows; do not sum them or use
unlimited expansion. If still flagged, retain an explicit partial conclusion.
If an older report lacks these fields, use the verified bounded callstack
query rather than assuming completeness.

Preserve report `included_bytes`, `percent_denominator`,
`active_bytes_at_event`, and `coverage_percent`. Row percentages describe
included bytes after filtering/top_n, not all active memory. Coverage uses the
active counter at the selected event, never reserved bytes or an independent
active peak; NULL coverage is unknown. Excluding static/preexisting memory may
lower coverage without truncation, and 100% coverage does not override cap-hit
flags. These values do not measure fragmentation or explain allocator gaps.

Do not use `callstack_analysis` as segment-source attribution. Its query has no
action filter, so it mixes event types and cannot identify which callstack
caused segment mapping, acquisition, retention, cache bytes, or fragmentation.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,25 @@ occurred together. The repeated `peak` and `allocator_gap` sections should agree
across all three reports; the metric-specific `event_id` and `callstack_groups`
are the selected-event breakdown.

Read report `has_more`, `truncated`, `total_is_exact`, and `effective_params`
before claiming a complete composition. A full dynamic `top_n` window means
possibly incomplete, not proven omissions. If either flag is true, widen
`--limit` at most twice (for example 20 → 40 → 80), within a finite agreed
budget; replace prior results rather than summing ranked windows. If still
flagged, report partial attribution and stop expanding. Never default to an
unlimited query. Static/preexisting groups are extra rows outside `top_n`.

Report `included_bytes`, `percent_denominator`, `active_bytes_at_event`, and
`coverage_percent` with the composition. The percentage denominator is included
bytes after filtering/top_n, not all active memory. Coverage uses active bytes
at this selected event even for allocated/reserved peaks; never divide by an
independent active peak or by reserved bytes. NULL coverage is unknown.
`--exclude-static` can lower coverage without truncation; 100% coverage does
not override conservative cap-hit flags. If an older report lacks these fields,
do not assume completeness: use the verified callstack query with a finite
`top_n` and `-n` at least `top_n + 2` to retain both special categories, and
preserve its completeness flags and included-byte denominator.

### Representative blocks

Use `active_blocks_at_event` at the chosen metric's peak event, not at the end of
Expand Down
23 changes: 23 additions & 0 deletions src/pt_snap_cli/cli_output.py
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,29 @@
typer.echo()

typer.secho("Active memory by callstack:", fg=typer.colors.GREEN, bold=True)
if report.event_id is None:
typer.echo(" Attribution: unavailable (no peak event).")
elif report.has_more or report.truncated:
typer.echo(" Attribution: partial / possibly incomplete (dynamic top_n cap reached).")
typer.echo(" Increase --limit within a finite budget to check for additional groups.")
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:
typer.echo(" No active memory callstack groups found.")
return
Expand Down
7 changes: 6 additions & 1 deletion src/pt_snap_cli/cli_reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,12 @@ def report_peak_memory(
bool,
typer.Option("--include-static/--exclude-static", help="Include static memory group"),
] = True,
limit: Annotated[int, typer.Option("--limit", "-n", help="Maximum callstack groups")] = 20,
limit: Annotated[
int,
typer.Option(
"--limit", "-n", help="Maximum dynamic callstack groups (static/preexisting are extra)"
),
] = 20,
json_output: Annotated[bool, _json_flag()] = False,
) -> None:
"""Generate a peak memory attribution report."""
Expand Down
8 changes: 8 additions & 0 deletions src/pt_snap_cli/core/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,14 @@ class PeakMemoryReport:
peak: dict[str, object]
allocator_gap: dict[str, object] | None
callstack_groups: list[dict[str, object]]
has_more: bool = False
truncated: bool = False
total_is_exact: bool = False
effective_params: dict[str, object] = field(default_factory=dict)
included_bytes: int = 0
percent_denominator: str = "included_bytes"
active_bytes_at_event: int | None = None
coverage_percent: float | None = None


@dataclass(frozen=True)
Expand Down
42 changes: 36 additions & 6 deletions src/pt_snap_cli/core/report_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@
"reserved": "peak_reserved_event_id",
}

_ACTIVE_COUNTER_BY_METRIC = {
"active": "peak_active",
"allocated": "active_at_allocated_peak",
"reserved": "active_at_reserved_peak",
}


class ReportService:
def __init__(self, focus_service: FocusService | None = None) -> None:
Expand Down Expand Up @@ -48,6 +54,12 @@ def peak_memory_report(
peak = peak_result.rows[0] if peak_result.rows else {}
# memory_peak selects an INTEGER event ID (or NULL for an empty trace).
event_id = cast(int | None, peak.get(_EVENT_ID_BY_METRIC[metric]))
attribution_params: dict[str, object] = {
"event_id": event_id,
"include_static": include_static,
"min_size": 0,
"top_n": limit,
}

if event_id is None:
return PeakMemoryReport(
Expand All @@ -57,6 +69,8 @@ def peak_memory_report(
peak=peak,
allocator_gap=None,
callstack_groups=[],
total_is_exact=True,
effective_params=attribution_params,
)

gap_result = self._query_service.execute_query(
Expand All @@ -67,21 +81,37 @@ def peak_memory_report(
)
callstack_result = self._query_service.execute_query(
"active_memory_callstack_at_event",
params={
"event_id": event_id,
"include_static": include_static,
"top_n": limit,
},
params=attribution_params,
db_path=db_path,
device_id=device_id,
start_dir=start_dir,
)

gap = gap_result.rows[0] if gap_result.rows else None
# allocator_gap supplies the active counter at this metric's event,
# not the independently occurring active high-water value.
active_bytes = cast(int | None, (gap or {}).get(_ACTIVE_COUNTER_BY_METRIC[metric]))
# No caller-side max_rows cap: these are all rows in the SQL percentage
# denominator, including static/preexisting groups outside top_n.
included_bytes = sum(cast(int, row["size_bytes"]) for row in callstack_result.rows)
coverage = (
included_bytes * 100.0 / active_bytes
if active_bytes is not None and active_bytes > 0
else None
)

return PeakMemoryReport(
device_id=peak_result.device_id,
metric=metric,
event_id=event_id,
peak=peak,
allocator_gap=gap_result.rows[0] if gap_result.rows else None,
allocator_gap=gap,
callstack_groups=callstack_result.rows,
has_more=callstack_result.has_more,
truncated=callstack_result.truncated,
total_is_exact=callstack_result.total_is_exact,
effective_params=attribution_params,
included_bytes=included_bytes,
active_bytes_at_event=active_bytes,
coverage_percent=coverage,
)
Loading
Loading