diff --git a/README.md b/README.md index aa210c1..fcfebf3 100644 --- a/README.md +++ b/README.md @@ -48,9 +48,9 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough. ## Query Templates -7 built-in templates across 3 categories: +6 built-in templates across 3 categories: -- **Basic**: `active_blocks`, `blocks_by_size`, `events_by_action`, `memory_timeline` +- **Basic**: `block`, `event`, `allocation` - **Statistical**: `callstack_analysis`, `memory_peak` - **Business**: `leak_detection` diff --git a/README_zh.md b/README_zh.md index c4b9267..73261ba 100644 --- a/README_zh.md +++ b/README_zh.md @@ -48,9 +48,9 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' ## 查询模板 -7 个内置模板,3 个分类: +6 个内置模板,3 个分类: -- **Basic**: `active_blocks`, `blocks_by_size`, `events_by_action`, `memory_timeline` +- **Basic**: `block`, `event`, `allocation` - **Statistical**: `callstack_analysis`, `memory_peak` - **Business**: `leak_detection` diff --git a/docs/en/querying.md b/docs/en/querying.md index e4a6407..2c5e1b3 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -32,10 +32,9 @@ Raw data lookup. | Template | Description | |----------|-------------| -| `active_blocks` | Currently active (unfreed) memory blocks | -| `blocks_by_size` | Memory blocks sorted by size | -| `events_by_action` | Events grouped by action type | -| `memory_timeline` | Memory allocation timeline | +| `block` | Query memory blocks with flexible field filters | +| `event` | Query memory events with flexible field filters | +| `allocation` | Memory allocation timeline (id, allocated, active, reserved) | ### Statistical Queries diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md index eeb239f..7f3bcb4 100644 --- a/docs/en/quickstart.md +++ b/docs/en/quickstart.md @@ -47,7 +47,7 @@ pt-snap query --template-use memory_peak pt-snap query --template-use leak_detection --params '{"min_size": 1024}' # Query automatically uses the focused device, or you can override it -pt-snap query --template-use active_blocks --device 1 +pt-snap query --template-use block --device 1 --state 1 ``` ## What's Next diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 9464c9d..0a8fc39 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -32,10 +32,9 @@ pt-snap query [--template-use ] [--params ] [--device ] | 模板 | 说明 | |------|------| -| `active_blocks` | 当前活跃(未释放)的内存块 | -| `blocks_by_size` | 按大小排序的内存块 | -| `events_by_action` | 按动作类型分组的事件 | -| `memory_timeline` | 内存分配时间线 | +| `block` | 灵活字段过滤的内存块查询 | +| `event` | 灵活字段过滤的内存事件查询 | +| `allocation` | 内存分配时间线(id, allocated, active, reserved) | ### Statistical Queries diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index be20b54..304fbd9 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -47,7 +47,7 @@ pt-snap query --template-use memory_peak pt-snap query --template-use leak_detection --params '{"min_size": 1024}' # 查询自动使用 focus 中设置的设备,也可以显式覆盖 -pt-snap query --template-use active_blocks --device 1 +pt-snap query --template-use block --device 1 --state 1 ``` ## 下一步 diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 72d8f9b..3cf3457 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -225,7 +225,7 @@ def query_database( pt-snap focus --device 1 # Change device only pt-snap query --list # List templates pt-snap query --template-use leak_detection # Uses focused db and device - pt-snap query --template-use active_blocks --device 0 + pt-snap query --template-use block --device 0 --state 1 pt-snap query custom.db --template-use leak_detection # Override with custom path pt-snap query --template-info leak_detection pt-snap query --list --category basic # List only basic queries diff --git a/src/pt_snap_cli/query/templates/basic/active_blocks.yaml b/src/pt_snap_cli/query/templates/basic/active_blocks.yaml deleted file mode 100644 index f66ef57..0000000 --- a/src/pt_snap_cli/query/templates/basic/active_blocks.yaml +++ /dev/null @@ -1,37 +0,0 @@ -version: "1.0" -queries: - active_blocks: - description: Get active memory blocks (active=1) - devices: - - all - parameters: - device_id: - type: int - default: null - required: false - description: Device ID to query - limit: - type: int - default: 100 - required: false - description: Maximum rows to return - query: | - SELECT * FROM {{ device_block_table }} - WHERE state = 1 - ORDER BY size DESC - LIMIT {{ limit }} - output_schema: - - column: id - type: int - - column: address - type: hex - - column: size - type: int - - column: requestedSize - type: int - - column: state - type: int - - column: allocEventId - type: int - - column: freeEventId - type: int diff --git a/src/pt_snap_cli/query/templates/basic/allocation.yaml b/src/pt_snap_cli/query/templates/basic/allocation.yaml new file mode 100644 index 0000000..49d518a --- /dev/null +++ b/src/pt_snap_cli/query/templates/basic/allocation.yaml @@ -0,0 +1,73 @@ +version: "1.0" +queries: + allocation: + description: Memory allocation timeline — (id, allocated, active, reserved) curve + devices: + - all + parameters: + min_id: + type: int + default: null + required: false + description: Minimum event ID (start of range) + max_id: + type: int + default: null + required: false + description: Maximum event ID (end of range) + min_allocated: + type: int + default: null + required: false + description: Minimum total allocated bytes + min_active: + type: int + default: null + required: false + description: Minimum total active bytes + min_reserved: + type: int + default: null + required: false + description: Minimum memory pool reserved bytes + order_by: + type: str + default: "id" + required: false + description: Column to order by + order_dir: + type: str + default: "ASC" + required: false + description: Sort direction (ASC or DESC) + limit: + type: int + default: 1000 + required: false + description: Maximum rows to return + offset: + type: int + default: 0 + required: false + description: Number of rows to skip + query: | + SELECT id, allocated, active, reserved + FROM {{ device_trace_table }} + WHERE 1=1 + {% if min_id is not none %}AND id >= {{ min_id }}{% endif %} + {% if max_id is not none %}AND id <= {{ max_id }}{% endif %} + {% if min_allocated is not none %}AND allocated >= {{ min_allocated }}{% endif %} + {% if min_active is not none %}AND active >= {{ min_active }}{% endif %} + {% if min_reserved is not none %}AND reserved >= {{ min_reserved }}{% endif %} + ORDER BY {{ order_by }} {{ order_dir }} + LIMIT {{ limit }} + {% if offset > 0 %}OFFSET {{ offset }}{% endif %} + output_schema: + - column: id + type: int + - column: allocated + type: int + - column: active + type: int + - column: reserved + type: int diff --git a/src/pt_snap_cli/query/templates/basic/block.yaml b/src/pt_snap_cli/query/templates/basic/block.yaml new file mode 100644 index 0000000..e7d7ade --- /dev/null +++ b/src/pt_snap_cli/query/templates/basic/block.yaml @@ -0,0 +1,118 @@ +version: "1.0" +queries: + block: + description: Query memory blocks with flexible field filters + devices: + - all + parameters: + id: + type: int + default: null + required: false + description: Block ID + address: + type: int + default: null + required: false + description: Memory address + size: + type: int + default: null + required: false + description: Exact block size in bytes + min_size: + type: int + default: null + required: false + description: Minimum block size + max_size: + type: int + default: null + required: false + description: Maximum block size + requestedSize: + type: int + default: null + required: false + description: Exact user-requested size + allocEventId: + type: int + default: null + required: false + description: Allocation event ID + min_allocEventId: + type: int + default: null + required: false + description: Minimum allocation event ID + max_allocEventId: + type: int + default: null + required: false + description: Maximum allocation event ID + freeEventId: + type: int + default: null + required: false + description: Free event ID + min_freeEventId: + type: int + default: null + required: false + description: Minimum free event ID + max_freeEventId: + type: int + default: null + required: false + description: Maximum free event ID + order_by: + type: str + default: "size" + required: false + description: Column to order by + order_dir: + type: str + default: "DESC" + required: false + description: Sort direction (ASC or DESC) + limit: + type: int + default: 100 + required: false + description: Maximum rows to return + offset: + type: int + default: 0 + required: false + description: Number of rows to skip + query: | + SELECT * FROM {{ device_block_table }} + WHERE 1=1 + {% if id is not none %}AND id = {{ id }}{% endif %} + {% if address is not none %}AND address = {{ address }}{% endif %} + {% if size is not none %}AND size = {{ size }}{% endif %} + {% if min_size is not none %}AND size >= {{ min_size }}{% endif %} + {% if max_size is not none %}AND size <= {{ max_size }}{% endif %} + {% if requestedSize is not none %}AND requestedSize = {{ requestedSize }}{% endif %} + {% if allocEventId is not none %}AND allocEventId = {{ allocEventId }}{% endif %} + {% if min_allocEventId is not none %}AND allocEventId >= {{ min_allocEventId }}{% endif %} + {% if max_allocEventId is not none %}AND allocEventId <= {{ max_allocEventId }}{% endif %} + {% if freeEventId is not none %}AND freeEventId = {{ freeEventId }}{% endif %} + {% if min_freeEventId is not none %}AND freeEventId >= {{ min_freeEventId }}{% endif %} + {% if max_freeEventId is not none %}AND freeEventId <= {{ max_freeEventId }}{% endif %} + ORDER BY {{ order_by }} {{ order_dir }} + LIMIT {{ limit }} + {% if offset > 0 %}OFFSET {{ offset }}{% endif %} + output_schema: + - column: id + type: int + - column: address + type: int + - column: size + type: int + - column: requestedSize + type: int + - column: allocEventId + type: int + - column: freeEventId + type: int diff --git a/src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml b/src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml deleted file mode 100644 index 5020f7a..0000000 --- a/src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml +++ /dev/null @@ -1,37 +0,0 @@ -version: "1.0" -queries: - blocks_by_size: - description: Get blocks filtered by size range - devices: - - all - parameters: - min_size: - type: int - default: 0 - required: false - description: Minimum block size - max_size: - type: int - default: null - required: false - description: Maximum block size - limit: - type: int - default: 100 - required: false - description: Maximum rows to return - query: | - SELECT * FROM {{ device_block_table }} - WHERE size >= {{ min_size }} - {% if max_size is not none %}AND size <= {{ max_size }}{% endif %} - ORDER BY size DESC - LIMIT {{ limit }} - output_schema: - - column: id - type: int - - column: address - type: hex - - column: size - type: int - - column: active - type: int diff --git a/src/pt_snap_cli/query/templates/basic/event.yaml b/src/pt_snap_cli/query/templates/basic/event.yaml new file mode 100644 index 0000000..ee97b20 --- /dev/null +++ b/src/pt_snap_cli/query/templates/basic/event.yaml @@ -0,0 +1,112 @@ +version: "1.0" +queries: + event: + description: Query memory events with flexible field filters + devices: + - all + parameters: + id: + type: int + default: null + required: false + description: Event ID (negative = pre-snapshot synthetic events) + min_id: + type: int + default: null + required: false + description: Minimum event ID (start of range) + max_id: + type: int + default: null + required: false + description: Maximum event ID (end of range) + action: + type: int + default: null + required: false + description: Action type (0=segment_map, 1=segment_unmap, 2=segment_alloc, 3=segment_free, 4=alloc, 5=free_requested, 6=free_completed, 7=workspace_snapshot) + address: + type: int + default: null + required: false + description: Memory address + size: + type: int + default: null + required: false + description: Allocation size in bytes + stream: + type: int + default: null + required: false + description: CUDA/CANN stream ID + min_allocated: + type: int + default: null + required: false + description: Minimum total allocated bytes + min_active: + type: int + default: null + required: false + description: Minimum total active bytes + min_reserved: + type: int + default: null + required: false + description: Minimum memory pool reserved bytes + order_by: + type: str + default: "id" + required: false + description: Column to order by + order_dir: + type: str + default: "ASC" + required: false + description: Sort direction (ASC or DESC) + limit: + type: int + default: 1000 + required: false + description: Maximum rows to return + offset: + type: int + default: 0 + required: false + description: Number of rows to skip + query: | + SELECT * FROM {{ device_trace_table }} + WHERE 1=1 + {% if id is not none %}AND id = {{ id }}{% endif %} + {% if min_id is not none %}AND id >= {{ min_id }}{% endif %} + {% if max_id is not none %}AND id <= {{ max_id }}{% endif %} + {% if action is not none %}AND action = {{ action }}{% endif %} + {% if address is not none %}AND address = {{ address }}{% endif %} + {% if size is not none %}AND size = {{ size }}{% endif %} + {% if stream is not none %}AND stream = {{ stream }}{% endif %} + {% if min_allocated is not none %}AND allocated >= {{ min_allocated }}{% endif %} + {% if min_active is not none %}AND active >= {{ min_active }}{% endif %} + {% if min_reserved is not none %}AND reserved >= {{ min_reserved }}{% endif %} + ORDER BY {{ order_by }} {{ order_dir }} + LIMIT {{ limit }} + {% if offset > 0 %}OFFSET {{ offset }}{% endif %} + output_schema: + - column: id + type: int + - column: action + type: int + - column: address + type: hex + - column: size + type: int + - column: stream + type: int + - column: allocated + type: int + - column: active + type: int + - column: reserved + type: int + - column: callstack + type: str diff --git a/src/pt_snap_cli/query/templates/basic/events_by_action.yaml b/src/pt_snap_cli/query/templates/basic/events_by_action.yaml deleted file mode 100644 index 0cc71fc..0000000 --- a/src/pt_snap_cli/query/templates/basic/events_by_action.yaml +++ /dev/null @@ -1,34 +0,0 @@ -version: "1.0" -queries: - events_by_action: - description: Get events filtered by action type - devices: - - all - parameters: - action: - type: int - default: null - required: true - description: Action type to filter (0=alloc, 1=free) - limit: - type: int - default: 100 - required: false - description: Maximum rows to return - query: | - SELECT * FROM {{ device_trace_table }} - WHERE action = {{ action }} - LIMIT {{ limit }} - output_schema: - - column: id - type: int - - column: action - type: int - - column: timestamp - type: int - - column: address - type: hex - - column: size - type: int - - column: streamId - type: int diff --git a/src/pt_snap_cli/query/templates/basic/memory_timeline.yaml b/src/pt_snap_cli/query/templates/basic/memory_timeline.yaml deleted file mode 100644 index f926d4a..0000000 --- a/src/pt_snap_cli/query/templates/basic/memory_timeline.yaml +++ /dev/null @@ -1,48 +0,0 @@ -version: "1.0" -queries: - memory_timeline: - description: Get memory allocation timeline for analysis - devices: - - all - - "0" - - "1" - parameters: - start_time: - type: float - default: 0 - required: false - description: Start time in seconds - end_time: - type: float - default: null - required: false - description: End time in seconds - limit: - type: int - default: 1000 - required: false - description: Maximum number of records - query: | - SELECT id, action, address, size, allocated, active, reserved - FROM {{ device_trace_table }} - WHERE id >= {{ start_time|int }} - {% if end_time is not none %} - AND id <= {{ end_time|int }} - {% endif %} - ORDER BY id ASC - LIMIT {{ limit }} - output_schema: - - column: id - type: int - - column: action - type: int - - column: address - type: hex - - column: size - type: int - - column: allocated - type: int - - column: active - type: int - - column: reserved - type: int \ No newline at end of file diff --git a/tests/query/test_registry.py b/tests/query/test_registry.py index 6c196ec..c5e2df3 100644 --- a/tests/query/test_registry.py +++ b/tests/query/test_registry.py @@ -191,7 +191,7 @@ def test_list_by_category_basic(self): result = list_by_category("basic") assert "test_basic" in result # Packaged basic templates should also be present - assert "active_blocks" in result + assert "block" in result def test_list_by_category_statistical(self): register_query( diff --git a/tests/test_cli.py b/tests/test_cli.py index 7d9b589..8162424 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -498,7 +498,7 @@ def test_query_list_no_templates(self, sample_db: Path) -> None: assert result.exit_code == 0 # Default packaged templates should be listed assert "Basic Queries:" in result.stdout - assert "active_blocks" in result.stdout + assert "block" in result.stdout assert "Statistical Queries:" in result.stdout assert "Business Queries:" in result.stdout