# 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](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/developer/forensics/README.md).

## 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](https://fuchsia.dev/docs/development/diagnostics/triage/config) 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](https://fuchsia-review.googlesource.com/c/fuchsia/+/542996).

## 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.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/diagnostics/analytics/detect.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/diagnostics/analytics/detect.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/diagnostics/analytics/detect.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/diagnostics/analytics/detect.md "Edit the source code of this page")