vigilar/docs/architecture/subsystems/health.md

health

Purpose

Self-monitoring and housekeeping. Periodically checks disk usage and MQTT reachability, publishes an aggregated system-health snapshot, auto-prunes old recordings when the disk gets full, builds a daily "what happened today" digest, and drives the scheduled firing of highlight-reel and timelapse jobs.

Key files

• vigilar/health/monitor.py — HealthMonitor subsystem loop: disk check every 5 min, MQTT port check every 30 s, status publish every 10 s, daily reel trigger, per-minute timelapse schedule check
• vigilar/health/pruner.py — auto_prune / find_prunable_recordings; deletes oldest unstarred recordings (and their thumbnails) until usage is back under target
• vigilar/health/digest.py — build_digest: counts person/vehicle events, pet and wildlife sightings, and recording totals over a time window for notification digests
• vigilar/health/__init__.py

MQTT topics

Subscribes: none Publishes:

• vigilar/system/health — rolled-up health status with per-check breakdown

Database tables

• recordings — read in pruner (starred = 0, oldest first) and deleted row-by-row once the file is unlinked
• events, pet_sightings, wildlife_sightings, recordings — read in digest.py
• timelapse_schedules — read indirectly via vigilar.highlights.timelapse.check_schedules

Depends on

• storage — all DB access
• highlights — calls generate_daily_reel and check_schedules on schedule
• Filesystem — shutil.disk_usage on system.data_dir

Consumed by

• web — surfaces vigilar/system/health and the digest output in the system blueprint
• events — ingests vigilar/system/health off the bus (subscribes to everything)

Notes

The pruner is keyed on percentages, not gigabytes: it checks config.health.disk_warn_pct / disk_critical_pct for alerting and prunes toward config.health.auto_prune_target_pct. It never deletes a recording whose starred flag is set, and it unlinks the thumbnail alongside the video. The monitor owns the scheduling clock for both generate_daily_reel (fires when wall-clock matches highlights.generate_time) and timelapse generation (polls check_schedules every 60 s), so neither highlights/ nor its cron is wired directly into the supervisor.