Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--device` | Device ID |
| `--list` | List available query templates |
| `--category` | Filter templates by category: `basic`, `statistical`, `business` |
| `--template-info` | Show template details (parameters and output schema) |
| `--template-info` | Show template details (parameters, output schema, and field semantics) |
| `-n` | Maximum displayed rows; zero or a negative value means unlimited |

## Query Templates
Expand Down Expand Up @@ -60,7 +60,7 @@ Domain-specific analysis.

| Template | Description |
|----------|-------------|
| `leak_detection` | Find allocations without matching free events |
| `leak_detection` | Find captured allocations with no recorded free-completion event (leak candidates) |
| `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 All @@ -71,6 +71,9 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'

`min_size` is the minimum candidate size in bytes and defaults to `0`. Select
the target device with the command-level `--device` option, not inside `--params`.
`leak_detection` returns candidates that were still live in the captured range,
not confirmed leaks. Read field units and interpretation limits with
`pt-snap query --template-info leak_detection`.

## Parameter Validation

Expand Down Expand Up @@ -220,14 +223,26 @@ defaults to `max_rows=None` (no cap), matching the CLI unless `-n` / `max_rows`
CLI and Python API query results contain raw SQLite values. A template's
`output_schema` is metadata and is not applied automatically during query
execution. Use `ResultMapper` explicitly when converted values such as
hexadecimal address strings are required.
hexadecimal address strings are required. Result rows do not repeat field
explanations; look up `semantics_version` and interpretation limits with
`--template-info` (or `get_template_info`) for the template that produced the
rows. `SnapshotAnalyzer.execute_query()` results also include `template`
and `semantics_version` so that lookup stays tied to the rows.

## Template Architecture

Query templates are defined in YAML format with:
- `version`: Template version
- `version`: YAML file format version, not the field-semantics contract and not the SnapshotDB schema version
- `queries`: Query definitions with description, supported devices, parameters, SQL (Jinja2 templated), and output schema
- Each parameter declares `type`, `default`, `required`, `description`, and optionally `choices`, a closed list of accepted values that is mandatory for parameters rendered as SQL identifiers or keywords
- Optional `semantics_version` (positive integer) and `interpretation_limits` on the query, plus optional field keys on each `output_schema` entry: `units`, `metric_semantics`, `scope`, `denominator`, `sentinel`, and `interpretation_limits`
- `semantics_version` is the interpretation contract agents should cite. v1/v2 SQL variants of the same template share that contract. Templates that omit both remain valid; unannotated `output_schema` entries carry `column` and `type` only

Closed vocabularies:

- `units`: `bytes`, `gib`, `percent`, `event_id`, `count`, `address`, `flag`, `text`
- `metric_semantics`: `instantaneous_occupancy`, `same_event_gap`, `share_of_included_rows`, `identifier`, `classification`, `ordering_marker`
- `scope`: `dynamic`, `static`, `preexisting`, `mixed`, `captured_range`, `same_event`. Use `mixed` when a column contains more than one of those per row (see `category` on `active_memory_callstack_at_event`)

When passed explicitly to `ResultMapper`, recognized mapping types are `int`,
`float`, `str`, `bool`, `hex`, and `datetime`; `datetime` is currently a
Expand Down
13 changes: 11 additions & 2 deletions docs/en/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,14 @@ if info is not None:

`list_templates()` returns dictionaries containing `name`, `description`, and
`category`. `get_template_info()` returns full template metadata or `None` only
when the named template does not exist; registry failures are propagated.
when the named template does not exist; registry failures are propagated. The
payload includes `parameters`, `output_schema`, `semantics_version`, and
`interpretation_limits`. `semantics_version` is the field-interpretation
contract and is distinct from YAML `version` and the SnapshotDB schema /
callstack layout. Unannotated templates use `semantics_version: null` and
`column`/`type` only; annotated columns may also declare `units`,
`metric_semantics`, `scope`, `denominator`, `sentinel`, and per-field
`interpretation_limits`. The dict is JSON-serializable.

## Execute Queries

Expand All @@ -107,7 +114,9 @@ The result contains:
| `total` | Number of rows produced before display limiting |
| `returned` | Number of rows included in `rows` |
| `device_id` | Device selected for execution |
| `rows` | Query rows as dictionaries |
| `rows` | Query rows as dictionaries (raw SQLite values, without long field explanations) |
| `template` | Template that produced the rows |
| `semantics_version` | Interpretation contract to look up via `get_template_info()`, or `None` |

Pass `device_id` to `execute_query()` to override the analyzer's device for one
call. Otherwise selection uses the analyzer device, then the device from resolved
Expand Down
23 changes: 18 additions & 5 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--device` | 设备 ID |
| `--list` | 列出可用的查询模板 |
| `--category` | 按分类过滤模板:`basic`、`statistical`、`business` |
| `--template-info` | 显示模板详情(参数和输出 schema) |
| `--template-info` | 显示模板详情(参数、输出 schema 和字段语义) |
| `-n` | 最大显示行数;零或负数表示不限制 |

## 查询模板
Expand Down Expand Up @@ -60,7 +60,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \

| 模板 | 说明 |
|------|------|
| `leak_detection` | 查找未匹配释放事件的分配 |
| `leak_detection` | 查找已采集分配且没有释放完成记录的候选(不是已确认泄漏) |
| `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态与 preexisting 内存 |

## 泄漏检测
Expand All @@ -70,7 +70,9 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
```

`min_size` 表示候选泄漏的最小字节数,默认值为 `0`。目标设备应通过命令级
`--device` 选项指定,而不是放进 `--params`。
`--device` 选项指定,而不是放进 `--params`。`leak_detection` 返回的是捕获范围内
仍存活的候选,不是已确认泄漏。用 `pt-snap query --template-info leak_detection`
读取字段单位与解释限制。

## 参数校验

Expand Down Expand Up @@ -212,14 +214,25 @@ Found 150 results, showing 2:

CLI 和 Python API 的查询结果包含原始 SQLite 值。模板的 `output_schema`
只是 metadata,查询执行时不会自动应用。需要十六进制地址字符串等转换值时,
应显式调用 `ResultMapper`。
应显式调用 `ResultMapper`。结果行不重复字段说明;用 `--template-info`
(或 `get_template_info`)按产生这些行的模板查阅 `semantics_version` 与解释限制。
`SnapshotAnalyzer.execute_query()` 的结果还包含 `template` 与 `semantics_version`,
便于把行与契约对应起来。

## 模板架构

查询模板使用 YAML 格式定义,包含:
- `version`: 模板版本
- `version`: YAML 文件格式版本,既不是字段语义契约,也不是 SnapshotDB schema 版本
- `queries`: 查询定义,包含描述、支持的设备、参数、SQL(Jinja2 模板语法)和输出 schema
- 每个参数声明 `type`、`default`、`required`、`description`,以及可选的 `choices`(允许取值的封闭列表;会被渲染为 SQL 标识符或关键字的参数必须声明它)
- 查询可选声明 `semantics_version`(正整数)和 `interpretation_limits`;`output_schema` 各列还可声明 `units`、`metric_semantics`、`scope`、`denominator`、`sentinel`、`interpretation_limits`
- `semantics_version` 是 Agent 应引用的解释契约。同一模板的 v1/v2 SQL 变体共享该契约。未同时声明两者时模板仍有效;未注解的 `output_schema` 条目仅含 `column` 与 `type`

封闭词表:

- `units`:`bytes`、`gib`、`percent`、`event_id`、`count`、`address`、`flag`、`text`
- `metric_semantics`:`instantaneous_occupancy`、`same_event_gap`、`share_of_included_rows`、`identifier`、`classification`、`ordering_marker`
- `scope`:`dynamic`、`static`、`preexisting`、`mixed`、`captured_range`、`same_event`。一列按行混合多种范围时用 `mixed`(见 `active_memory_callstack_at_event` 的 `category`)

显式传给 `ResultMapper` 时,可识别的映射类型包括 `int`、`float`、`str`、
`bool`、`hex` 和 `datetime`;当前 `datetime` 只是透传声明,不执行解析。
Expand Down
11 changes: 9 additions & 2 deletions docs/zh/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,12 @@ if info is not None:

`list_templates()` 返回包含 `name`、`description` 和 `category` 的字典。
`get_template_info()` 返回完整模板 metadata;仅当指定模板不存在时返回 `None`,registry
内部错误会继续向调用方抛出。
内部错误会继续向调用方抛出。返回值包含 `parameters`、`output_schema`、
`semantics_version` 和 `interpretation_limits`。`semantics_version` 是字段解释契约,
有别于 YAML `version` 以及 SnapshotDB schema / callstack 布局。未标注的模板
`semantics_version` 为 `null`,列上只有 `column`/`type`;已标注列还可包含
`units`、`metric_semantics`、`scope`、`denominator`、`sentinel` 以及字段级
`interpretation_limits`。该字典可直接 JSON 序列化。

## 执行查询

Expand All @@ -101,7 +106,9 @@ for row in result["rows"]:
| `total` | 限制显示行数前产生的结果总数 |
| `returned` | `rows` 中实际返回的行数 |
| `device_id` | 本次执行选择的设备 |
| `rows` | 字典形式的查询行 |
| `rows` | 字典形式的查询行(原始 SQLite 值,不含长说明) |
| `template` | 产生这些行的模板名 |
| `semantics_version` | 通过 `get_template_info()` 查阅的解释契约,未声明时为 `None` |

向 `execute_query()` 传入 `device_id` 可以仅覆盖本次调用的 analyzer 设备。否则依次使用
analyzer 设备;未设置显式 analyzer 数据库时,再使用已解析项目或全局 focus 的设备;
Expand Down
4 changes: 2 additions & 2 deletions skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Run an initial ranked query, keeping the result bounded while retaining the repo
pt-snap query '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<min_size>}' -n 100
```

`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing.
`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from `pt-snap query --template-info leak_detection`; do not treat candidates as confirmed leaks.

Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`.

Expand All @@ -108,7 +108,7 @@ Use the final event ID from Step 1:
pt-snap query '<db_path>' --device <device_id> --template-use active_memory_callstack_at_event --params '{"event_id":<final_event_id>,"include_static":true,"min_size":0,"top_n":20}'
```

Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. The `percent_of_active_blocks` column is a byte share (`size_bytes / total size_bytes`) despite its name; it is not the share of block count. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`.
Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. Read `percent_of_active_blocks` units, denominator, and interpretation limits from `pt-snap query --template-info active_memory_callstack_at_event` rather than inferring them from the column name. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`.

### 4. Compare occupancy at the active peak

Expand Down
5 changes: 1 addition & 4 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,10 +192,7 @@ their event ID carries the range selection forward.
- It does not assign reserved/cache bytes, allocator gaps, or inactive allocated
bytes to callstacks. A large gap is evidence of counter separation at one
event, not proof of fragmentation, caching policy, or an OOM cause.
- `percent_of_active_blocks` is a byte percentage despite its name. It is based
on `size_bytes`, not block count.
- Excluding static memory changes the percentage denominator. State the
inclusion choice whenever percentages are reported.
- Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event` (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported.

### Static, preexisting, and dynamic memory

Expand Down
4 changes: 4 additions & 0 deletions src/pt_snap_cli/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,18 @@
*,
context_cache: ContextCache | None = None,
) -> None:
self._config = Config()

Check warning on line 44 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_config` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
self._db_path = db_path

Check warning on line 45 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_db_path` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
self._device_id = device_id

Check warning on line 46 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_device_id` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
self._focus_service = FocusService(self._config)

Check warning on line 47 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_focus_service` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
# Share one context cache across the analyzer so that long-lived
# SnapshotAnalyzer instances reuse a single
# SQLite connection and skip schema validation on every query.
# Explicit ``is not None`` because an empty cache is falsy via
# ``__len__`` and would be silently replaced otherwise.
self._context_cache = context_cache if context_cache is not None else ContextCache()

Check warning on line 53 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_context_cache` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
self._query_service = QueryService(self._focus_service, context_cache=self._context_cache)

Check warning on line 54 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_query_service` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)
self._metadata_service = ImportMetadataService()

Check warning on line 55 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type annotation for attribute `_metadata_service` is required because this class is not decorated with `@final` (reportUnannotatedClassAttribute)

@property
def context_cache(self) -> ContextCache:
Expand Down Expand Up @@ -92,7 +92,7 @@

if candidate_db is not None:
try:
self._focus_service.validate_session_db(candidate_db, candidate_device)

Check warning on line 95 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Result of call expression is of type "FocusState" and is not used; assign to variable "_" if this is intentional (reportUnusedCallResult)
except DatabaseMissingError as exc:
raise FileNotFoundError(str(exc)) from exc
except DatabaseSchemaError as exc:
Expand All @@ -105,7 +105,7 @@
self._device_id = device_id
return self.get_focus()

def list_templates(self, category: str | None = None) -> list[dict[str, Any]]:

Check warning on line 108 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type `Any` is not allowed (reportExplicitAny)
return [
{
"name": template.name,
Expand All @@ -115,7 +115,7 @@
for template in self._query_service.list_templates(category)
]

def get_template_info(self, name: str) -> dict[str, Any] | None:

Check warning on line 118 in src/pt_snap_cli/api.py

View workflow job for this annotation

GitHub Actions / Lint & Format

Type `Any` is not allowed (reportExplicitAny)
try:
info = self._query_service.get_template_info(name)
except TemplateNotFoundError:
Expand All @@ -137,6 +137,8 @@
for param_name, param in info.parameters.items()
},
"output_schema": info.output_schema,
"semantics_version": info.semantics_version,
"interpretation_limits": info.interpretation_limits,
}

def execute_query(
Expand All @@ -161,6 +163,8 @@
"returned": result.returned,
"device_id": result.device_id,
"rows": result.rows,
"template": result.template,
"semantics_version": result.semantics_version,
}

def get_database_metadata(self, db_path: str | None = None) -> dict[str, Any]:
Expand Down
4 changes: 2 additions & 2 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 @@ -96,7 +96,7 @@ Run an initial ranked query, keeping the result bounded while retaining the repo
pt-snap query '<db_path>' --device <device_id> --template-use leak_detection --params '{"min_size":<min_size>}' -n 100
```

`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing.
`leak_detection` includes only dynamic blocks with a recorded allocation and no recorded free completion. It intentionally excludes static blocks whose allocation predates tracing. Interpret its columns from `pt-snap query --template-info leak_detection`; do not treat candidates as confirmed leaks.

Record candidate count, largest sizes, addresses, and allocation event IDs. Do not infer simultaneous live bytes by summing cumulative allocation activity from `callstack_analysis`.

Expand All @@ -108,7 +108,7 @@ Use the final event ID from Step 1:
pt-snap query '<db_path>' --device <device_id> --template-use active_memory_callstack_at_event --params '{"event_id":<final_event_id>,"include_static":true,"min_size":0,"top_n":20}'
```

Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. The `percent_of_active_blocks` column is a byte share (`size_bytes / total size_bytes`) despite its name; it is not the share of block count. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`.
Keep static memory separate from dynamic live memory. Rank dynamic groups by `size_bytes`, then compare block count, requested bytes, and each group's share of included active bytes. Read `percent_of_active_blocks` units, denominator, and interpretation limits from `pt-snap query --template-info active_memory_callstack_at_event` rather than inferring them from the column name. A group containing many small blocks can be important even when no individual block appears near the top of `leak_detection`.

### 4. Compare occupancy at the active peak

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -192,10 +192,7 @@ their event ID carries the range selection forward.
- It does not assign reserved/cache bytes, allocator gaps, or inactive allocated
bytes to callstacks. A large gap is evidence of counter separation at one
event, not proof of fragmentation, caching policy, or an OOM cause.
- `percent_of_active_blocks` is a byte percentage despite its name. It is based
on `size_bytes`, not block count.
- Excluding static memory changes the percentage denominator. State the
inclusion choice whenever percentages are reported.
- Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event` (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported.

### Static, preexisting, and dynamic memory

Expand Down
30 changes: 27 additions & 3 deletions src/pt_snap_cli/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
from collections.abc import Mapping
from dataclasses import asdict
from pathlib import Path
from typing import Annotated, Literal, NoReturn, cast
from typing import Annotated, Any, Literal, NoReturn, cast

import typer

Expand Down Expand Up @@ -60,6 +60,7 @@
human_skill_summary,
parse_host_option,
)
from pt_snap_cli.query.config import OUTPUT_COLUMN_OPTIONAL
from pt_snap_cli.query.registry import discover_categories

AGENT_HELP_EPILOG = (
Expand Down Expand Up @@ -89,6 +90,20 @@ def _query_service() -> QueryService:
return QueryService(_focus_service())


def _echo_output_schema_column(column: Mapping[str, Any]) -> None:
typer.echo(f" {column['column']}: {column['type']}")
for key in OUTPUT_COLUMN_OPTIONAL:
if key not in column:
continue
value = column[key]
if key == "interpretation_limits":
typer.echo(" interpretation_limits:")
for item in value:
typer.echo(f" - {item}")
else:
typer.echo(f" {key}: {value}")


def _skill_service() -> SkillService:
return SkillService()

Expand Down Expand Up @@ -371,7 +386,7 @@ def query_database(
str | None,
typer.Option(
"--template-info",
help="Show detailed information about a template (including parameters and output schema)",
help="Show detailed information about a template (including parameters, output schema, and field semantics)",
autocompletion=complete_template_names,
),
] = None,
Expand Down Expand Up @@ -427,6 +442,10 @@ def query_database(
typer.echo(f"Description: {info.description}")
typer.echo(f"Category: {info.category}")
typer.echo(f"Devices: {info.devices}")
typer.echo(
"Semantics Version: "
f"{info.semantics_version if info.semantics_version is not None else 'none'}"
)
typer.echo()
typer.echo("Parameters:")
if info.parameters:
Expand All @@ -453,9 +472,14 @@ def query_database(
typer.echo("Output Schema:")
if info.output_schema:
for col in info.output_schema:
typer.echo(f" {col['column']}: {col['type']}")
_echo_output_schema_column(col)
else:
typer.echo(" Dynamic (depends on query)")
if info.interpretation_limits:
typer.echo()
typer.echo("Interpretation Limits:")
for limit in info.interpretation_limits:
typer.echo(f" - {limit}")
typer.echo()
typer.echo("Example Usage:")
example_params = {}
Expand Down
Loading
Loading