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: 1 addition & 1 deletion .agents/quickstart/01-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ pt-snap --version
pt-snap use examples/snapshot.pkl.db

# 执行查询
pt-snap query snapshot.pkl.db --template leak_detection_v2 --params '{"min_size": 1024}'
pt-snap query snapshot.pkl.db --template leak_detection --params '{"min_size": 1024}'

# 列出模板
pt-snap query snapshot.pkl.db --list
Expand Down
10 changes: 5 additions & 5 deletions .agents/quickstart/04-query.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ Fluent API 构建 SQL 查询。

## 预定义模板

位于 `query/templates/` 目录:
位于 `query/templates/` 目录,按分类组织:

1. **leak_detection_v2.yaml** - 内存泄漏检测
2. **callstack_analysis_v2.yaml** - 调用栈分析
3. **memory_timeline_v2.yaml** - 内存时间线
- **Basic**: `active_blocks.yaml`, `blocks_by_size.yaml`, `events_by_action.yaml`, `memory_timeline.yaml`
- **Statistical**: `memory_summary.yaml`, `callstack_analysis.yaml`
- **Business**: `leak_detection.yaml`

## 使用示例

Expand All @@ -74,7 +74,7 @@ executor = QueryExecutor(ctx, template_dir=Path("query/templates"))

# 执行模板查询
results = executor.execute_template(
"leak_detection_v2",
"leak_detection",
params={"min_size": 1024},
device_id=0
)
Expand Down
4 changes: 2 additions & 2 deletions .agents/quickstart/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,10 @@ Models 模块
pt-snap use snapshot.pkl.db

# 2. 执行泄漏检测
pt-snap query snapshot.pkl.db --template leak_detection_v2
pt-snap query snapshot.pkl.db --template leak_detection

# 3. 调用栈分析
pt-snap query snapshot.pkl.db --template callstack_analysis_v2
pt-snap query snapshot.pkl.db --template callstack_analysis
```

## 相关文件
Expand Down
97 changes: 32 additions & 65 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Use `PT_SNAP_DB_PATH` when one shell or agent needs an isolated database without

```bash
export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db
pt-snap query --template-use memory_summary_v2
pt-snap query --template-use memory_summary
```

You can also print the export command after validation:
Expand All @@ -77,13 +77,13 @@ pt-snap use
pt-snap query --list

# Execute query (automatically uses the resolved database context)
pt-snap query --template-use memory_summary_v2
pt-snap query --template-use memory_summary

# Query with parameters
pt-snap query --template-use leak_detection_v2 --params '{"min_size": 1024}'
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'

# Specify device
pt-snap query --template-use active_blocks_v2 --device 0
pt-snap query --template-use active_blocks --device 0
```

#### Resolution Priority
Expand All @@ -99,7 +99,7 @@ Even with context configured, you can still specify a different database on the

```bash
# Use temporarily specified database (does not affect context)
pt-snap query /path/to/other.db --template-use memory_summary_v2
pt-snap query /path/to/other.db --template-use memory_summary
```

#### Legacy Global Configuration
Expand Down Expand Up @@ -142,7 +142,7 @@ Context content example:
**Query without configured database:**

```bash
pt-snap query --template-use memory_summary_v2
pt-snap query --template-use memory_summary
# Error: No database path specified and no database configured.
# Use 'pt-snap use <database_path>' to set a project database, or provide db_path argument.
```
Expand All @@ -152,7 +152,7 @@ pt-snap query --template-use memory_summary_v2
If the resolved database file is deleted or moved, `pt-snap` reports the context source and leaves the context file unchanged:

```bash
pt-snap query --template-use memory_summary_v2
pt-snap query --template-use memory_summary
# Error: Database from project context not found: /path/to/missing.db
# Use 'pt-snap use <new_database_path>' to set a new project database, or provide db_path argument.
```
Expand All @@ -164,9 +164,9 @@ pt-snap query --template-use memory_summary_v2
pt-snap use examples/snapshot_expandable.pkl.db

# 2. Then query directly without repeating path
pt-snap query --template-use memory_summary_v2
pt-snap query --template-use active_blocks_v2 --device 0
pt-snap query --template-use leak_detection_v2
pt-snap query --template-use memory_summary
pt-snap query --template-use active_blocks --device 0
pt-snap query --template-use leak_detection

# 3. View the effective context and source
pt-snap use
Expand Down Expand Up @@ -202,7 +202,8 @@ pt-snap query [--template-use <template_name>] [--params <json>] [--device <id>]
- `--template-use`: Query template name (required unless using --list or --template-info)
- `--params`: Query parameters in JSON format (optional)
- `--device`: Device ID (optional)
- `--list`: List available query templates
- `--list`: List available query templates (grouped by category)
- `--category`: Filter templates by category when using --list (`basic`, `statistical`, `business`)
- `--template-info <template>`: Show detailed information about a specific template (parameters and output schema)

**Examples:**
Expand All @@ -214,17 +215,17 @@ pt-snap query --list

Query using template (leak detection):
```bash
pt-snap query --template-use leak_detection_v2 --params '{"min_size": 1024}'
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
```

Query specific device:
```bash
pt-snap query --template-use active_blocks_v2 --device 0
pt-snap query --template-use active_blocks --device 0
```

View template details:
```bash
pt-snap query --template-info leak_detection_v2
pt-snap query --template-info leak_detection
```

### Query Module Usage
Expand All @@ -233,66 +234,32 @@ The Query module provides powerful memory snapshot query functionality with temp

#### Available Query Templates

1. **leak_detection_v2** - Memory Leak Detection

Detects memory allocations without free events.

```bash
pt-snap query --template-use leak_detection_v2 --params '{"min_size": 1024}'
```

Parameters:
- `min_size`: Minimum leak size (bytes), default 1024
- `device_id`: Device ID
Templates are organized into three categories. List them with `pt-snap query --list` or filter by category with `pt-snap query --list --category <basic|statistical|business>`.

2. **callstack_analysis_v2** - Callstack Analysis

Analyzes callstack information for memory allocations.

```bash
pt-snap query --template-use callstack_analysis_v2
```
**Basic Queries** — raw data lookup:

3. **memory_timeline_v2** - Memory Timeline

Shows timeline information for memory allocations.

```bash
pt-snap query --template-use memory_timeline_v2
```
1. **active_blocks** - Active Memory Blocks
2. **blocks_by_size** - Blocks by Size
3. **events_by_action** - Events by Action
4. **memory_timeline** - Memory Timeline

4. **active_blocks_v2** - Active Memory Blocks

View currently active memory blocks.

```bash
pt-snap query --template-use active_blocks_v2
```
**Statistical Queries** — aggregation and analysis:

5. **memory_summary_v2** - Memory Summary

Display memory usage statistics summary.

```bash
pt-snap query --template-use memory_summary_v2
```
5. **callstack_analysis** - Callstack Analysis
6. **memory_summary** - Memory Summary

6. **blocks_by_size_v2** - Blocks by Size

Display memory blocks sorted by allocation size.

```bash
pt-snap query --template-use blocks_by_size_v2
```
**Business Queries** — domain-specific analysis:

7. **leak_detection** - Memory Leak Detection

7. **events_by_action_v2** - Events by Action

Display events grouped by action type.

```bash
pt-snap query --template-use events_by_action_v2
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
```

Parameters:
- `min_size`: Minimum leak size (bytes), default 0
- `device_id`: Device ID

#### Query Output

Query results are displayed in list format:
Expand Down
Loading
Loading