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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,13 @@
- `focus`、`import`、`split`、`query`、`config` 支持 `--json`。成功结果带 `schema_version` / `ok` 信封,以及 `db_path`、`focus_source`、`device_id`、`template`、`effective_params` 等上下文。`query --list` / `--template-info` / 执行共用该选项;`--template-info --json` 透出 #147 字段语义。
- JSON 模式失败时 stdout 为空,stderr 为带稳定错误码的结构化对象(如 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND`),退出码非零。`pt-snap` 控制台入口返回 Typer/Click 的退出码(不再丢弃非 standalone 返回值),在检测到 `--json` 时也会把 Click 用法/解析错误写成 `INVALID_PARAMETER` 信封(退出码 2),并把 Ctrl-C / EOF 写成 `ERROR` / `Aborted!`。解析失败时的 `--json` 判定是 argv 词法扫描(best-effort):忽略 `--` 之后的词,`--opt=value` 与数字词不吞后续参数。`query --json` 的 `effective_params.limit` 是尾部 SQL `LIMIT`(模板 `limit` 与 `-n` 的合并,或追加的 `-n`);CTE 内的 `top_n` 仍是独立参数。
- `split --json` 只控制 stdout 清单,与 `--format json` 的分片文件格式相互独立。`focus --session --json` 返回验证结果与 `PT_SNAP_DB_PATH` 赋值信息,不暗示已修改父 shell。
- 查询结果增加完整性与分页字段:`has_more` / `truncated` / `total_is_exact`。默认 `total` 等于本页 `returned`;`--exact-total`(API `exact_total=True`)才对匹配集合做 `COUNT`。有限 `LIMIT` 时多取一行判断是否还有后续,不再在触达 `-n` 时自动计数。CTE 内有限 `top_n` 在窗口已满时也置 `has_more` / `truncated`,续页靠增大 `top_n` 而不是 `offset` / `-n`。`event` / `block` / `allocation` / `leak_detection` 用 `id` 做稳定分页次序。`--timeout` 与 `PT_SNAP_QUERY_TIMEOUT` 是一次 `QueryService` 调用的共享时限(页面查询与可选 COUNT 共用),并作用于所有模板查询(含 `report peak-memory`);非法环境变量归为 `INVALID_PARAMETER`。诊断 skill 默认有界查询,并按 `has_more` / `truncated` 续页。

### 兼容性提示

- 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 已在 0.4.0 以退出码 1 失败。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。
- 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。

## [0.4.0] - Unreleased

Expand Down
47 changes: 38 additions & 9 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Run memory analysis queries against your snapshot database.
```bash
pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
[--device <id>] [--list] [--category <category>] \
[--template-info <template>] [-n <rows>] [--json]
[--template-info <template>] [-n <rows>] [--exact-total] [--timeout <seconds>] [--json]
```

**Parameters:**
Expand All @@ -23,7 +23,9 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--list` | List available query templates |
| `--category` | Filter templates by category: `basic`, `statistical`, `business` |
| `--template-info` | Show template details (parameters, output schema, and field semantics) |
| `-n` | Maximum displayed rows; zero or a negative value means unlimited |
| `-n` | Maximum displayed rows; zero or a negative value means unlimited. Separate from `--timeout`. |
| `--exact-total` | Run a `COUNT` of the matching set. Default `total` is the returned-row count. |
| `--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`) |

## Query Templates
Expand Down Expand Up @@ -201,11 +203,29 @@ and prints either a human-readable summary or JSON.

| Branch | Extra fields |
|--------|----------------|
| Execute | `db_path`, `focus_source`, `device_id`, `template`, `effective_params`, `semantics_version`, `total`, `returned`, `rows` |
| Execute | `db_path`, `focus_source`, `device_id`, `template`, `effective_params`, `semantics_version`, `total`, `returned`, `has_more`, `truncated`, `total_is_exact`, `timeout_s`, `rows` |
| `--list` | `category`, `templates` (`name`, `description`, `category`) |
| `--template-info` | Template metadata matching `get_template_info()`, plus `template` |

`-n` still caps `rows` and `returned`. `total` remains the untruncated count.
`-n` still caps `rows` and `returned`. By default `total` equals `returned`
(this page's row count) and `total_is_exact` is true only when the page is
the complete matching set (`has_more` is false and `offset` is 0).
`--exact-total` runs a `COUNT` of the matching set (ignoring `limit` /
`offset` / `top_n`) and sets `total_is_exact` to true. When a finite
trailing `LIMIT` is in effect, the executor fetches one extra row to set
`has_more` without that count. A finite inner `top_n` (for example inside
a CTE) is not a trailing `LIMIT`: when that ranked window is full,
`has_more` / `truncated` are set so a default page is not reported as
complete. An exact `COUNT` that equals `returned` can clear that signal.
`truncated` is true when this response is not the complete matching set
(`has_more`, a positive `offset`, or an exact `total` greater than
`returned`). `timeout_s` is the effective execution timeout in seconds, or
`null` when unbounded. `--timeout` / `PT_SNAP_QUERY_TIMEOUT` are one
QueryService-call budget shared by the page query and optional COUNT; they
apply to every template query, including `report peak-memory`, and do not
change the row cap. A non-numeric `PT_SNAP_QUERY_TIMEOUT` is
`INVALID_PARAMETER`, not `QUERY_FAILED`.

`effective_params` is the validated parameter set after defaults and `choices`
normalization. When `-n` is set, `limit` is the trailing SQL LIMIT after the
same merge the executor applies: `min` of a declared template `limit` and
Expand All @@ -215,6 +235,12 @@ caps such as `top_n` stay their own parameters; they do not rewrite
`semantics_version`, `interpretation_limits`, and field semantics from
`output_schema`.

`event`, `block`, `allocation`, and `leak_detection` paginate with a stable
`id` tie-break after the primary sort. Continue a truncated `limit` /
`offset` listing with the same sort keys and a higher `offset` (or `-n`).
`active_memory_callstack_at_event` has no `offset`; `-n` cannot raise the
CTE `top_n` cap. Continue that template by increasing `top_n`.

On `--json` failure, stdout is empty. stderr is:

```json
Expand Down Expand Up @@ -263,17 +289,20 @@ pt-snap query --template-use leak_detection -n 5
pt-snap query --template-use leak_detection -n 0
```

Example output (with `-n 2`):
Example output (with `-n 2`, default `total` semantics):

```
Found 150 results, showing 2:
Found 2 results, showing 2:
{'id': 1, 'address': 4096, 'size': 2048, ...}
{'id': 2, 'address': 8192, 'size': 4096, ...}
... and 148 more (use -n to show more)
... more available (use -n, offset, top_n, or --exact-total)
```

The "Found N" count is exact even when output is capped. `SnapshotAnalyzer.execute_query()`
defaults to `max_rows=None` (no cap), matching the CLI unless `-n` / `max_rows` is set.
With `--exact-total`, "Found N" is the matching-row count and the footer can
show how many rows remain. `SnapshotAnalyzer.execute_query()` defaults to
`max_rows=None` (no cap) and `exact_total=False`, matching the CLI unless
`-n` / `max_rows` or `--exact-total` / `exact_total` is set. `timeout_s` is
independent of the row cap.

CLI and Python API query results contain raw SQLite values. A template's
`output_schema` is metadata and is not applied automatically during query
Expand Down
14 changes: 12 additions & 2 deletions docs/en/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,12 @@ The result contains:

| Key | Meaning |
| --- | --- |
| `total` | Number of rows produced before display limiting |
| `total` | Matching-row `COUNT` when `exact_total=True`; otherwise the returned-row count |
| `returned` | Number of rows included in `rows` |
| `has_more` | True when a later page exists (extra-row probe on a trailing `LIMIT`, or a full inner `top_n` window) |
| `truncated` | True when this response is not the complete matching set |
| `total_is_exact` | True when `total` is a `COUNT`, or when the page is the complete matching set |
| `timeout_s` | Effective execution timeout in seconds, or `None` when unbounded |
| `device_id` | Device selected for execution |
| `rows` | Query rows as dictionaries (raw SQLite values, without long field explanations) |
| `template` | Template that produced the rows |
Expand All @@ -123,7 +127,13 @@ call. Otherwise selection uses the analyzer device, then the device from resolve
project or global focus when no explicit analyzer database is set, then the first
discovered device. An explicit analyzer database without an analyzer device does
not inherit a configured device. `max_rows=None`, zero, or a negative value is
unlimited.
unlimited. Pass `exact_total=True` for a matching-row `COUNT`. `timeout_s`
is a wall-clock budget for one `execute_query()` call in seconds (or
`PT_SNAP_QUERY_TIMEOUT`); the page query and optional COUNT share it. The
same environment variable applies to every template query, including
`report peak-memory`. It does not change the row cap. Continue
`active_memory_callstack_at_event` by increasing `top_n`; `-n` cannot
raise that CTE cap.

Rows contain raw SQLite values. Template `output_schema` metadata is not applied
automatically; use the optional [ResultMapper API](result-mapper-api.md) when
Expand Down
40 changes: 31 additions & 9 deletions docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
```bash
pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
[--device <id>] [--list] [--category <category>] \
[--template-info <template>] [-n <rows>] [--json]
[--template-info <template>] [-n <rows>] [--exact-total] [--timeout <seconds>] [--json]
```

**参数说明:**
Expand All @@ -23,7 +23,9 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--list` | 列出可用的查询模板 |
| `--category` | 按分类过滤模板:`basic`、`statistical`、`business` |
| `--template-info` | 显示模板详情(参数、输出 schema 和字段语义) |
| `-n` | 最大显示行数;零或负数表示不限制 |
| `-n` | 最大显示行数;零或负数表示不限制。与 `--timeout` 相互独立。 |
| `--exact-total` | 对匹配集合做 `COUNT`。默认 `total` 等于已返回行数。 |
| `--timeout` | 一次 `query` / `QueryService` 调用的墙钟预算(页面查询与可选 `--exact-total` COUNT 共用),经 SQLite progress handler 生效。`<= 0` 表示关闭。默认:`PT_SNAP_QUERY_TIMEOUT` 或不限制。该环境变量作用于所有模板查询,包括 `report peak-memory`。 |
| `--json` | 输出机器可读 JSON(执行、`--list` 与 `--template-info`) |

## 查询模板
Expand Down Expand Up @@ -193,18 +195,36 @@ pt-snap report peak-memory /path/to/snapshot.db --json

| 分支 | 额外字段 |
|------|----------|
| 执行 | `db_path`、`focus_source`、`device_id`、`template`、`effective_params`、`semantics_version`、`total`、`returned`、`rows` |
| 执行 | `db_path`、`focus_source`、`device_id`、`template`、`effective_params`、`semantics_version`、`total`、`returned`、`has_more`、`truncated`、`total_is_exact`、`timeout_s`、`rows` |
| `--list` | `category`、`templates`(`name`、`description`、`category`) |
| `--template-info` | 与 `get_template_info()` 对齐的模板元数据,另加 `template` |

`-n` 仍然限制 `rows` 与 `returned`。`total` 仍是未截断的总数。
`-n` 仍然限制 `rows` 与 `returned`。默认 `total` 等于 `returned`(本页行数);
仅当本页就是完整匹配集合(`has_more` 为 false 且 `offset` 为 0)时
`total_is_exact` 为 true。`--exact-total` 会对匹配集合做 `COUNT`(忽略
`limit` / `offset` / `top_n`)并把 `total_is_exact` 设为 true。存在有限
尾部 `LIMIT` 时,执行器会多取一行来设置 `has_more`,不必先做计数。CTE
内部的有限 `top_n` 不是尾部 `LIMIT`:排名窗口已满时会置 `has_more` /
`truncated`,避免把默认页报成完整集合;精确 `COUNT` 若等于 `returned`
则可清除该信号。`truncated` 表示本次响应不是完整匹配集合(`has_more`、
正 `offset`,或精确 `total` 大于 `returned`)。`timeout_s` 是生效的执行
超时秒数,未限制时为 `null`。`--timeout` / `PT_SNAP_QUERY_TIMEOUT` 是一次
QueryService 调用的共享预算(页面查询与可选 COUNT 共用),作用于所有
模板查询(含 `report peak-memory`),不改变行数上限。非数字的
`PT_SNAP_QUERY_TIMEOUT` 归为 `INVALID_PARAMETER`,不是 `QUERY_FAILED`。

`effective_params` 是应用默认值并按 `choices` 规范化后的参数。带 `-n` 时,
`limit` 是与执行器相同的**尾部** SQL `LIMIT`:已声明的模板 `limit` 与 `-n`
取较小值;渲染后的 SQL 没有尾部 `LIMIT` 时追加 `-n`。CTE 内部的 `top_n`
仍是独立参数,不会改写 `limit`。
`--template-info --json` 包含 `semantics_version`、`interpretation_limits`
以及 `output_schema` 上的字段语义。

`event`、`block`、`allocation` 与 `leak_detection` 在主排序后用 `id` 做稳定
次序。带 `limit` / `offset` 的截断列表应带着相同排序键提高 `offset`
(或 `-n`)续页。`active_memory_callstack_at_event` 没有 `offset`,`-n`
也无法突破 CTE 内的 `top_n`;该模板应增大 `top_n` 续页。

`--json` 失败时 stdout 为空,stderr 为:

```json
Expand Down Expand Up @@ -247,17 +267,19 @@ pt-snap query --template-use leak_detection -n 5
pt-snap query --template-use leak_detection -n 0
```

示例输出(使用 `-n 2`):
示例输出(使用 `-n 2`,默认 `total` 语义):

```
Found 150 results, showing 2:
Found 2 results, showing 2:
{'id': 1, 'address': 4096, 'size': 2048, ...}
{'id': 2, 'address': 8192, 'size': 4096, ...}
... and 148 more (use -n to show more)
... more available (use -n, offset, top_n, or --exact-total)
```

即使输出被截断,"Found N" 的计数也是精确的。`SnapshotAnalyzer.execute_query()`
默认 `max_rows=None`(不截断),与 CLI 在未指定 `-n` / `max_rows` 时一致。
加上 `--exact-total` 时,"Found N" 是匹配行总数,页脚可以给出剩余行数。
`SnapshotAnalyzer.execute_query()` 默认 `max_rows=None`(不截断)且
`exact_total=False`,与 CLI 在未指定 `-n` / `max_rows` 或 `--exact-total` /
`exact_total` 时一致。`timeout_s` 与行数上限相互独立。

CLI 和 Python API 的查询结果包含原始 SQLite 值。模板的 `output_schema`
只是 metadata,查询执行时不会自动应用。需要十六进制地址字符串等转换值时,
Expand Down
14 changes: 12 additions & 2 deletions docs/zh/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,12 @@ for row in result["rows"]:

| 键 | 含义 |
| --- | --- |
| `total` | 限制显示行数前产生的结果总数 |
| `total` | `exact_total=True` 时为匹配集合的 `COUNT`;否则等于已返回行数 |
| `returned` | `rows` 中实际返回的行数 |
| `has_more` | 还有后续页时为 true(尾部 `LIMIT` 多取一行,或内部 `top_n` 窗口已满) |
| `truncated` | 本次响应不是完整匹配集合时为 true |
| `total_is_exact` | `total` 来自 `COUNT`,或本页就是完整匹配集合时为 true |
| `timeout_s` | 生效的执行超时秒数;未限制时为 `None` |
| `device_id` | 本次执行选择的设备 |
| `rows` | 字典形式的查询行(原始 SQLite 值,不含长说明) |
| `template` | 产生这些行的模板名 |
Expand All @@ -113,7 +117,13 @@ for row in result["rows"]:
向 `execute_query()` 传入 `device_id` 可以仅覆盖本次调用的 analyzer 设备。否则依次使用
analyzer 设备;未设置显式 analyzer 数据库时,再使用已解析项目或全局 focus 的设备;
最后使用发现的第一个设备。只有显式 analyzer 数据库而没有 analyzer 设备时,不会继承
配置中的设备。`max_rows=None`、零或负数均表示不限制行数。
配置中的设备。`max_rows=None`、零或负数均表示不限制行数。传入
`exact_total=True` 可得到匹配行 `COUNT`。`timeout_s` 是一次
`execute_query()` 调用的墙钟预算(秒),也可由 `PT_SNAP_QUERY_TIMEOUT`
提供;页面查询与可选 COUNT 共用该预算。该环境变量作用于所有模板查询,
包括 `report peak-memory`。它不改变行数上限。
`active_memory_callstack_at_event` 应增大 `top_n` 续页,`-n` 无法突破
CTE 上限。

查询行包含原始 SQLite 值,不会自动应用模板的 `output_schema` metadata。需要转换后的值
或模型映射时,使用可选的 [ResultMapper API](result-mapper-api.md)。
Expand Down
3 changes: 3 additions & 0 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@ on `pt-snap`; add the option to the specific command:
- `pt-snap query --list --json`
- `pt-snap query --template-info <name> --json`
- `pt-snap query --template-use <name> --json`

Execute results include `has_more` / `truncated`. Diagnostic skills keep
listings bounded; do not treat a page as the complete matching set.
- `pt-snap import <snapshot.pkl> --json`
- `pt-snap split <snapshot.pkl> --output <dir> --slices <n> --json`

Expand Down
Loading
Loading