44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
### Stability Agent
|
|
|
|
A lightweight filesystem-first watchdog and observer agent for CHELSTY.
|
|
|
|
#### Features
|
|
|
|
* **Continuous Monitoring**: Runs as a background service.
|
|
* **Docker Inspection**: Checks container status via read-only Docker socket.
|
|
* **Disk Usage**: Monitors local disk utilization.
|
|
* **Tailscale Check**: Verifies Tailscale availability.
|
|
* **MQTT Reachability**: Checks connectivity to the local MQTT broker.
|
|
* **Zigbee2MQTT Monitoring**: Specifically monitors the Zigbee2MQTT container.
|
|
* **Event Logging**: Writes append-only JSON events to `/opt/homelab/events/YYYY-MM-DD/chelsty/`.
|
|
* **State Reporting**: Writes heartbeat and status summary to `/opt/homelab/state/`.
|
|
|
|
#### Configuration
|
|
|
|
Environment variables:
|
|
|
|
* `STABILITY_CHECK_INTERVAL`: Interval between checks in seconds (default: 60).
|
|
* `DISK_THRESHOLD_PCT`: Disk usage percentage to trigger warning (default: 90).
|
|
* `MQTT_HOST`: Hostname or IP of the MQTT broker to check.
|
|
* `MQTT_PORT`: Port of the MQTT broker (default: 1883).
|
|
|
|
#### Safety
|
|
|
|
* No automatic restarts are performed.
|
|
* Read-only access to Docker socket.
|
|
* No configuration mutation.
|
|
* No secrets stored in the repository.
|
|
|
|
#### Event Schema
|
|
|
|
Events are written as JSON lines with the following fields:
|
|
|
|
* `id`: Unique event UUID.
|
|
* `timestamp`: ISO 8601 timestamp (UTC).
|
|
* `node`: `chelsty`.
|
|
* `source`: `stability-agent`.
|
|
* `type`: Type of event (e.g., `disk_usage_high`, `containers_not_running`).
|
|
* `severity`: `info`, `warning`, or `error`.
|
|
* `message`: Human-readable description.
|
|
* `details`: Object containing specific check results.
|