From 147e4a69f0f83dd47fa0cd0a7fb71be43093c831 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 3 Oct 2026 00:41:25 +0800 Subject: [PATCH] fix(query): normalize missing callstack attribution --- skills/pt-snap-memory-peak-breakdown/SKILL.md | 8 +- .../pt-snap-memory-peak-breakdown/SKILL.md | 8 +- .../active_memory_callstack_at_event.yaml | 17 ++- tests/query/test_callstack_schema_compat.py | 113 ++++++++++++++++++ tests/query/test_template_semantics.py | 20 +++- tests/test_contract_cli_api.py | 71 +++++++++-- 6 files changed, 221 insertions(+), 16 deletions(-) diff --git a/skills/pt-snap-memory-peak-breakdown/SKILL.md b/skills/pt-snap-memory-peak-breakdown/SKILL.md index 9d2ad8e..5ee1f3c 100644 --- a/skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -239,7 +239,13 @@ their event ID carries the range selection forward. blocks have no captured allocation callstack. Report their bytes and block counts under their own labels rather than inventing or inferring a callstack. - A dynamic `[missing callstack]` group is unknown attribution, not static or - preexisting memory. + preexisting memory. With template `semantics_version: 2`, empty strings, + NULLs, and missing allocation-event or callstack links merge into this group + before `top_n` ranking. Retain its bytes, requested bytes, and block count in + dynamic attribution. Older template versions may also return empty labels; + treat those as unknown dynamic attribution rather than dropping them. + Use `category` to distinguish synthetic groups; a display label alone is not + a unique group identity (captured literal labels remain separate). - The callstack template always returns `static` and `preexisting_live_at_event` groups regardless of `top_n`; when dynamic groups exceed `top_n`, the smallest dynamic groups are dropped while these special diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md index 9d2ad8e..5ee1f3c 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-memory-peak-breakdown/SKILL.md @@ -239,7 +239,13 @@ their event ID carries the range selection forward. blocks have no captured allocation callstack. Report their bytes and block counts under their own labels rather than inventing or inferring a callstack. - A dynamic `[missing callstack]` group is unknown attribution, not static or - preexisting memory. + preexisting memory. With template `semantics_version: 2`, empty strings, + NULLs, and missing allocation-event or callstack links merge into this group + before `top_n` ranking. Retain its bytes, requested bytes, and block count in + dynamic attribution. Older template versions may also return empty labels; + treat those as unknown dynamic attribution rather than dropping them. + Use `category` to distinguish synthetic groups; a display label alone is not + a unique group identity (captured literal labels remain separate). - The callstack template always returns `static` and `preexisting_live_at_event` groups regardless of `top_n`; when dynamic groups exceed `top_n`, the smallest dynamic groups are dropped while these special diff --git a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml index 8cb7ece..275a281 100644 --- a/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml +++ b/src/pt_snap_cli/query/templates/business/active_memory_callstack_at_event.yaml @@ -4,11 +4,12 @@ queries: description: Aggregate active memory blocks at an event by allocation callstack, including static memory classification devices: - all - semantics_version: 1 + semantics_version: 2 interpretation_limits: - "Rows mix dynamic, static, and preexisting groups. Use the category column for per-row scope; do not label the whole result as dynamic." - "percent_of_active_blocks is a 0-100 byte percentage of the rows included in the SQL result after min_size, include_static, and top_n truncation of dynamic groups; caller-side max_rows (-n) may truncate further after the percentage is computed. Not of all active memory and not of block counts." - "Static and preexisting groups have no captured allocation callstack." + - "Missing dynamic callstacks form one group before top_n ranking. This includes empty strings, NULL text or IDs, and missing joined allocation events or callstack records; their category remains dynamic_live_at_event." - "Event IDs are ordering markers, not elapsed time." parameters: event_id: @@ -55,7 +56,7 @@ queries: CASE WHEN b.category = 'static' THEN '[static] allocEventId=-1, freeEventId=-1' WHEN b.category = 'preexisting_live_at_event' THEN '[preexisting live] allocEventId=-1' - ELSE COALESCE(t.callstack, '[missing callstack]') + ELSE COALESCE(NULLIF(t.callstack, ''), '[missing callstack]') END AS callstack, b.category, COUNT(*) AS block_count, @@ -66,7 +67,7 @@ queries: FROM active_blocks b LEFT JOIN {{ device_trace_table }} t ON b.allocEventId = t.id - GROUP BY callstack, b.category + GROUP BY NULLIF(t.callstack, ''), b.category ), ranked_dynamic AS ( SELECT @@ -138,7 +139,7 @@ queries: CASE WHEN b.category = 'static' THEN '[static] allocEventId=-1, freeEventId=-1' WHEN b.category = 'preexisting_live_at_event' THEN '[preexisting live] allocEventId=-1' - ELSE COALESCE(cs.callstack, '[missing callstack]') + ELSE COALESCE(NULLIF(cs.callstack, ''), '[missing callstack]') END AS callstack, b.category, COUNT(*) AS block_count, @@ -151,7 +152,9 @@ queries: ON b.allocEventId = t.id LEFT JOIN callstack cs ON t.callstackId = cs.id - GROUP BY callstack, b.category + GROUP BY + CASE WHEN NULLIF(cs.callstack, '') IS NULL THEN NULL ELSE t.callstackId END, + b.category ), ranked_dynamic AS ( SELECT @@ -206,7 +209,9 @@ queries: metric_semantics: identifier scope: mixed interpretation_limits: - - "Static and preexisting groups use synthetic labels rather than a captured allocation callstack. Dynamic rows may be '[missing callstack]' when the alloc event has no callstack." + - "Static and preexisting groups use synthetic labels rather than a captured allocation callstack. Dynamic rows use '[missing callstack]' for empty strings, NULL text or IDs, or missing joined allocation events or callstack records." + - "All missing dynamic callstacks merge before top_n ranking; bytes, requested bytes, and block counts are retained. Missing attribution does not imply static or preexisting memory." + - "Nonempty callstacks are grouped by text in v1 and callstackId in v2. Whitespace-only text and a captured literal '[missing callstack]' are not missing and do not merge into the missing group. Display labels alone are not unique group identities." - column: category type: str units: text diff --git a/tests/query/test_callstack_schema_compat.py b/tests/query/test_callstack_schema_compat.py index 7978333..315b16f 100644 --- a/tests/query/test_callstack_schema_compat.py +++ b/tests/query/test_callstack_schema_compat.py @@ -237,6 +237,119 @@ def test_active_memory_callstack_groups_match_across_layouts(v1_db: Path, v2_db: assert by_callstack["[missing callstack]"]["requested_bytes"] == 500 +@pytest.fixture(params=["v1", "v2"]) +def missing_callstack_db(request: pytest.FixtureRequest, tmp_path: Path) -> Path: + """Include every missing-link shape alongside real and synthetic groups.""" + layout = request.param + create = create_v1_db if layout == "v1" else create_v2_db + path = create(tmp_path / f"missing-{layout}.db") + with sqlite3.connect(path) as conn: + conn.execute("DELETE FROM block_0") + conn.execute("DELETE FROM trace_entry_0") + # Empty text, NULL text, NULL ID, dangling ID, and missing alloc event. + texts = ["", None, None, None, "train.py:10", " ", "[missing callstack]"] + if layout == "v1": + conn.executemany( + "INSERT INTO trace_entry_0 (id, callstack) VALUES (?, ?)", + enumerate(texts, start=1), + ) + else: + conn.execute("DELETE FROM callstack") + conn.executemany( + "INSERT INTO callstack (id, callstack) VALUES (?, ?)", + [(1, ""), (2, None), (5, texts[4]), (6, texts[5]), (7, texts[6])], + ) + conn.executemany( + "INSERT INTO trace_entry_0 (id, callstackId) VALUES (?, ?)", + [(1, 1), (2, 2), (3, None), (4, 404), (5, 5), (6, 6), (7, 7)], + ) + conn.executemany( + "INSERT INTO block_0 (id, size, requestedSize, allocEventId, freeEventId) " + "VALUES (?, ?, ?, ?, ?)", + [ + (1, 100, 90, 1, -1), + (2, 200, 180, 2, -1), + (3, 300, 270, 3, -1), + (4, 400, 360, 4, -1), + (5, 500, 450, 8, -1), # No trace row for alloc event 8. + (6, 600, 540, 5, -1), + (7, 700, 630, 5, -1), # Same real callstack aggregates. + (8, 10, 9, 6, -1), # Whitespace is not empty text. + (9, 20, 18, 7, -1), # Literal label is not missing text. + (10, 50, 45, -1, -1), + (11, 70, 63, -1, 20), + ], + ) + return path + + +@pytest.mark.parametrize("include_static", [True, False]) +@pytest.mark.parametrize("top_n", [-1, 1]) +def test_missing_callstacks_merge_before_ranking_and_preserve_totals( + missing_callstack_db: Path, include_static: bool, top_n: int +) -> None: + rows = _execute( + missing_callstack_db, + "active_memory_callstack_at_event", + {"event_id": 10, "include_static": include_static, "top_n": top_n}, + ) + dynamic = [row for row in rows if row["category"] == "dynamic_live_at_event"] + assert len(dynamic) == (4 if top_n == -1 else 1) + missing = dynamic[0] + assert missing["callstack"] == "[missing callstack]" + assert (missing["block_count"], missing["size_bytes"], missing["requested_bytes"]) == ( + 5, + 1500, + 1350, + ) + if top_n == -1: + assert dynamic[1]["callstack"] == "train.py:10" + assert dynamic[1]["block_count"] == 2 + assert dynamic[1]["size_bytes"] == 1300 + assert [row["callstack"] for row in dynamic[2:]] == ["[missing callstack]", " "] + assert {row["category"] for row in rows} == ( + {"dynamic_live_at_event", "static", "preexisting_live_at_event"} + if include_static + else {"dynamic_live_at_event"} + ) + expected_size = (2830 if top_n == -1 else 1500) + (120 if include_static else 0) + expected_requested = (2547 if top_n == -1 else 1350) + (108 if include_static else 0) + expected_count = (9 if top_n == -1 else 5) + (2 if include_static else 0) + assert sum(row["size_bytes"] for row in rows) == expected_size + assert sum(row["requested_bytes"] for row in rows) == expected_requested + assert sum(row["block_count"] for row in rows) == expected_count + for row in rows: + assert row["percent_of_active_blocks"] == round(row["size_bytes"] * 100 / expected_size, 4) + assert sum(row["percent_of_active_blocks"] for row in rows) == pytest.approx(100, abs=0.0002) + + +def test_active_memory_v2_keeps_nonempty_callstack_ids_separate(v2_db: Path) -> None: + with sqlite3.connect(v2_db) as conn: + conn.execute("INSERT INTO callstack (id, callstack) VALUES (99, 'train.py:10')") + conn.execute("UPDATE trace_entry_0 SET callstackId = 99 WHERE id = 4") + rows = _execute(v2_db, "active_memory_callstack_at_event", {"event_id": 5, "top_n": -1}) + normal = [row for row in rows if row["callstack"] == "train.py:10"] + assert [(row["size_bytes"], row["block_count"]) for row in normal] == [(4096, 1), (1024, 1)] + + +def test_missing_callstack_filter_and_page_keep_sql_denominator(missing_callstack_db: Path) -> None: + params = {"event_id": 10, "min_size": 200, "include_static": False, "top_n": -1} + result = QueryService().execute_query( + "active_memory_callstack_at_event", params=params, db_path=missing_callstack_db, max_rows=1 + ) + assert result.returned == 1 + assert result.has_more is True + missing = result.rows[0] + assert missing["callstack"] == "[missing callstack]" + assert (missing["size_bytes"], missing["requested_bytes"], missing["block_count"]) == ( + 1400, + 1260, + 4, + ) + # The normal 1300-byte group remains in the denominator, beyond max_rows. + assert missing["percent_of_active_blocks"] == round(1400 * 100 / 2700, 4) + + def test_v1_callstack_analysis_pagination_and_total(v1_db: Path) -> None: result = QueryService().execute_query( "callstack_analysis", diff --git a/tests/query/test_template_semantics.py b/tests/query/test_template_semantics.py index 5d19de4..ed4931a 100644 --- a/tests/query/test_template_semantics.py +++ b/tests/query/test_template_semantics.py @@ -60,7 +60,9 @@ def test_annotated_templates_share_a_json_serializable_contract() -> None: for name in _ANNOTATED: template = get_query(name) assert template is not None - assert template.semantics_version == 1 + assert template.semantics_version == ( + 2 if name == "active_memory_callstack_at_event" else 1 + ) assert template.interpretation_limits info = get_template_info(name) assert info is not None @@ -117,3 +119,19 @@ def test_callstack_percent_metadata_matches_truncated_byte_denominator() -> None category = _column("active_memory_callstack_at_event", "category") assert category["scope"] == "mixed" assert "Per-row scope" in " ".join(category["interpretation_limits"]) + + +def test_missing_callstack_contract_covers_normalization_and_group_boundaries() -> None: + column = _column("active_memory_callstack_at_event", "callstack") + limits = " ".join(column["interpretation_limits"]) + for term in ( + "[missing callstack]", + "empty strings", + "NULL text or IDs", + "missing joined allocation events or callstack records", + "merge before top_n", + "callstackId in v2", + "Whitespace-only", + "not unique group identities", + ): + assert term in limits diff --git a/tests/test_contract_cli_api.py b/tests/test_contract_cli_api.py index c36d6d7..41dd866 100644 --- a/tests/test_contract_cli_api.py +++ b/tests/test_contract_cli_api.py @@ -357,7 +357,9 @@ def test_template_semantics_contract_matches_cli_and_api(contract_db: Path) -> N api_info = analyzer.get_template_info(name) assert cli_info == api_info json.dumps(api_info) - assert api_info["semantics_version"] == 1 + assert api_info["semantics_version"] == ( + 2 if name == "active_memory_callstack_at_event" else 1 + ) assert api_info["interpretation_limits"] @@ -627,6 +629,52 @@ def test_query_json_contract_matches_api_semantics(contract_db: Path) -> None: assert payload["total_is_exact"] is True +@pytest.mark.parametrize("layout", ["v1", "v2"]) +def test_missing_callstack_query_json_contract(contract_db: Path, layout: str) -> None: + name = "active_memory_callstack_at_event" + with sqlite3.connect(contract_db) as conn: + if layout == "v1": + conn.executemany( + "INSERT INTO trace_entry_0 (id, callstack) VALUES (?, ?)", + [(1, ""), (2, None)], + ) + else: + conn.execute("CREATE TABLE callstack (id INTEGER PRIMARY KEY, callstack TEXT)") + conn.executemany("INSERT INTO callstack VALUES (?, ?)", [(1, ""), (2, None)]) + for device in (0, 1): + conn.execute(f"ALTER TABLE trace_entry_{device} DROP COLUMN callstack") + conn.execute(f"ALTER TABLE trace_entry_{device} ADD COLUMN callstackId INTEGER") + conn.executemany( + "INSERT INTO trace_entry_0 (id, callstackId) VALUES (?, ?)", [(1, 1), (2, 2)] + ) + params = {"event_id": 2, "top_n": -1} + payload = _json_stdout( + runner.invoke( + app, + [ + "query", + str(contract_db), + "--template-use", + name, + "--params", + json.dumps(params), + "--device", + "0", + "--json", + ], + ) + ) + api_query = _focused_analyzer(contract_db).execute_query(name, params=params, device_id=0) + assert {key: payload[key] for key in api_query} == api_query + assert payload["semantics_version"] == 2 + assert payload["returned"] == 1 + row = payload["rows"][0] + assert row["callstack"] == "[missing callstack]" + assert row["category"] == "dynamic_live_at_event" + assert (row["size_bytes"], row["requested_bytes"], row["block_count"]) == (2560, 2500, 2) + assert row["percent_of_active_blocks"] == 100 + + def test_json_error_contract_keeps_text_errors_on_stdout(contract_db: Path) -> None: text = runner.invoke(app, ["query", str(contract_db), "--template-info", "does_not_exist"]) assert text.exit_code == 1 @@ -666,15 +714,24 @@ def test_overview_contract_matches_cli_and_api_semantics(contract_db: Path) -> N assert payload["focus_source"] == "explicit" -def test_capabilities_template_matches_template_info_json(analyzer: SnapshotAnalyzer) -> None: +@pytest.mark.parametrize("name", ["preexisting_live", "active_memory_callstack_at_event"]) +def test_capabilities_template_matches_template_info_json( + analyzer: SnapshotAnalyzer, name: str +) -> None: capabilities = _json_stdout(runner.invoke(app, ["capabilities", "--json"])) - info = _json_stdout( - runner.invoke(app, ["query", "--template-info", "preexisting_live", "--json"]) - ) - entry = next(item for item in capabilities["templates"] if item["name"] == "preexisting_live") + info = _json_stdout(runner.invoke(app, ["query", "--template-info", name, "--json"])) + entry = next(item for item in capabilities["templates"] if item["name"] == name) shared = {key: info[key] for key in entry} assert shared == entry - assert analyzer.get_template_info("preexisting_live") == entry + assert analyzer.get_template_info(name) == entry + assert ( + next(item for item in analyzer.list_capabilities()["templates"] if item["name"] == name) + == entry + ) + if name == "active_memory_callstack_at_event": + assert entry["semantics_version"] == 2 + callstack = next(col for col in entry["output_schema"] if col["column"] == "callstack") + assert "empty strings, NULL text or IDs" in " ".join(callstack["interpretation_limits"]) def test_overview_error_contract_maps_four_domain_failures(tmp_path: Path) -> None: