blob: f9619284bb0d57448f5e4b2ba1a9c15a1abfa8d3 [file] [view] [edit]
# Diagnostics Persistence: Saving Inspect across reboot
Diagnostics Persistence automatically captures and stores Inspect data across
device reboots. This can be used to preserve anything that can be written to
Inspect.
## Overview {#overview}
* **Automatic collection in development**: On `eng` and `userdebug` builds,
all Inspect data across the system is automatically persisted across
reboots. No configuration required.
* **Production (`user`) builds require privacy configuration**: On production
devices, persisted Inspect data must be explicitly allowlisted in a
product's `previous_boot` pipeline (for example, in go/previous-boot-pipeline)
and undergo privacy review.
* **Available in Feedback & Crash Reports**: Persisted Inspect data is
automatically ingested by Feedback and included in snapshot archives
(as `inspect.previous_boot.json`) when generating feedback or crash reports.
## Field collection on user builds {#field-collection-on-user-builds}
On production (`user`) builds, diagnostic data exfiltration is restricted for
user privacy. To persist specific Inspect properties or trees on production
devices, you must add your selectors to the product's `previous_boot` pipeline
and complete a privacy review.
The privacy requirements for Persistence are functionally identical to
go/tq-feedback-privacy.
### 1. Identify Inspect selectors {#identify-inspect-selectors}
Determine the exact Inspect selectors for the properties or nodes you need.
You can inspect your component on a running device or emulator using
`ffx inspect`.
### 2. Add selectors to the previous_boot pipeline {#add-selectors-to-pipeline}
Create or update the selector configuration for your component in the product
repository's pipeline directory:
1. Create a component directory under the product's `previous_boot` pipeline:
```none
//vendor/*/privacy/pipelines/previous_boot/<component_name>/inspect/
```
2. Add a `.cfg` file (e.g. `<component_name>.cfg`) containing the exact
selectors to persist:
```none
core/my_component:root/my_node:error_count
core/my_component:root/my_node:last_failure_reason
```
3. Update the corresponding `BUILD.bazel` or pipeline list to include your
new configuration.
### 3. Submit for privacy review {#submit-for-privacy-review}
Refer to go/tq-feedback-privacy.
## Accessing persisted data {#accessing-persisted-data}
### Feedback reports and snapshots {#feedback-reports-and-snapshots}
When a feedback report or crash snapshot is taken after a reboot, Feedback
automatically retrieves the previous boot's Inspect data from Persistence.
The resulting snapshot contains:
* `inspect.previous_boot.json`: The complete or filtered Inspect JSON tree
from the prior boot.
## Technical architecture and behavior {#technical-architecture-and-behavior}
Under the hood, Diagnostics Persistence operates as a scheduled and
event-driven pipeline snapshotting service:
```none {:.devsite-disable-click-to-copy}
┌───────────────────────────┐
│ Archivist │
│ ArchiveAccessor │
│ .previous_boot pipeline │
└─────────────┬─────────────┘
│ Snapshot query
▼
┌───────────────────────────┐ writes active snapshot
│ Diagnostics Persistence ├───► /cache/active/active.json
│ │ /cache/active/metadata.json
│ • Periodic (every 300s) │
│ • Low battery trigger │ on reboot: rotate
│ • Wait for update check ├───► /cache/previous_boot/active.json
└─────────────┬─────────────┘ /cache/previous_boot/metadata.json
│ Serves via FIDL
▼
┌───────────────────────────┐
│ PreviousBootDataProvider │
│ (e.g. Feedback component) │
└───────────────────────────┘
```
### 1. Archivist previous_boot pipeline {#archivist-previous-boot-pipeline}
Persistence connects to `fuchsia.diagnostics.ArchiveAccessor.previous_boot`.
Archivist dynamically applies the allowlist selectors configured for the
pipeline, or bypasses filtering when `DISABLE_FILTERING.txt` is present (such
as in `eng` and `userdebug` builds).
### 2. Snapshot triggers {#snapshot-triggers}
Persistence records active system snapshots using two triggers:
* **Periodic Interval**: Runs every $N$ seconds (configured by
`fuchsia.diagnostics.persist.PersistencePeriodSeconds`, default 300 seconds).
* **Low-Battery Trigger**: Connects to
`fuchsia.power.battery.BatteryManager` to monitor battery status. If
battery drops to or below
`fuchsia.diagnostics.persist.LowBatteryThresholdPercent` (default 10%), an
immediate snapshot is captured to preserve state prior to impending
shutdown.
### 3. Active-to-previous boot rotation {#active-to-previous-boot-rotation}
* Active snapshots and metadata are saved to `/cache/active/active.json` and
`/cache/active/metadata.json`.
* On startup, Persistence atomically cleans `/cache/previous_boot` and moves
`/cache/active` to `/cache/previous_boot`.
* Persisted data is retained strictly for the single previous boot cycle.
### 4. Software update check gating {#software-update-check-gating}
To protect against persistent crash loops across updates, Persistence
registers with `fuchsia.update.Listener` and withholds serving previous boot
data until the first post-boot software update check completes. On `eng` and
`userdebug` builds, this check can be skipped (`skip_update_check: true`).
## Assembly configuration {#assembly-configuration}
Persistence parameters can be customized in product assembly configuration
under the `diagnostics.persistence` section:
* `persistence_period_seconds` (integer, default: `300`):
Duration in seconds between periodic snapshots on
`ArchiveAccessor.previous_boot`.
* `low_battery_threshold_percent` (integer, default: `10`):
Battery percentage threshold that triggers an immediate active snapshot.
* `skip_update_check` (boolean, default: `false` on user, `true` on
userdebug/eng):
If `true`, does not wait for the post-boot update check before publishing
previous boot data. Always `false` on user builds.
## FAQ {#faq}
### Does Persistence work with Lazy Nodes? {#lazy-nodes}
Yes. Because Persistence requests a snapshot from Archivist via
`ArchiveAccessor`, Archivist actively evaluates all Lazy Nodes that match the
pipeline's active selectors at the time of each snapshot.
### Where did .persist configuration files go? {#legacy-config-files}
Legacy `.persist` files and per-tag fetch scheduling have been replaced by the
Archivist `previous_boot` pipeline. Components no longer publish separate
`.persist` files or re-export persisted data in the live Inspect hierarchy
under `core/diagnostics/persistence:root/persist`. All previous boot Inspect
is unified into a single snapshot file served directly to Feedback.