Repository navigation
feat: add peak memory attribution reports - #63
Conversation
Add event-scoped active block and callstack attribution queries plus an initial peak-memory report command so users can inspect peak composition without manual SQL scripts. Also package categorized query templates in built artifacts and cover the new workflow with service, template, and CLI tests.
Update brittle _safe_call tests to mock the CLI entrypoint instead of Click internals, align invalid metric expectations with Typer's argument validation, and format the new template tests so CI lint and type checks pass consistently across environments.
codeasier
left a comment
There was a problem hiding this comment.
Code review
Found 2 issues.
| ) | ||
| raise typer.Exit(1) from None | ||
| except DatabaseMissingError: | ||
| typer.secho(f"Error: Database not found: {db_path}", fg=typer.colors.RED) |
There was a problem hiding this comment.
When report peak-memory is run without an explicit db_path, a stale focused/configured database will reach this handler with db_path == None, so the user sees Database not found: None. The existing query flow re-resolves focus and reports the focused source/path; this new command should surface the resolved missing path too so users can fix the stale focus.
There was a problem hiding this comment.
Fixed in the report CLI handler. It now re-resolves focus on DatabaseMissingError, reports the actual focused source/path, and includes the focus file when available instead of printing Database not found: None.
| WHERE size >= {{ min_size|int }} | ||
| AND ( | ||
| {% if include_static %}(allocEventId = -1 AND freeEventId = -1) OR{% endif %} | ||
| (allocEventId != -1 AND allocEventId <= {{ event_id|int }} AND (freeEventId = -1 OR freeEventId > {{ event_id|int }})) |
There was a problem hiding this comment.
This active-block predicate omits live blocks encoded with freeEventId IS NULL. Existing templates treat freeEventId IS NULL OR freeEventId < 0 as not freed, so snapshots using NULL for open allocations will undercount peak active memory and misattribute callstack totals. The sibling statistical/active_blocks_at_event.yaml uses the same predicate and likely needs the same fix.
There was a problem hiding this comment.
Fixed in both active-block templates. The live-block predicate now treats freeEventId IS NULL and other negative values as not freed, matching the existing repository semantics used by leak_detection. Added targeted tests for both active_blocks_at_event and active_memory_callstack_at_event.
Document the new event-scoped peak attribution queries and the peak-memory report command, including the lifecycle rules behind active blocks, static memory handling, allocator gap interpretation, and example CLI usage in both English and Chinese docs.
Make report peak-memory surface the resolved missing database path for stale focused configurations, and treat freeEventId NULL or negative values as not-freed in the new active block attribution queries. Cover both cases with focused CLI and query-template tests.
📝 Description
This PR adds a user-facing peak memory attribution workflow to
pt-snap, so users can move from "find the peak" to "explain what was live at that moment" without writing manual SQL or Python scripts.User-visible changes in this PR:
New Statistical Query:
active_blocks_at_eventallocEventId <= event_idfreeEventId = -1orfreeEventId > event_idallocEventId = -1 AND freeEventId = -1New Statistical Query:
allocator_gapallocated,active, andreserved.reserved - activeandreserved - allocated.New Business Query:
active_memory_callstack_at_eventNew CLI report command:
pt-snap report peak-memorymemory_peakallocator_gapactive_memory_callstack_at_event--metric active|allocated|reserved--include-static|--exclude-static--limit--jsonPackaging fix
Basic usage examples now supported:
🔗 Related Issue
Fixes #62
🧪 Testing
conda run -n cc pytestconda run -n cc python -m buildconda run -n cc ruff check .conda run -n cc black --check .conda run -n cc python -m basedpyright --pythonpath "$(conda run -n cc python -c 'import sys; print(sys.executable)')"✅ Checklist
📸 Screenshots (if applicable)
N/A
📋 Additional Notes
pt-snap report peak-memoryworkflow.