pw_snapshot

Warning

This module is unstable and under active development. The snapshot proto format may see breaking changes as it stabilizes.

pw_snapshot provides a storage format and associated tooling for capturing a device’s system state at a given point in time for analysis at a later time. This is particularly useful for capturing information at crash time to provide context to the cause of the crash. Outside of crash reporting, snapshots can be used to debug anomalies that don’t result in crashes by treating snapshotting as a heavyweight alternative to tracing, logging-based dump commands, or other on-demand system state capturing.

• Setting up a Snapshot Pipeline
• Module Usage
• Snapshot Proto Format
• Design Discussion
• Source code
• Issues

Life of a Snapshot

A “snapshot” is just a proto message with many optional fields that describe a device’s state at the time the snapshot was captured. The serialized proto can then be stored and transfered like a file so it can be analyzed at a later time.

1. Snapshot capture triggered - The device encounters a condition that indicates a snapshot should be captured. This could be through a crash handler, or through other developer-specified entry points.

2. Device “pauses” - In order to capture system state, the device must temporarily disable the thread scheduler and regular servicing of interrupts to prevent the system state from churning while it is captured.

3. Snapshot captured - The device collects information throughout the system through a project-provided snapshot collection logic flow. This data is stored as a serialized Snapshot proto message for later retrieval.

4. Device resumes - After a snapshot is stored, the device resumes normal execution. In a crash handler, the device will usually reboot instead of returning to normal execution.

5. Snapshot retrieved from device - During normal device operation, stored snapshots are retrieved from a device by a client that is interested in analyzing the snapshot, or forwarding it elsewhere to be analyzed.

6. Snapshot analyzed - Finally, analysis tooling is run on the captured snapshot proto to produce human readable dumps (akin to a crash report). Alternatively, the data can be ingested by a server to act as a cloud crash reporting endpoint. The structured form of a snapshot enables common cloud-based crash reporting needs like version filtering, crash signatures, de-duplication, and binary-matched symbolization.

While Pigweed provides libraries for each part of a snapshot’s lifecycle, the glue that puts all these pieces together is project specific. Please see the section on Setting up a Snapshot Pipeline for more information on how to bring up snapshot support for your project.