# Observability

## Goals

- Explain every emitted position estimate.
- Detect false-position risk before it reaches the flight controller.
- Preserve enough evidence to replay incidents without storing raw frames.
- Surface operator-relevant status to QGroundControl without saturating telemetry.

## Runtime Signals

| Signal | Frequency | Destination | Notes |
|--------|-----------|-------------|-------|
| Position estimate | Per processed frame locally | FDR, MAVLink `GPS_INPUT` | GCS receives downsampled status |
| Source label | Per estimate | FDR, status summary | `satellite_anchored`, `vo_extrapolated`, `dead_reckoned` |
| Covariance semi-major | Per estimate | FDR, `GPS_INPUT.horiz_accuracy` mapping | Must not under-report |
| Anchor decision | Per candidate | FDR | Include MRE, inliers, tile provenance, rejection reason |
| Cache validation | On cache load / tile read | FDR, health log | Signature, freshness, resolution, hash |
| Blackout/spoofing status | On transition and 1-2 Hz while active | QGC, FDR | Operator status |
| Total occlusion status | Per transition and sampled while active | FDR, QGC if persistent | Indicates VIO is bypassed and IMU-only propagation is active |
| Resource health | 1 Hz or configurable | FDR, QGC warning on threshold | CPU/GPU/temp/memory/throttle |
| Tile write decision | Per generated tile | FDR, sidecar | Include parent covariance and trust level |

## Logs

| Log Type | Format | Retention |
|----------|--------|-----------|
| FDR events/index | PostgreSQL tables + CBOR payload segments | <=64 GB per flight, rollover |
| MAVLink raw stream | tlog or equivalent | FDR cap |
| Health metrics | FDR event stream | FDR cap |
| Test reports | CSV/Markdown | CI artifact retention |

## Alerts And Status Text

| Condition | Status |
|-----------|--------|
| Visual blackout starts | `VISUAL_BLACKOUT_IMU_ONLY` |
| Total occlusion before VIO | `VISUAL_OCCLUSION_IMU_ONLY` |
| Blackout failsafe threshold exceeded | `VISUAL_BLACKOUT_FAILSAFE` |
| Spoofing promotion/demotion | QGC status text with mode and timestamp |
| Stale cache tile rejected | Warning in FDR; QGC only if mission-impacting |
| Thermal throttle risk | QGC warning before throttle if possible |
| No estimate for threshold | Relocalization request / failsafe status |

## Metrics For Release Evidence

- Error CDF against ground truth.
- Anchor-age binned error.
- Covariance calibration plot.
- VIO completion rate.
- Relocalization trigger-to-anchor latency.
- Cache freshness rejection counts.
- FDR size over 8 hours.
- Thermal/throttle timeline.

## Open Tasks For Decomposition

- Define FDR schema and event names.
- Define QGC status vocabulary and rate limiting.
- Define telemetry-to-report export tooling.
- Define covariance calibration dashboard/report.