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
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ that local environment is intentionally available.
| Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules |
| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures |
| Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs |
| Setup skill | [skills/AGENTS.md](skills/AGENTS.md) | Installation skill approval and active-interpreter safety boundary |
| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Installation approval and read-only memory-diagnostic boundaries |

## Runtime Topology

Expand Down Expand Up @@ -112,6 +112,7 @@ templates under category subdirectories are included by
| Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` |
| Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` |
| Reports | `src/pt_snap_cli/core/report_service.py`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` |
| Agent setup or peak-memory diagnostic skills | `skills/` and the referenced CLI/query surfaces | `tests/test_setup_skill.py`, `tests/test_memory_peak_breakdown_skill.py` |
| Packaging or release | `pyproject.toml`, `.github/workflows/` | `tests/test_package.py`, `tests/test_release_workflow.py` |
| Executable fixtures | `tests/fixtures/snapshots/` | `tests/test_fixture_provenance.py` before any deserializing suite |

Expand Down
23 changes: 17 additions & 6 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Aggregation and analysis.
|----------|-------------|
| `callstack_analysis` | Analyze callstack information |
| `memory_peak` | Peak memory metrics |
| `active_blocks_at_event` | List blocks that are still active at a specific event, with optional static block inclusion |
| `active_blocks_at_event` | List blocks that are still active at a specific event, with optional static and preexisting live inclusion |
| `allocator_gap` | Compare allocated, active, and reserved peak events and same-event gaps |

### Business Queries
Expand All @@ -57,7 +57,7 @@ Domain-specific analysis.
| Template | Description |
|----------|-------------|
| `leak_detection` | Find allocations without matching free events |
| `active_memory_callstack_at_event` | Aggregate blocks active at a specific event by allocation callstack, with static memory classified separately |
| `active_memory_callstack_at_event` | Aggregate blocks active at a specific event by allocation callstack, with static and preexisting memory classified separately |

## Leak Detection

Expand Down Expand Up @@ -88,10 +88,17 @@ pt-snap query --template-use active_blocks_at_event --params '{"event_id": 1234,

`active_blocks_at_event` treats a block as live at `event_id` when:

- `allocEventId <= event_id`
- and `freeEventId = -1` or `freeEventId > event_id`
- Dynamic block: `allocEventId != -1 AND allocEventId <= event_id`, and `freeEventId`
is `NULL`, negative, or greater than `event_id`
- Block without a captured allocation event (`allocEventId = -1`): `freeEventId`
is `NULL`, negative, or greater than `event_id`

When `include_static=true`, blocks with `allocEventId=-1 AND freeEventId=-1` are also included and labeled as `static`.
When `include_static=true`, blocks without an allocation event that are still
live at `event_id` are also included:

- `allocEventId=-1 AND freeEventId=-1` is labeled `static`
- Other allocation-less live blocks (for example, allocated before snapshot
collection began and freed later) are labeled `preexisting_live_at_event`

### 3. Attribute active memory to callstacks at that event

Expand All @@ -104,7 +111,11 @@ This query:
- starts from the active block set at `event_id`
- joins dynamic blocks back to their allocation events in `trace_entry_<device>`
- groups by allocation callstack
- emits static memory as a dedicated group instead of inventing a callstack
- 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.

### 4. Compare peak event gaps across metrics

Expand Down
17 changes: 11 additions & 6 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
|------|------|
| `callstack_analysis` | 调用栈分析 |
| `memory_peak` | 峰值内存指标 |
| `active_blocks_at_event` | 查询某个事件时刻仍然活跃的 block,可选包含静态内存 |
| `active_blocks_at_event` | 查询某个事件时刻仍然活跃的 block,可选包含静态与 preexisting 存活内存 |
| `allocator_gap` | 比较 allocated、active、reserved 三类峰值事件及其同事件 gap |

### Business Queries
Expand All @@ -57,7 +57,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| 模板 | 说明 |
|------|------|
| `leak_detection` | 查找未匹配释放事件的分配 |
| `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态内存 |
| `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态与 preexisting 内存 |

## 泄漏检测

Expand Down Expand Up @@ -88,10 +88,13 @@ pt-snap query --template-use active_blocks_at_event --params '{"event_id": 1234,

`active_blocks_at_event` 认为 block 在 `event_id` 时刻仍然活跃的条件是:

- `allocEventId <= event_id`
- 且 `freeEventId = -1` 或 `freeEventId > event_id`
- 动态 block:`allocEventId != -1 AND allocEventId <= event_id`,且 `freeEventId` 为 `NULL`、负数或大于 `event_id`
- 无分配事件的 block(`allocEventId = -1`):`freeEventId` 为 `NULL`、负数或大于 `event_id`

当 `include_static=true` 时,还会包含 `allocEventId=-1 AND freeEventId=-1` 的 block,并标记为 `static`。
当 `include_static=true` 时,还会包含无分配事件且在 `event_id` 时刻仍活跃的 block:

- `allocEventId=-1 AND freeEventId=-1` 标记为 `static`
- 其余无分配事件但存活的 block(例如快照采集前已分配、之后才释放)标记为 `preexisting_live_at_event`

### 3. 对该时刻的活跃内存做调用栈归因

Expand All @@ -104,7 +107,9 @@ pt-snap query --template-use active_memory_callstack_at_event --params '{"event_
- 先从 `event_id` 时刻的活跃 block 集合开始
- 把动态 block 回连到 `trace_entry_<device>` 的分配事件
- 按分配调用栈做聚合
- 对静态内存单独分组,而不是伪造调用栈
- 对静态内存和 preexisting 内存单独分组,而不是伪造调用栈

`top_n` 只限制动态调用栈分组的数量;`static` 和 `preexisting_live_at_event` 分组始终返回,不会被更大的动态分组挤出结果。

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

Expand Down
6 changes: 5 additions & 1 deletion skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,22 @@
## Purpose
`skills` contains agent workflows shipped with the repository. The setup skill
has an independent side-effect boundary because it may install packages into the
user's active Python environment after explicit approval.
user's active Python environment after explicit approval; diagnostic skills use
existing SnapshotDB data without writes.

## Scope
| Path | Responsibility |
| --- | --- |
| `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. |
| `pt-snap-memory-peak-breakdown/SKILL.md` | Explain active memory at active, allocated, or reserved peak events without leak, fragmentation, or OOM overclaims. |

## Invariants
- Preserve the selected `sys.executable` path for every Python and pip command; canonical paths are only for ownership comparison.
- Never assume Conda, switch environments, use plain `pip`, or install automatically.
- Keep `editable` and PyPI choices explicit, and obtain confirmation before every install attempt.
- Do not add setup steps that write reports or modify pt-snap focus/configuration.
- Keep memory diagnostics SnapshotDB-only and read-only; pass database/device explicitly and delegate missing tooling to `pt-snap-setup`.

## Focused Tests
- Run `pytest tests/test_setup_skill.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically.
- Run `pytest tests/test_memory_peak_breakdown_skill.py` after peak-breakdown skill changes; it locks command/template references, range fallback, and attribution caveats.
Loading
Loading