1.. _module-pw_snapshot: 2 3=========== 4pw_snapshot 5=========== 6.. pigweed-module:: 7 :name: pw_snapshot 8 9.. warning:: 10 11 This module is unstable and under active development. The snapshot proto 12 format may see breaking changes as it stabilizes. 13 14``pw_snapshot`` provides a storage format and associated tooling for capturing a 15device's system state at a given point in time for analysis at a later time. 16This is particularly useful for capturing information at crash time to provide 17context to the cause of the crash. Outside of crash reporting, snapshots can be 18used to debug anomalies that don't result in crashes by treating snapshotting as 19a heavyweight alternative to tracing, logging-based dump commands, or other 20on-demand system state capturing. 21 22 23.. toctree:: 24 :maxdepth: 1 25 26 setup 27 module_usage 28 proto_format 29 design_discussion 30 31------------------ 32Life of a Snapshot 33------------------ 34A "snapshot" is just a `proto message 35<https://cs.pigweed.dev/pigweed/+/HEAD:pw_snapshot/pw_snapshot_protos/snapshot.proto>`_ 36with many optional fields that describe a device's state at the time the 37snapshot was captured. The serialized proto can then be stored and transfered 38like a file so it can be analyzed at a later time. 39 40#. **Snapshot capture triggered** - The device encounters a condition that 41 indicates a snapshot should be captured. This could be through a crash 42 handler, or through other developer-specified entry points. 43#. **Device "pauses"** - In order to capture system state, the device must 44 temporarily disable the thread scheduler and regular servicing of interrupts 45 to prevent the system state from churning while it is captured. 46#. **Snapshot captured** - The device collects information throughout the 47 system through a project-provided snapshot collection logic flow. This data 48 is stored as a serialized Snapshot proto message for later retrieval. 49#. **Device resumes** - After a snapshot is stored, the device resumes normal 50 execution. In a crash handler, the device will usually reboot instead of 51 returning to normal execution. 52#. **Snapshot retrieved from device** - During normal device operation, stored 53 snapshots are retrieved from a device by a client that is interested in 54 analyzing the snapshot, or forwarding it elsewhere to be analyzed. 55#. **Snapshot analyzed** - Finally, analysis tooling is run on the captured 56 snapshot proto to produce human readable dumps (akin to a crash report). 57 Alternatively, the data can be ingested by a server to act as a cloud crash 58 reporting endpoint. The structured form of a snapshot enables common 59 cloud-based crash reporting needs like version filtering, crash signatures, 60 de-duplication, and binary-matched symbolization. 61 62While Pigweed provides libraries for each part of a snapshot's lifecycle, the 63glue that puts all these pieces together is project specific. Please see the 64section on :ref:`Setting up a Snapshot Pipeline<module-pw_snapshot-setup>` for 65more information on how to bring up snapshot support for your project. 66