Skip to content

Storage Module API Explanation

The Storage module monitors physical disk health, disk temperature, and filesystem usage for configured homelab storage devices.

API Execution Logic

The module reads storage devices from storage.devices in public/config.yaml and requires storage.prometheusUrl for SMART telemetry. It also uses configured Proxmox instances to retrieve authoritative filesystem usage for each Proxmox storage target.

Request Execution

The backend performs parallel lookups against Prometheus and Proxmox:

  1. SMART Health: smartctl_device_smart_status
  2. SMART Exit Status: smartctl_device_smartctl_exit_status
  3. Disk Temperature: smartctl_device_temperature
  4. Physical Capacity: smartctl_device_capacity_bytes
  5. Proxmox Usage: /api2/json/nodes/[NODE]/storage/[STORAGE]/status

Data Parsing

Each configured device is resolved into a normalized storage record containing:

  • Device id and display name.
  • Node and Proxmox storage target.
  • SMART health state.
  • Highest detected temperature.
  • Used bytes and total bytes.
  • Optional physical capacity.
  • Human-readable usage display.

Metric Calculation

  • Primary Metric: Number of configured storage devices.
  • Secondary Metric: Number of healthy devices.
  • Raw Data: Per-device health, temperature, used bytes, total bytes, and display string.

Caching Strategy

Storage telemetry is cached in memory for 60 seconds with a stale window of 300 seconds.