Monitoring

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:

curl http://aris.local/health

{
  "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):

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

# 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:

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

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

curl http://aris.local/api/fcus/status/all \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "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

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

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

curl http://aris.local/api/metrics/health \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Metrics

# 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

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

Get Started

Guides

Health Checks

Detailed Health Status

Status Meanings

Readiness Probe

Event Log

Querying Events

Event Types

Event Severities

Exporting Events

Equipment Monitoring

Heat Pump Status

FCU Status

HCU Status

DHW Tank

Time-Series Metrics

Check Metrics Health

Query Metrics

Available Metrics

Monitoring Script Example

Alerting Integration

​Health Checks

​Detailed Health Status

​Status Meanings

​Readiness Probe

​Event Log

​Querying Events

​Event Types

​Event Severities

​Exporting Events

​Equipment Monitoring

​Heat Pump Status

​FCU Status

​HCU Status

​DHW Tank

​Time-Series Metrics

​Check Metrics Health

​Query Metrics

​Available Metrics

​Monitoring Script Example

​Alerting Integration

Health Checks

Detailed Health Status

Status Meanings

Readiness Probe

Event Log

Querying Events

Event Types

Event Severities

Exporting Events

Equipment Monitoring

Heat Pump Status

FCU Status

HCU Status

DHW Tank

Time-Series Metrics

Check Metrics Health

Query Metrics

Available Metrics

Monitoring Script Example

Alerting Integration