> ## Documentation Index > Fetch the complete documentation index at: https://docs.ariscomfort.com/llms.txt > Use this file to discover all available pages before exploring further. # Monitoring > Monitor system health, events, and performance The Aris Brain provides comprehensive monitoring capabilities for tracking system health, equipment status, and historical performance. ## Health Checks ### Detailed Health Status Get comprehensive system health: ```bash theme={null} curl http://aris.local/health ``` ```json theme={null} { "status": "ok", "version": "1.0.0", "uptime_seconds": 86400, "timestamp": "2024-01-15T10:30:00Z", "checks": { "mqtt": { "status": "ok", "connected": true }, "cloud": { "status": "ok", "state": "connected", "connected": true }, "memory": { "heap_used_mb": 45, "heap_total_mb": 64, "rss_mb": 120 }, "state_file": { "status": "ok", "last_modified": "2024-01-15T10:29:00Z" } } } ``` ### Status Meanings | Status | Meaning | | ----------- | --------------------------------------------- | | `ok` | Everything is working normally | | `degraded` | Cloud is disconnected but local control works | | `unhealthy` | MQTT is disconnected, system may not function | ### Readiness Probe For container orchestration (Kubernetes, Docker): ```bash theme={null} curl http://aris.local/ready ``` Returns 200 if ready, 503 if not. ## Event Log The Brain maintains an audit log of all significant events. ### Querying Events ```bash theme={null} # Recent events (default: last 100) curl "http://aris.local/api/events" \ -H "Authorization: Bearer YOUR_TOKEN" # Filter by type curl "http://aris.local/api/events?type=fault_raised" \ -H "Authorization: Bearer YOUR_TOKEN" # Filter by severity curl "http://aris.local/api/events?severity=critical" \ -H "Authorization: Bearer YOUR_TOKEN" # Filter by time range curl "http://aris.local/api/events?from=2024-01-14T00:00:00Z&to=2024-01-15T00:00:00Z" \ -H "Authorization: Bearer YOUR_TOKEN" # Pagination curl "http://aris.local/api/events?limit=50&offset=100" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ### Event Types | Type | Description | | ----------------- | --------------------------------- | | `fault_raised` | A fault was detected | | `fault_cleared` | A fault was resolved | | `mode_change` | System or zone mode changed | | `setpoint_change` | Temperature setpoint was adjusted | | `device_online` | Device came online | | `device_offline` | Device went offline | | `command_sent` | Command was sent to a device | | `system_startup` | Brain started | | `system_shutdown` | Brain stopped | ### Event Severities | Severity | Description | | ---------- | ----------------------------------------- | | `info` | Normal operation | | `warning` | Potential issue, system still functioning | | `critical` | Serious issue requiring attention | ### Exporting Events Download events as CSV: ```bash theme={null} curl "http://aris.local/api/events/export?from=2024-01-01T00:00:00Z" \ -H "Authorization: Bearer YOUR_TOKEN" \ -o events.csv ``` ## Equipment Monitoring ### Heat Pump Status ```bash theme={null} curl http://aris.local/api/heatpumps \ -H "Authorization: Bearer YOUR_TOKEN" ``` Key metrics to watch: * `compressorSpeedPercent` - Current compressor load * `copInstant` - Real-time efficiency (higher is better) * `defrostActive` - Defrost cycle in progress * `activeFaults` - Any active fault codes ### FCU Status ```bash theme={null} curl http://aris.local/api/fcus/status/all \ -H "Authorization: Bearer YOUR_TOKEN" ``` ```json theme={null} { "status": [ { "fcuId": "fcu_01", "friendlyName": "Living Room", "online": true, "lastSeen": "2024-01-15T10:30:00Z" }, { "fcuId": "fcu_02", "friendlyName": "Bedroom", "online": false, "lastSeen": "2024-01-15T09:15:00Z" } ] } ``` ### HCU Status ```bash theme={null} curl http://aris.local/api/hcu \ -H "Authorization: Bearer YOUR_TOKEN" ``` Key metrics: * `mode` - Current operating mode (heat/cool/dhw\_charge/idle) * `supplyTempC` / `returnTempC` - Water temperatures * `thermalPowerKw` - Heat output * `copInstant` - System efficiency ### DHW Tank ```bash theme={null} curl http://aris.local/api/dhw \ -H "Authorization: Bearer YOUR_TOKEN" ``` Key metrics: * `stateOfChargePercent` - How much hot water is available * `effectiveCapacityLiters` - Usable hot water volume * `heatingActive` - Whether tank is being heated * `isSanitizing` - Legionella sanitization in progress ## Time-Series Metrics The Brain stores detailed metrics in VictoriaMetrics for historical analysis. ### Check Metrics Health ```bash theme={null} curl http://aris.local/api/metrics/health \ -H "Authorization: Bearer YOUR_TOKEN" ``` ### Query Metrics ```bash theme={null} # Current value curl "http://aris.local/api/metrics/query?query=aris_zone_temp_c" \ -H "Authorization: Bearer YOUR_TOKEN" # Historical range curl "http://aris.local/api/metrics/query_range?query=aris_zone_temp_c&start=2024-01-14T00:00:00Z&end=2024-01-15T00:00:00Z&step=5m" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ### Available Metrics | Metric | Labels | Description | | ---------------------------- | -------- | ---------------------------------------- | | `aris_zone_temp_c` | zone\_id | Zone temperature | | `aris_zone_humidity_percent` | zone\_id | Zone humidity | | `aris_zone_heat_setpoint_c` | zone\_id | Heating setpoint | | `aris_zone_cool_setpoint_c` | zone\_id | Cooling setpoint | | `aris_fcu_fan_percent` | fcu\_id | FCU fan speed | | `aris_hcu_supply_temp_c` | hcu\_id | HCU supply temperature | | `aris_hcu_cop` | hcu\_id | System efficiency (COP—higher is better) | | `aris_hp_power_kw` | hp\_id | Heat pump power | | `aris_dhw_soc_percent` | dhw\_id | DHW state of charge | ## Monitoring Script Example ```python theme={null} import requests import time BRAIN_URL = "http://aris.local" TOKEN = "your-api-token" def check_health(): """Check system health and alert on issues""" response = requests.get(f"{BRAIN_URL}/health") health = response.json() if health["status"] == "unhealthy": print(f"CRITICAL: System unhealthy - MQTT disconnected") return False if health["status"] == "degraded": print(f"WARNING: System degraded - Cloud disconnected") return True def check_faults(): """Check for active faults""" headers = {"Authorization": f"Bearer {TOKEN}"} # Check heat pump faults response = requests.get(f"{BRAIN_URL}/api/heatpumps", headers=headers) if response.status_code == 200: for hp in response.json().get("heatPumps", []): if hp.get("activeFaults"): print(f"FAULT: Heat pump {hp['hpId']}: {hp['activeFaults']}") # Check FCU faults response = requests.get(f"{BRAIN_URL}/api/fcus", headers=headers) if response.status_code == 200: for fcu in response.json().get("fcus", []): if fcu.get("activeFaults"): print(f"FAULT: FCU {fcu['fcuId']}: {fcu['activeFaults']}") def check_offline_devices(): """Check for offline FCUs""" headers = {"Authorization": f"Bearer {TOKEN}"} response = requests.get(f"{BRAIN_URL}/api/fcus/status/all", headers=headers) if response.status_code == 200: for fcu in response.json().get("status", []): if not fcu.get("online"): print(f"WARNING: FCU offline: {fcu['friendlyName']}") if __name__ == "__main__": while True: print(f"\n--- Health Check {time.strftime('%Y-%m-%d %H:%M:%S')} ---") check_health() check_faults() check_offline_devices() time.sleep(60) # Check every minute ``` ## Alerting Integration For production alerting, integrate with: * **Prometheus/Alertmanager** - Use the `/prometheus/*` endpoints * **Custom webhooks** - Poll events API and send to Slack/Discord/PagerDuty