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
8 changes: 7 additions & 1 deletion skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
113 changes: 113 additions & 0 deletions tests/query/test_callstack_schema_compat.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
20 changes: 19 additions & 1 deletion tests/query/test_template_semantics.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
71 changes: 64 additions & 7 deletions tests/test_contract_cli_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]


Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Loading