中文 | English
Go from an existing input to a readable peak-memory report. The default path is one SnapshotDB; you do not need to choose a sharded format to start.
Use Python 3.10 or newer in the environment where you want the CLI:
python -m pip install pt-snap-cli
pt-snap --helpOffline import and analysis do not require PyTorch, TorchNPU, CUDA, or accelerator hardware. Collection is different: it runs beside the workload in a compatible PyTorch/CUDA or TorchNPU/Ascend environment. Contributors should use the separate Development and Checks entry.
| What you have | Shortest next step |
|---|---|
An existing SnapshotDB .db |
Skip import; use its path in Step 2. |
A complete native or compatibility-v1 dataset directory / manifest.json |
Skip import; use that explicit target in Step 2. Keep every member, not just one ready shard. |
A trusted .pkl / .pickle snapshot |
Use Step 1, then analyze the generated DB. |
| No snapshot yet | Follow the collection entry below, then make a separate trusted-import decision. |
- CUDA/PyTorch: collect allocator history in your workload's GPU environment using the official PyTorch snapshot guide. Verify the APIs for your installed PyTorch version, choose a bounded history window, and dump the snapshot after the relevant workload section. Installing this offline CLI does not instrument or start your training job.
- Ascend NPU: use pt-snap-ascend-npu-collect for TorchNPU API/environment checks and the framework-specific capture route. Choose the capture ranks, step window and output location. The skill can guide collection without the CLI if the host has loaded it; see Agent Skills.
- A CSV, SVG or screenshot is not a SnapshotDB. Obtain the database or the
original trusted pickle; do not rename a visualization to
.db.
Collection changes the workload's recording behavior and writes a pickle; it is not read-only analysis. Review that plan separately. Copying a pickle to an offline machine does not make it safe to deserialize.
Security warning: Import only pickle snapshots you trust. Deserialization can execute arbitrary code. The loader rejects non-
builtinsglobal objects, butpt-snap importis not a sandbox. Agent setup or collection approval is not approval to import a pickle.
pt-snap import snapshot.pklBy default this creates snapshot.pkl.db beside the source pickle and
updates .pt-snap/focus.json in the current working directory (project focus).
--output-dir captures changes the output parent, not the filename. To create
or reuse the DB without changing focus, use:
pt-snap import snapshot.pkl --no-focus--no-focus is not no-replace: a standalone cache miss or --force can
replace an existing same-named .db. Confirm that output is disposable, or use
a different --output-dir before importing.
The remaining examples pass an explicit path and device and work with either
choice. Replace snapshot.pkl.db with your actual DB or complete dataset path.
Import is a write operation; overview, built-in queries, and reports do not
change source data or persist focus. Dataset queries may use private temporary
scratch storage within their work limits.
pt-snap overview snapshot.pkl.db --jsonCheck db_path and choose a device_id from devices. Below we use 0 as an
example; substitute a device that was actually returned. For a dataset also
check dataset.status, format and fingerprint. Stop on an invalid target or
import_metadata.status: "invalid"; legacy "unavailable" with reason
"metadata_missing" means unknown import provenance, not known corruption.
Other unknown statuses/reasons need investigation before diagnosis.
pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --jsonAn illustrative rows[0] (not a promised result for your snapshot):
{
"peak_allocated": 8388608,
"peak_allocated_event_id": 10,
"peak_active": 10485760,
"peak_active_event_id": 12,
"peak_reserved": 16777216,
"peak_reserved_event_id": 10
}All three sizes are bytes: here 8, 10 and 16 MiB (1 MiB = 1048576 bytes).
| Counter | Meaning in the replayed allocator history |
|---|---|
allocated |
Bytes in allocated blocks, excluding blocks already marked pending free. This is block size, not requested tensor payload size. |
active |
Allocated plus pending-free block bytes that are not yet reusable. |
reserved |
Total segment bytes held by the allocator, including inactive capacity; not all process/device memory. |
Each metric has its own earliest peak event; event IDs are ordering markers, not timestamps. Do not subtract independent peaks as if they were simultaneous. Empty real-event ranges return null peaks: do not invent an event. A large reserved/active gap alone does not prove fragmentation, a leak or OOM causality.
pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20Expect Peak memory report, the selected device/metric/event, separate peak
counters, same-event allocator gaps, and Active memory by callstack. The
report explains active blocks at the selected peak, not every reserved byte.
Check the attribution completeness label and active-byte coverage before making
claims: group percentages use included_bytes after filtering/ranking, not all
active memory. A capped report can be partial; a budget error is not a partial
successful analysis. Add --json for automation. See the
report contract for limits and denominators.
pt-snap focus snapshot.pkl.db --device 0
pt-snap report peak-memoryUnlike the explicit-path analysis above, focus <path> writes project focus.
Skip it if you do not want shared project state. The import default may already
have selected the DB; this command also selects your chosen device. See
focus precedence and session isolation.
These are optional, not prerequisites for the first report.
--events-per-slice opts into a native dataset; it does not make pickle loading
streaming or bound peak RSS. For output paths, complete-member validation,
force/recovery behavior and supported built-ins, read the
native import contract and
global support matrix.
Native output is not msinsight-compatible.
--format msinsight is explicit opt-in. Existing compatible targets are never
replaced, even with --force; compatibility, cache validation, GUI entrance and
fixed-version evidence have their own protocol contract.
Read recorded interoperability acceptance before claiming
GUI reuse. A matching hash alone is not GUI acceptance.
Current exports use parser v3. The pinned 101f65b revision and targetRevision
are historical v2 schema/identity references, not verified current GUI consumers.
No fixed v3 consumer revision/build has been verified yet. Do not open current
caches with the old GUI: it may reparse and rewrite them. Future v3 acceptance
must use a separately trusted pickle copy and a new adjacent cache, preserving
original artifacts.
Compatible reuse checks source identity, sourceFile, options, contract versions,
the complete member inventory and required read-only structure. Historical member
hash fields are inventories; their digest values are not compared. Import does
not hash database contents or scan arbitrary row values, so structurally valid
content edits can be reused. Queries and explicit validators perform independent
admission checks. Successful reuse is not proof of database content integrity or
GUI cache reuse. --output-dir selects another parent; moving a dataset does not
establish a GUI entrance.
pt-snap split creates independently replayable files, not a queried dataset.
It also requires trusted pickle input, exactly one split strategy, and an absent
output directory. It does not change focus. See Splitting Snapshots.
Standalone import stores source SHA-256 and compatibility metadata. Identical
content/options can reuse the DB; cache misses (including missing/invalid
metadata) and --force rebuild and can replace the same-named standalone DB.
Unlike native/compatible directory policies, this is not an unknown-target
protection gate. Confirm ownership or choose another --output-dir first.
Do not force a rebuild merely because analysis failed; inspect the error. Import loads the entire
pickle before replay; --device reduces subsequent work, not that initial peak.
Use sufficient memory headroom. Snapshot runtime modules are not a public API.
- Agent Skills — install, restart, verify and ask for a diagnosis
- Querying — templates, bounded results, stack detail and reports
- Focus Management — optional persisted/session targets
- Database Schema — counters, metadata and sentinel meanings
- SnapshotAnalyzer API — analysis with owned Python resources