Skip to main content

Supervision hôte integration for Gladys Assistant

Supervision hôte integration for Gladys Assistant

Reports the CPU, memory, disk usage and CPU temperature of the machine running Gladys.

View on GitHubAll external integrations

This integration creates one device in Gladys, representing the machine Gladys runs on, with five sensors:

SensorUnitSource
CPU usage%/proc/stat
Memory usage%/proc/meminfo (MemAvailable)
Disk usage%statfs() on the monitored path
Free disk spaceGiBstatfs() on the monitored path
CPU temperature°C/sys/class/thermal or hwmon

Everything is read locally, on the machine: no agent to install, no cloud service, no data leaving your home.

Installation​

Requires Gladys 4.86 or later. On an older version the integration simply does not appear in the catalog: update Gladys first.

  1. Install the integration from the Gladys catalog (category Services).
  2. Open the Configuration tab and save (the defaults are fine for the vast majority of setups).
  3. Go to the Discovery tab: the "Machine hôte" device shows up, click Add.

The first values are published within seconds, then every 5 minutes.

Refresh rate and database size​

This is the point that shapes the whole integration. Gladys writes one history row for every published value: there is no server-side deduplication. A system monitor publishing 5 metrics every 30 seconds writes roughly 5 million rows a year, the vast majority of them repeating the previous value. On a Raspberry Pi with an SD card, that costs both space and write endurance.

Three guardrails, all tunable in the Configuration screen:

  • Refresh interval (300 s by default, 60 s minimum) — how often the metrics are read. The integration runs its own timer: it does not use the Gladys scheduler, which cannot go slower than one read per minute.
  • Minimum variation (2 percentage points / 1 °C by default) — a value is only published when it moved by at least this much since the last published value. A slow drift therefore always crosses the threshold eventually, while background noise stops filling the database. Set it to 0 to publish everything.
  • Maximum interval without a point (60 min by default) — even when nothing moves, each sensor is published at least once per hour, so the charts keep a continuous line.

With the default settings, a quiet machine typically writes a few dozen rows per day instead of tens of thousands.

The Keep history switch goes one step further: turned off, the sensors still show their live value but write no history row at all. Note that this setting is applied when the device is created; if the device already exists, change it directly on the device page in Gladys (each feature has its own "keep history" checkbox there).

Disk space: which disk is measured?​

A container does not see the host filesystem, it sees its own. The default path /data is the volume Gladys mounts from the host: it is the filesystem holding your Gladys data, so it is the free space that actually matters in practice.

To monitor another mount point, put its path in Disk path to monitor — as long as it is visible from inside the container.

The percentage is computed the way df does: root-reserved blocks are excluded, so a freshly formatted ext4 filesystem reads 0%, not 5%.

CPU temperature​

The sensor is auto-detected among those the kernel exposes under /sys/class/thermal (Raspberry Pi and ARM boards) and /sys/class/hwmon (coretemp on Intel, k10temp on AMD…). Sensors whose name clearly designates the CPU are preferred.

If your machine exposes no sensor at all (virtual machine, LXC container, non-Linux host), the temperature feature is simply not created: the other four keep working.

If the chosen sensor is not the right one, use the List temperature sensors button: it shows every visible sensor with its current reading and marks the one in use with a >. Copy the path you want into CPU temperature sensor.

Available actions​

  • Read the metrics now — reads everything immediately and shows the result under the button, without waiting for the next refresh. This is the first test to run when a value looks wrong.
  • List temperature sensors — see above.

Troubleshooting​

No value shows up. Check that the device was actually added from the Discovery tab: until it is created, Gladys silently ignores published states. As soon as you add it, the integration publishes a full snapshot again — so the five metrics appear within seconds, without waiting for the next refresh or the next guaranteed point.

The device shows "No recent value". That badge appears when no state has been recorded for 48 hours — so, in practice, never. Use the Read the metrics now action: it ends with "N state(s) published". If N is at least 1, the integration does publish, and the problem is the feature matching described right below.

The device was created by an older version. Gladys never updates the features of a device that already exists: publishing the device again only refreshes its entry on the Discovery screen. A device created with older identifiers therefore keeps them, and the states published for the new ones are dropped without a visible error (the Gladys server logs DeviceFeature "..." not found (or not added to Gladys), skipping state update.). The integration detects this at startup and reports it in the configuration screen. The only fix is to remove the device in Gladys, then add it again from the Discovery screen. That is also how you apply a change to the Keep history option, or make the temperature appear on a device created before the sensor was detected.

The temperature is missing. That is expected on a VM. Use the List temperature sensors action to confirm the kernel exposes none.

The charts look like stairs. That is the intended behaviour: between two published points, the value did not move more than the threshold. Lower the minimum variation for more detail — at the cost of a bigger database.

The values look smoothed. The published CPU usage is the average over the refresh interval, not an instant sample: a 2-second spike inside a 5-minute window stays barely visible. Shorten the interval if you are hunting short spikes.

The integration logs every read. Check the logs from the Gladys interface, with LOG_LEVEL=debug for the full detail.

Configuration settings​

These are the settings Supervision hôte asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Host supervisionsectionNoOne device exposing the health of the machine that runs Gladys: CPU usage, memory usage, disk usage, free disk space and CPU temperature. Everything is read locally from /proc and /sys, no agent and no cloud service involved.
Device namestringNoName of the device created in Gladys. Useful when several machines are monitored.
Disk path to monitorstringNoPath whose filesystem is measured. The default /data is the integration volume, hosted on the same filesystem as your Gladys data.
CPU temperature sensor (optional)stringNoLeave empty to auto-detect. Otherwise, the sysfs file to read, e.g. /sys/class/thermal/thermal_zone0/temp.
Refresh rate and historysectionNoGladys writes one history row per published value, so a host monitor left unchecked fills the database fast. The integration reads the metrics on its own schedule and only publishes a value when it moved more than the thresholds below — with a guaranteed point at least once per maximum interval so the charts stay continuous.
Refresh interval (s)numberNoHow often the metrics are read, in seconds. 300 s (5 minutes) is plenty for host supervision.
Minimum variation (%)numberNoA percentage reading is only published when it moved by at least this many points since the last published value. 0 publishes every reading.
Minimum variation (°C)numberNoSame threshold, applied to the CPU temperature.
Maximum interval without a point (min)numberNoEven when nothing moves, each metric is published at least once per this interval so the charts keep a continuous line.
Keep historybooleanNoApplied when the device is created. Turn it off to keep only the live values, with no history row at all.

How to install Supervision hôte in Gladys​

  1. In Gladys, open Integrations: Supervision hôte appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/prohand/gladys-host-monitoring:1.0.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/prohand/gladys-host-monitoring.

Supervision hôte requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Supervision hôte is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on