From 87a8fd4b39c0915e7daf27fb4fe608305e1bf89f Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 18 Apr 2026 18:52:57 +0800 Subject: [PATCH] feat: replace memory_summary with memory_peak query template - Replace memory_summary.yaml with memory_peak.yaml, changing from block-table statistics to trace_entry-based peak memory metrics (MAX(allocated), MAX(active), MAX(reserved)) with corresponding earliest event IDs for each peak - Add optional start_id / end_id parameters for event ID range filtering - Update all documentation references - Update test assertion in test_registry.py --- .agents/quickstart/04-query.md | 2 +- README.md | 4 +- README_zh.md | 4 +- docs/en/focus-management.md | 10 ++-- docs/en/querying.md | 2 +- docs/en/quickstart.md | 2 +- docs/zh/focus-management.md | 10 ++-- docs/zh/querying.md | 2 +- docs/zh/quickstart.md | 2 +- .../query/templates/memory_peak.yaml | 60 +++++++++++++++++++ .../query/templates/memory_summary.yaml | 26 -------- tests/query/test_registry.py | 2 +- 12 files changed, 80 insertions(+), 46 deletions(-) create mode 100644 src/pt_snap_cli/query/templates/memory_peak.yaml delete mode 100644 src/pt_snap_cli/query/templates/memory_summary.yaml diff --git a/.agents/quickstart/04-query.md b/.agents/quickstart/04-query.md index 8615e2a..8024428 100644 --- a/.agents/quickstart/04-query.md +++ b/.agents/quickstart/04-query.md @@ -58,7 +58,7 @@ Fluent API 构建 SQL 查询。 位于 `query/templates/` 目录,按分类组织: - **Basic**: `active_blocks.yaml`, `blocks_by_size.yaml`, `events_by_action.yaml`, `memory_timeline.yaml` -- **Statistical**: `memory_summary.yaml`, `callstack_analysis.yaml` +- **Statistical**: `memory_peak.yaml`, `callstack_analysis.yaml` - **Business**: `leak_detection.yaml` ## 使用示例 diff --git a/README.md b/README.md index 9fb3e23..aa210c1 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ pt-snap focus examples/snapshot_expandable.pkl.db --device 0 pt-snap query --list # Run a query (automatically uses the focused device) -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # Detect potential memory leaks pt-snap query --template-use leak_detection --params '{"min_size": 1024}' @@ -51,7 +51,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough. 7 built-in templates across 3 categories: - **Basic**: `active_blocks`, `blocks_by_size`, `events_by_action`, `memory_timeline` -- **Statistical**: `callstack_analysis`, `memory_summary` +- **Statistical**: `callstack_analysis`, `memory_peak` - **Business**: `leak_detection` See [Querying](docs/en/querying.md) for details. diff --git a/README_zh.md b/README_zh.md index 4b2a8e5..c4b9267 100644 --- a/README_zh.md +++ b/README_zh.md @@ -20,7 +20,7 @@ pt-snap focus examples/snapshot_expandable.pkl.db --device 0 pt-snap query --list # 运行查询(自动使用 focus 中设置的设备) -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # 检测潜在内存泄漏 pt-snap query --template-use leak_detection --params '{"min_size": 1024}' @@ -51,7 +51,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' 7 个内置模板,3 个分类: - **Basic**: `active_blocks`, `blocks_by_size`, `events_by_action`, `memory_timeline` -- **Statistical**: `callstack_analysis`, `memory_summary` +- **Statistical**: `callstack_analysis`, `memory_peak` - **Business**: `leak_detection` 详见 [Querying](docs/zh/querying.md)。 diff --git a/docs/en/focus-management.md b/docs/en/focus-management.md index e99a289..1ac9be2 100644 --- a/docs/en/focus-management.md +++ b/docs/en/focus-management.md @@ -34,7 +34,7 @@ When a shell or agent needs an isolated database without changing project focus: ```bash export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak ``` Or validate and print the export command in one step: @@ -57,10 +57,10 @@ Even with focus configured, you can temporarily specify a different database or ```bash # Uses this database temporarily, does not affect saved focus -pt-snap query /path/to/other.db --template-use memory_summary +pt-snap query /path/to/other.db --template-use memory_peak # Override device (ignores focused device_id) -pt-snap query --template-use memory_summary --device 2 +pt-snap query --template-use memory_peak --device 2 ``` ## Legacy Global Configuration @@ -101,7 +101,7 @@ pt-snap config --clear # Clear global configuration **No focus configured:** ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # Error: No database path specified and no database configured. # Use 'pt-snap focus ' to set a project database, or provide db_path argument. ``` @@ -109,7 +109,7 @@ pt-snap query --template-use memory_summary **Database file not found:** ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # Error: Database from project focus not found: /path/to/missing.db # Use 'pt-snap focus ' to set a new project database, or provide db_path argument. ``` diff --git a/docs/en/querying.md b/docs/en/querying.md index ae5e7e4..e4a6407 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -44,7 +44,7 @@ Aggregation and analysis. | Template | Description | |----------|-------------| | `callstack_analysis` | Analyze callstack information | -| `memory_summary` | Memory usage statistics | +| `memory_peak` | Peak memory metrics | ### Business Queries diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md index a367d00..eeb239f 100644 --- a/docs/en/quickstart.md +++ b/docs/en/quickstart.md @@ -37,7 +37,7 @@ pt-snap query --list ### Step 3: Run a Query ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak ``` ### Step 4: Try Advanced Queries diff --git a/docs/zh/focus-management.md b/docs/zh/focus-management.md index 24b5d93..acdce8d 100644 --- a/docs/zh/focus-management.md +++ b/docs/zh/focus-management.md @@ -34,7 +34,7 @@ pt-snap focus --device 1 ```bash export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak ``` 或在验证数据库的同时输出 export 命令: @@ -57,10 +57,10 @@ pt-snap focus ```bash # 仅本次查询使用该数据库,不影响已保存的 focus -pt-snap query /path/to/other.db --template-use memory_summary +pt-snap query /path/to/other.db --template-use memory_peak # 覆盖设备(忽略 focus 中的 device_id) -pt-snap query --template-use memory_summary --device 2 +pt-snap query --template-use memory_peak --device 2 ``` ## Legacy 全局配置 @@ -101,7 +101,7 @@ pt-snap config --clear # 清除全局配置 **未设置焦点时查询:** ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # Error: No database path specified and no database configured. # Use 'pt-snap focus ' to set a project database, or provide db_path argument. ``` @@ -109,7 +109,7 @@ pt-snap query --template-use memory_summary **数据库文件不存在:** ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak # Error: Database from project focus not found: /path/to/missing.db # Use 'pt-snap focus ' to set a new project database, or provide db_path argument. ``` diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 191eff6..9464c9d 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -44,7 +44,7 @@ pt-snap query [--template-use ] [--params ] [--device ] | 模板 | 说明 | |------|------| | `callstack_analysis` | 调用栈分析 | -| `memory_summary` | 内存使用统计摘要 | +| `memory_peak` | 峰值内存指标 | ### Business Queries diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index 59c1903..be20b54 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -37,7 +37,7 @@ pt-snap query --list ### 第三步:运行查询 ```bash -pt-snap query --template-use memory_summary +pt-snap query --template-use memory_peak ``` ### 第四步:尝试高级查询 diff --git a/src/pt_snap_cli/query/templates/memory_peak.yaml b/src/pt_snap_cli/query/templates/memory_peak.yaml new file mode 100644 index 0000000..6f17a89 --- /dev/null +++ b/src/pt_snap_cli/query/templates/memory_peak.yaml @@ -0,0 +1,60 @@ +version: "1.0" +queries: + memory_peak: + category: statistical + description: Get peak memory metrics from trace events with corresponding event IDs + devices: + - all + parameters: + start_id: + type: int + default: null + required: false + description: Start event ID for range filtering + end_id: + type: int + default: null + required: false + description: End event ID for range filtering + query: | + SELECT + (SELECT MAX(allocated) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) as peak_allocated, + (SELECT MIN(id) FROM {{ device_trace_table }} + WHERE allocated = (SELECT MAX(allocated) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) + {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} + ) as peak_allocated_event_id, + (SELECT MAX(active) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) as peak_active, + (SELECT MIN(id) FROM {{ device_trace_table }} + WHERE active = (SELECT MAX(active) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) + {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} + ) as peak_active_event_id, + (SELECT MAX(reserved) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) as peak_reserved, + (SELECT MIN(id) FROM {{ device_trace_table }} + WHERE reserved = (SELECT MAX(reserved) FROM {{ device_trace_table }} + {% if start_id is not none %}WHERE id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}WHERE id <= {{ end_id|int }}{% endif %} + ) + {% if start_id is not none %}AND id >= {{ start_id|int }}{% if end_id is not none %} AND id <= {{ end_id|int }}{% endif %}{% elif end_id is not none %}AND id <= {{ end_id|int }}{% endif %} + ) as peak_reserved_event_id + output_schema: + - column: peak_allocated + type: int + - column: peak_allocated_event_id + type: int + - column: peak_active + type: int + - column: peak_active_event_id + type: int + - column: peak_reserved + type: int + - column: peak_reserved_event_id + type: int diff --git a/src/pt_snap_cli/query/templates/memory_summary.yaml b/src/pt_snap_cli/query/templates/memory_summary.yaml deleted file mode 100644 index bca80d5..0000000 --- a/src/pt_snap_cli/query/templates/memory_summary.yaml +++ /dev/null @@ -1,26 +0,0 @@ -version: "1.0" -queries: - memory_summary: - category: statistical - description: Get memory statistics by device - devices: - - all - parameters: - device_id: - type: int - default: 0 - required: false - description: Device ID to query - query: | - SELECT - COUNT(*) as block_count, - SUM(size) as total_size, - AVG(size) as avg_size - FROM {{ device_block_table }} - output_schema: - - column: block_count - type: int - - column: total_size - type: int - - column: avg_size - type: float diff --git a/tests/query/test_registry.py b/tests/query/test_registry.py index 2a0eec6..6c196ec 100644 --- a/tests/query/test_registry.py +++ b/tests/query/test_registry.py @@ -200,7 +200,7 @@ def test_list_by_category_statistical(self): result = list_by_category("statistical") assert "test_stat" in result - assert "memory_summary" in result + assert "memory_peak" in result def test_list_by_category_business(self): register_query(QueryTemplate(name="test_biz", query="SELECT 1", category="business"))