Skip to content
Closed
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
34 changes: 34 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,39 @@ deterministic names, replay validation, and failure-safe publication.

See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.

Complete compatibility-v1 sharded artifacts can be focused by directory or
`manifest.json`, without the archived pickle. See [dataset focus and addressing](docs/en/sharded-snapshotdb.md#complete-dataset-focus-and-addressing-p1)
for read-only overview, event routing, `--slice`, and explicit cross-slice limits.

Opt into a **native, not msinsight-compatible** dataset with
`pt-snap import snapshot.pkl --events-per-slice 50000 --output-dir captures --json`.
The output is `captures/snapshot.pkl.pt-snap-native-v2/`; default standalone import
is unchanged. Reuse validates all shards and content/options/semantic versions.
Nonmatching recognized targets require `--force`; unknown targets are preserved.
Publication/focus failures are compensated, with explicit recovery evidence if
rollback fails (force is not a single crash-atomic swap). See the
[native import guide](docs/en/quickstart.md#optional-import-a-native-sharded-dataset).
Dataset `event` addressing and point-event `active_blocks_at_event` /
`active_memory_callstack_at_event` share batched cross-shard alloc/free sources,
including original artifacts without extensions. Built-in global peaks, event pages,
canonical stack statistics, deduplicated lifecycles, terminal leak candidates and
`report peak-memory` share bounded core semantics; custom SQL/overrides remain unsupported
on datasets. See the [global support matrix](docs/en/querying.md#dataset-global-built-in-support-p3)
and [dataset attribution and coverage](docs/en/querying.md#dataset-point-event-attribution).

Explicit `pt-snap import snapshot.pkl --format msinsight --json` produces
`snapshot.pkl.msinsight/` for the fixed msinsight revision's **same original
pickle + adjacent cache** entrance. Inline stacks cost more space than native
interning. Existing compatible targets are never replaced, even with `--force`;
only fully validated identical pt-snap caches are reused. GUI acceptance remains
**pending/not run**; hash equality alone is not acceptance. See
[compatible export and limits](docs/en/sharded-snapshotdb.md#explicit-msinsight-compatible-export-p2).

See [offline interoperability acceptance and bounded performance](docs/en/interop-acceptance.md)
for the two fixed-version chains, deterministic reference tools, honest three-mode
measurements and the explicitly **pending/not-run GUI checklist**. Diagnostic skills
accept explicitly selected complete validated datasets, not arbitrary directories.

## Commands

| Command | Description |
Expand Down Expand Up @@ -98,6 +131,7 @@ See the [documentation index](docs/README.md) for all English and Chinese guides
| Splitting snapshots | [Splitting Snapshots](docs/en/splitting.md) |
| Agent skills | [Agent Skills](docs/en/skills.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Sharded protocols, native import and compatibility limits | [Sharded SnapshotDB protocol](docs/en/sharded-snapshotdb.md) |
| Python API | [SnapshotAnalyzer API](docs/en/snapshot-analyzer-api.md) |
| Result mapping utility | [ResultMapper API](docs/en/result-mapper-api.md) |

Expand Down
27 changes: 27 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,32 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices

完整的入门指南见 [Quick Start](docs/zh/quickstart.md)。

完整兼容 v1 分片产物可以目录或 `manifest.json` 为 focus,无需已归档 pickle。
只读 overview、事件路由、`--slice` 和跨片限制见
[完整数据集 focus 与寻址](docs/zh/sharded-snapshotdb.md#完整数据集-focus-与寻址p1)。

用 `pt-snap import snapshot.pkl --events-per-slice 50000 --output-dir captures --json`
显式生成**原生、非 msinsight 兼容**数据集 `captures/snapshot.pkl.pt-snap-native-v2/`。
默认单库导入不变;复用校验全部片及内容/选项/语义版本。不匹配的已识别目标须
`--force`,未知目标保留。发布/focus 失败会补偿,回滚自身失败则保留并报告恢复证据
(force 不是单次崩溃原子 swap)。详见
[原生分库导入](docs/zh/quickstart.md#可选导入原生分库数据集)。数据集 `event` 寻址及定点
`active_blocks_at_event` / `active_memory_callstack_at_event` 共用跨片 alloc/free 批量来源,
原版无扩展产物也适用。内建全局峰值、事件分页、canonical 栈统计、去重生命周期、
终片泄漏候选及 `report peak-memory` 共用有界 core 语义;数据集仍不支持自定义 SQL/override。
详见[全局支持矩阵](docs/zh/querying.md#数据集全局内建支持p3)及
[数据集定点归因与覆盖](docs/zh/querying.md#数据集定点事件归因)。

显式 `pt-snap import snapshot.pkl --format msinsight --json` 生成
`snapshot.pkl.msinsight/`,对齐固定 msinsight 版本的**同一原始 pickle + 邻接缓存**入口。
内联栈比原生去重占更多空间;即使 `--force` 也不替换已有兼容目标,只复用完整校验且
身份相同的 pt-snap 缓存。GUI **待验收/未运行**,hash 相等不代表验收通过。详见
[兼容导出及限制](docs/zh/sharded-snapshotdb.md#显式-msinsight-兼容导出p2)。

[离线双向验收与有界性能](docs/zh/interop-acceptance.md) 提供固定版本两条链路、
确定性独立参考工具、真实三模式测量及明确**待验收/not-run 的 GUI 清单**。
诊断 skills 接受显式选择的完整已校验数据集,不接受任意目录。

## 命令

| 命令 | 说明 |
Expand Down Expand Up @@ -91,6 +117,7 @@ helper 会先路由采集,无需先安装 CLI。分析仍需要 CLI 和 Snapsh
| 拆分快照 | [拆分快照](docs/zh/splitting.md) |
| Agent skill | [Agent Skills](docs/zh/skills.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| 分片协议、原生导入与兼容边界 | [分片 SnapshotDB 协议](docs/zh/sharded-snapshotdb.md) |
| Python API | [SnapshotAnalyzer API](docs/zh/snapshot-analyzer-api.md) |
| 结果映射工具 | [ResultMapper API](docs/zh/result-mapper-api.md) |

Expand Down
Loading
Loading