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
310 changes: 310 additions & 0 deletions benchmarks/active_at_event_capacity.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,310 @@
"""Synthetic text-attribution capacity/differential gate; no pickle or producer.

Default: 1.5M events, three 500k-event shards, 200k active blocks. Uses private
TemporaryDirectory storage and deletes it on success/failure. Both published v1
and native-v2 schemas are supported. Timing includes normal validation/hashing;
work bytes measure serialized fetched/output values, not process RSS.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import sqlite3
import tempfile
import time
from contextlib import closing
from dataclasses import asdict
from pathlib import Path

from pt_snap_cli.core.dataset_contract import ACTION_NAMES, BLOCK_STATES
from pt_snap_cli.core.dataset_sources import QueryBudget
from pt_snap_cli.core.errors import QueryExecutionError
from pt_snap_cli.core.models import ImportMetadata
from pt_snap_cli.core.native_dataset_contract import NATIVE_FORMAT, cache_identity
from pt_snap_cli.core.query_service import QueryService

SCHEMA = """CREATE TABLE dictionary ("table" TEXT,"column" TEXT,"key" TEXT,"value" TEXT);
CREATE TABLE trace_entry_0 (id INTEGER PRIMARY KEY,action INTEGER,address INTEGER,
size INTEGER,stream INTEGER,allocated INTEGER,active INTEGER,reserved INTEGER,callstack TEXT);
CREATE TABLE block_0 (id INTEGER PRIMARY KEY,address INTEGER,size INTEGER,
requestedSize INTEGER,state INTEGER,allocEventId INTEGER,freeEventId INTEGER);"""


def digest(path):
with path.open("rb") as file:
value = hashlib.sha256()
for chunk in iter(lambda: file.read(1024 * 1024), b""):
value.update(chunk)
return value.hexdigest()


def inventory(root):
return {str(path.relative_to(root)): digest(path) for path in root.rglob("*") if path.is_file()}


def build_case(root: Path, capacity=500_000, active=200_000, groups=32, layout="v1"):
"""Build a bounded deterministic dataset plus full-text standalone reference.

Half the allocations are in each of the first two owners. Completed frees
are in the third, after the target. Native local stack IDs deliberately name
different texts in different shards; global grouping must use their full text.
"""
if not (2 <= active <= capacity <= 500_000 and active % 2 == 0 and 1 <= groups <= active):
raise ValueError("Require even 2<=active<=capacity<=500000 and 1<=groups<=active")
root.mkdir()
dataset = root / "dataset"
(dataset / "device_0").mkdir(parents=True)
half = active // 2

def occupied(count):
return 8 * (6 * (count // 3) + (count % 3) * (count % 3 + 1) // 2)

metadata = asdict(
ImportMetadata(
1,
2,
"0" * 64,
0,
"synthetic.sql",
None,
"synthetic-capacity-benchmark",
"1",
"2026-10-11T00:00:00+00:00",
)
)
records = []
for index in range(3):
lo, hi = index * capacity, (index + 1) * capacity - 1
file = f"device_0/slice_{index:05d}.db"
path = dataset / file
with closing(sqlite3.connect(path)) as conn, conn:
conn.executescript(
SCHEMA
if layout == "v1"
else SCHEMA.replace("callstack TEXT", "callstackId INTEGER")
)
conn.executemany(
"INSERT INTO dictionary VALUES (?,?,?,?)",
[
("trace_entry_0", "action", str(i), name)
for i, name in enumerate(
ACTION_NAMES if layout == "v1" else (*ACTION_NAMES, "oom")
)
]
+ [("block_0", "state", str(i), name) for i, name in BLOCK_STATES],
)
if layout == "v2":
conn.execute("CREATE TABLE callstack (id INTEGER PRIMARY KEY,callstack TEXT)")
conn.executemany(
"INSERT INTO callstack VALUES (?,?)",
((i + 1, f"stack-{(i + index) % groups:06d}") for i in range(groups)),
)
conn.execute(
"CREATE TABLE pt_snap_block_reference (blockId INTEGER PRIMARY KEY,stream INTEGER,allocCallstack TEXT,freeCallstack TEXT)"
)
columns = ",".join(
f'"{key}" {"INTEGER" if isinstance(value, int) or key == "requested_device" else "TEXT"}'
for key, value in metadata.items()
)
conn.execute(f"CREATE TABLE pt_snap_metadata (id INTEGER PRIMARY KEY,{columns})")
conn.execute(
"INSERT INTO pt_snap_metadata VALUES ("
+ ",".join("?" for _ in range(len(metadata) + 1))
+ ")",
[1, *metadata.values()],
)

def trace(lo=lo, hi=hi, index=index):
for event in range(lo, hi + 1):
position = event - lo
ordinal = position + (half if index == 1 else 0)
action = (
4
if index < 2 and position < half
else 6 if index == 2 and position < active else 7
)
stack = ordinal % groups
live = (
occupied(index * half + min(position + 1, half))
if index < 2
else occupied(active) - occupied(min(position + 1, active))
)
yield (
event,
action,
ordinal * 32,
8 * (1 + ordinal % 3),
0,
live,
live,
occupied(active),
f"stack-{stack:06d}" if layout == "v1" else (stack - index) % groups + 1,
)

conn.executemany("INSERT INTO trace_entry_0 VALUES (?,?,?,?,?,?,?,?,?)", trace())
count = half if index == 0 else active
conn.executemany(
"INSERT INTO block_0 VALUES (?,?,?,?,?,?,?)",
(
(
ordinal if ordinal < half else capacity + ordinal - half,
ordinal * 32,
8 * (1 + ordinal % 3),
8,
1,
ordinal if ordinal < half else capacity + ordinal - half,
2 * capacity + ordinal,
)
for ordinal in range(count)
),
)
if layout == "v2":
conn.execute(
"INSERT INTO pt_snap_block_reference SELECT id,0,NULL,NULL FROM block_0"
)
record = {"index": index, "startEventId": lo, "endEventId": hi, "file": file, "ready": True}
if layout == "v2":
record.update(startPosition=lo, endPosition=hi, sha256=digest(path))
records.append(record)
manifest = {
"schemaVersion": 1,
"status": "complete",
"sourceFile": "synthetic.sql",
"devices": {
"0": {
"eventCount": capacity * 3,
"sliceCount": 3,
"readySlices": [0, 1, 2],
"slices": records,
}
},
}
if layout == "v2":
manifest.update(
format=NATIVE_FORMAT,
identity=cache_identity("0" * 64, None, capacity),
metadata=metadata,
omittedDevices=[],
)
else:
manifest.update(eventsPerSlice=capacity, cacheHash="")
(dataset / "manifest.json").write_text(json.dumps(manifest))
single = root / "standalone.db"
with closing(sqlite3.connect(single, uri=True)) as conn:
conn.executescript(SCHEMA)
for record in records:
conn.execute(
"ATTACH DATABASE ? AS src", [(dataset / record["file"]).as_uri() + "?mode=ro"]
)
if record["index"] == 0:
conn.execute("INSERT INTO dictionary SELECT * FROM src.dictionary")
if layout == "v1":
conn.execute("INSERT INTO trace_entry_0 SELECT * FROM src.trace_entry_0")
else:
conn.execute(
"INSERT INTO trace_entry_0 SELECT t.id,t.action,t.address,t.size,t.stream,t.allocated,t.active,t.reserved,c.callstack FROM src.trace_entry_0 t LEFT JOIN src.callstack c ON c.id=t.callstackId"
)
conn.execute("INSERT OR REPLACE INTO block_0 SELECT * FROM src.block_0")
conn.commit()
conn.execute("DETACH DATABASE src")
return dataset, single


def run_case(root, capacity, active, groups, layout, timeout):
dataset, single = build_case(root, capacity, active, groups, layout)
before = inventory(root)
results = []
with closing(QueryService()) as service:
for template, params in (
("active_blocks_at_event", {"limit": 20}),
("active_memory_callstack_at_event", {"top_n": 20}),
):
params["event_id"] = 2 * capacity - 1
budget = QueryBudget(timeout, time.monotonic())
started = time.monotonic()
result = service.execute_query(
template, params, db_path=dataset, exact_total=True, _budget=budget
)
elapsed = time.monotonic() - started
expected = service.execute_query(
template, params, db_path=single, exact_total=True, timeout_s=timeout
)
fields = set(expected.rows[0]) if expected.rows else set()
assert [{key: row[key] for key in fields} for row in result.rows] == expected.rows
assert (
result.total
== expected.total
== (active if template == "active_blocks_at_event" else groups)
)
coverage = result.scope["source_coverage"]
assert (
coverage["active_blocks"]
== coverage["allocation_events_resolved"]
== coverage["free_events_resolved"]
== active
)
assert budget.work_rows < 150
results.append(
{
"template": template,
"elapsed_s": elapsed,
"work_rows": budget.work_rows,
"work_bytes": budget.work_bytes,
"total": result.total,
"returned": result.returned,
}
)
rejected = False
try:
service.execute_query(
"active_blocks_at_event",
{"event_id": 2 * capacity - 1, "limit": -1},
db_path=dataset,
timeout_s=timeout,
)
except QueryExecutionError as error:
if "work budget" not in str(error):
raise
rejected = True
if active > 100_000:
assert rejected
assert inventory(root) == before
return {
"layout": layout,
"events": 3 * capacity,
"active": active,
"queries": results,
"unbounded_output_rejected": rejected,
"standalone_differential": "passed",
"source_unchanged": True,
}


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--capacity", type=int, default=500_000)
parser.add_argument("--active", type=int, default=200_000)
parser.add_argument("--groups", type=int, default=32)
parser.add_argument("--layout", choices=("v1", "v2"), default="v1")
parser.add_argument("--timeout", type=float, default=120)
args = parser.parse_args()
with tempfile.TemporaryDirectory(prefix="pt-snap-active-capacity-") as temporary:
print(
json.dumps(
run_case(
Path(temporary) / "case",
args.capacity,
args.active,
args.groups,
args.layout,
args.timeout,
),
indent=2,
)
)


if __name__ == "__main__":
main()
17 changes: 15 additions & 2 deletions docs/en/sharded-snapshotdb.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,8 +230,21 @@ restricted real interval, dataset fingerprint and boundary exclusion. Totals and
pagination apply to this scope, **not** to an implicitly truncated full dataset.
Caller parameter defaults in CLI `effective_params` are additionally constrained
by `scope`. Point-event `active_blocks_at_event` and
`active_memory_callstack_at_event` now resolve alloc/free/full stack sources in
bounded batches before grouping/ranking, including original no-extension artifacts.
`active_memory_callstack_at_event` prove alloc/free/full-stack coverage before
pagination/ranking, including future completed-free owners and original no-extension
artifacts. Text-only v1/v2 queries use read-only SQL reduction when the required
owners fit SQLite's ATTACH limit: coverage and full-text groups stay in SQL, and
only returned block details are hydrated. Global top_n percentages still use all
included groups before max_rows. Ordered-frame inputs or larger owner sets retain
the budgeted source-batch fallback. SQL scans/sorts share the timeout; reduced
rows, hydrated sources and output still consume the work budget. A finite page
can therefore succeed where unbounded output exceeds the same budget.

The opt-in synthetic gate `PYTHONPATH=src python benchmarks/active_at_event_capacity.py`
(and `--layout v2`) checks 1.5 million events / three 500000-event shards / 200000
active blocks, page20 and top20, exact totals, standalone differential results,
read-only hashes and rejection of unbounded block output. It creates and removes
private temporary data; it is not producer/GUI or general RSS/performance evidence.
See [point-event attribution](querying.md#dataset-point-event-attribution) for
lifecycle identity, separate source/frame coverage, and the optional versioned
ordered-frame reader interface. Dataset-global built-ins use the explicit P3 matrix
Expand Down
15 changes: 13 additions & 2 deletions docs/zh/sharded-snapshotdb.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,8 +190,19 @@ with SnapshotAnalyzer(Path("/capture/snapshot.pkl.msinsight"), device_id=0) as a
selector。输出 `scope` 标识实际 DB/device/slice、受限真实区间、数据集指纹和边界排除。
总数和分页针对该 scope,**不是**隐式截断的整份数据集。CLI `effective_params` 的调用者
参数默认值另受 `scope` 约束。定点 `active_blocks_at_event` 和
`active_memory_callstack_at_event` 现于分组/排名前批量解析 alloc/free/完整栈来源,
原版无扩展产物也适用。生命周期身份、独立来源/frame 覆盖及版本化有序 frame reader
`active_memory_callstack_at_event` 在分页/排名前验证全部 alloc/free/完整栈来源覆盖,
包括未来 completed-free 所在片,原版无扩展产物也适用。纯文本 v1/v2 查询在所需 owner
集合不超过 SQLite ATTACH 上限时使用只读 SQL 归约:全量覆盖与完整文本分组保留在 SQL
内,仅补充返回 block 的来源详情。全局 top_n 百分比分母仍是 max_rows 前的全部入选组。
有序 frame 输入或更大的 owner 集合保留受预算约束的来源批次回退。SQL 扫描/排序共用
超时;归约行、实际补充来源及输出仍计入工作预算,因此有限页可成功而无界输出仍超限。

可选合成验收 `PYTHONPATH=src python benchmarks/active_at_event_capacity.py`(以及
`--layout v2`)检查 150 万事件 / 三个 500000 事件分片 / 20 万活跃 block、page20、
top20、精确总数、单库差分、只读哈希和无界 block 输出硬失败。它创建并清理私有临时
数据,不是 producer/GUI 验收或通用 RSS/性能保证。

生命周期身份、独立来源/frame 覆盖及版本化有序 frame reader
接口详见[定点归因](querying.md#数据集定点事件归因)。数据集全局内建查询遵循 P3 矩阵
及累计工作上限;任意 SQL/自定义 override 明确失败,不静默选首片/最新片。单库真实
事件 peak/gap 与全部 action 完整文本栈统计版本在相同合同中明确说明。
Expand Down
Loading
Loading