Detect snapshot filing

Detect runs on-device, periodically gathering and evaluating Diagnostic data to decide whether to generate a crash report / snapshot.

How it works

Every few minutes Detect reads the Inspect state, evaluates trigger conditions, and files crash reports to the FuchsiaDetect product. The frequency of diagnostic scans is set by command line arguments in //src/diagnostics/detect/meta/triage-detect.cml.

Diagnostic state other than Inspect is not currently read. SyslogHas(), KlogHas(), and BootlogHas() will always return false.

Enabling crash reports

By default, Detect runs in all products and builds, but only creates or files crash reports in some builds. Otherwise it logs a warning: Detect would have filed {} where {} is replaced by the snapshot signature.

Detect only generates crash reports if "//src/diagnostics/detect:enable-report-filing" is included in --with-base.

Crash reports are only sent to the server in some build configurations, or if explicitly enabled as explained in Crash reporting.

Snapshot triggers

Snapshot triggers live in .triage files in the //src/diagnostics/config/triage/detect directory. Files added to that directory must also be added to detect_unconditional_files in //src/diagnostics/config/triage/BUILD.gn.

The .triage files are standard Triage format. Detect adds a new act type:

    snapshot_action: {
        type: "Snapshot",
        trigger: "something > something_else",
        repeat: "Hours(6)",
        signature: "a-string-with-restrictions",
    }
  • trigger is evaluated by Triage-lib just like in Warning-type actions.
  • repeat gives the minimum delay before re-filing if a condition persists or repeats. It can use Days(), Hours(), and Minutes(). If the repeat value is less than MINIMUM_SIGNATURE_INTERVAL_NANOS the latter will be used and a warning will be logged.
  • signature will be reported in the crash report.
    • fuchsia-detect- will be prepended to the signature.
    • Signatures must contain only lowercase letters and hyphens (no spaces or underscores). Any characters outside this set will be lowercased or converted to hyphens and an error will be logged.
    • Several Snapshot actions may have the same signature. Crash reports filed by each action will be identical. repeat throttling will be applied per-signature not per-action, using the value from the action that triggered.

Conditional file inclusion

Detect configuration files can be included in only a subset of builds or products. This can be done in //src/diagnostics/config/triage/BUILD.gn by:

  1. Adding the file to detect_conditional_files rather than detect_unconditional_files
  2. Creating a new config_data() entry; by convention its target name should be the same as the file name
  3. Adding that target to the appropriate group so the file is included along with whatever component(s) it should be analyzing

See here for examples.

The fine print

Read this section if you're using Detect for debugging on your desktop.

repeat is actually a Triage eval expression like trigger and could be calculated dynamically from Inspect data. The expression must evaluate to an integer number of nanoseconds.

The frequency with which Detect checks diagnostic data is configured by the --check-every command line parameter which is set in //src/diagnostics/detect/meta/triage-detect.cml. (This expression must contain only constants.)

Detect has built-in limits on its time delays; it will exit with error if --check-every is less than MINIMUM_CHECK_TIME_NANOS and it will delay re-filing snapshots at least MINIMUM_SIGNATURE_INTERVAL_NANOS. These limits can be overridden by adding a --test-only command line argument.