Initial commit: Hermes Agent Skills collection

2026-07-12 19:02:59 +00:00
commit e9cc106625
789 changed files with 233126 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Home Assistant History/Recorder Troubleshooting
+
+## Symptom: History page shows no data or is blank
+
+### Quick Diagnosis Flow
+
+1. **Check if recorder is running**
+   ```
+   curl -s -H "Authorization: Bearer $HA_TOKEN" \
+     https://homeassistant.familie-schoen.com/api/services/recorder |
+     jq '.[].service'
+   ```
+   If recorder service is missing, the `recorder` integration may be disabled.
+
+2. **Check HA core logs for recorder errors**
+   ```
+   curl -s -H "Authorization: Bearer $HA_TOKEN" \
+     https://homeassistant.familie-schoen.com/api/error_log
+   ```
+   Look for: `sqlite3.DatabaseError`, `database is locked`, `disk I/O error`,
+   `Recorder thread encountered an error`, `purge` failures.
+
+3. **Check disk space** (via SSH or HA API)
+   - HA OS: `ha os info` or check Settings → System → Storage in UI
+   - Docker/container: `df -h` inside the container
+   - Recorder stops writing when partition is >95% full
+
+4. **Check database size**
+   - SQLite default: `/config/home-assistant_v2.db`
+   - If >2GB on SQLite, consider switching to PostgreSQL or MySQL
+   - Large DB causes slow queries → history appears empty (timeout)
+
+5. **Check recorder config in configuration.yaml**
+   ```yaml
+   recorder:
+     purge_keep_days: 10
+     db_url: sqlite:///config/home-assistant_v2.db
+     include:
+       domains:
+         - sensor
+         - switch
+     exclude:
+       domains:
+         - automation
+   ```
+   Overly restrictive `include`/`exclude` filters can hide entities from history.
+
+### Common Causes (ranked by frequency)
+
+| Cause | Fix |
+|-------|-----|
+| Recorder DB corrupt | Stop HA, delete `.db` + `.db-wal` + `.db-shm`, restart |
+| Disk full | Free space, run `recorder.purge` service |
+| Recorder stuck on purge | Call `recorder.disable` then `recorder.enable` |
+| SQLite lock contention | Switch to external DB (MySQL/PostgreSQL) |
+| `history:` integration disabled | Add `history:` to configuration.yaml |
+| Too many entities recorded | Add `exclude` filters, reduce retention |
+| Time zone mismatch | Check `time_zone:` in configuration.yaml |
+
+### Useful API Endpoints
+
+```
+# Get states for an entity (last 24h)
+GET /api/history/period/{timestamp}?filter_entity_id=sensor.xxx
+
+# Get all entity states now
+GET /api/states
+
+# Error logs
+GET /api/error_log
+
+# Call service
+POST /api/services/recorder/purge
+POST /api/services/recorder/disable
+POST /api/services/recorder/enable
+
+# HA config check
+GET /api/config/core/check_config
+```
+
+### SSH Access
+
+HA is VM 106 on proxmox1 (10.0.20.10). Access via Proxmox guest agent:
+```bash
+ssh -i ~/.ssh/id_ed25519_proxmox root@10.0.20.10 \
+  "qm guest exec 106 --timeout 30 -- bash -c 'docker logs homeassistant 2>&1 | tail -30'"
+```
+
+Config file: `/mnt/data/supervisor/homeassistant/configuration.yaml` (inside VM).
+
+### External Database (MariaDB Galera + MaxScale)
+
+Production HA uses MariaDB Galera cluster (3 nodes) behind MaxScale VIP, NOT SQLite.
+If recorder errors mention MySQL/MariaDB (`MySQLdb.OperationalError`), see:
+**`references/galera-cluster-recovery.md`** for full cluster recovery procedure.
+
+Quick checks:
+```bash
+# MaxScale server states
+ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.81 "maxctrl list servers"
+
+# Direct DB connection test via MaxScale
+ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.81 \
+  "mariadb -h 127.0.0.1 -P 3306 -u ha_recorder -p'<password>' --skip-ssl -e \"SELECT 1\""
+
+# Galera node status
+ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.71 \
+  "sudo mariadb -e \"SHOW GLOBAL STATUS LIKE 'wsrep_cluster_size'; SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';\""
+```
+
+Common Galera failure symptoms:
+- All nodes `failed` since same timestamp → simultaneous crash (network or power)
+- `Access denied` from HA → MaxScale can't route to any backend
+- `Lost connection during query` → MaxScale routed to Donor/Desynced node without `available_when_donor=true`
+
+### Recovery Procedure (corrupt SQLite DB)
+
+```bash
+# Via SSH to HA
+ha core stop
+mv /config/home-assistant_v2.db /config/home-assistant_v2.db.bak
+rm -f /config/home-assistant_v2.db-wal /config/home-assistant_v2.db-shm
+ha core start
+```
+
+History will rebuild from scratch. Old history is lost (backup exists as .bak).
+
+### Prevention
+
+- Set `recorder.commit_interval: 1` (flush more frequently, smaller WAL)
+- Add `exclude` filters for noisy domains (automation, script, timer)
+- Consider external DB for installations with 500+ entities
+- Monitor disk space with a sensor/alert