gps-denied-onboard/_docs/02_document/deployment/observability.md

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.