Type: disk_space | Runner: Agent only
Reads disk usage for a mount point on the monitored host and compares it against configurable thresholds.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path |
text | Yes | / |
Absolute path of the mount point to monitor (e.g. /, /var, /mnt/backup) |
warn_percent |
number | No | 80 |
Warn when disk usage reaches or exceeds this percentage |
fail_percent |
number | No | 90 |
Fail when disk usage reaches or exceeds this percentage. Must be greater than warn_percent. |
| Status | Condition |
|---|---|
| OK | Disk usage is below warn_percent |
| Warn | Disk usage >= warn_percent and < fail_percent |
| Fail | Disk usage >= fail_percent |
| Unknown | Path not found or not a directory |
| Unknown | Invalid config (fail_percent <= warn_percent) |
| Unknown | No path configured |
The message always reports the usage percentage and free/total space in human-readable format (e.g. 72% used (28.3 GB free of 100.8 GB)).
The agent must mount the host filesystem and set the HOST_ROOT environment variable:
# compose.stage.yml or docker-compose.agent.yml
agent:
environment:
HOST_ROOT: /host/root
volumes:
- /:/host/root:ro
HOST_ROOT is prepended to the configured path before calling PHP's filesystem functions. Without it, the check measures disk space inside the container instead of on the host.
| Mount | Usage |
|---|---|
/ |
Root filesystem — overall server disk usage |
/var |
Logs and variable data — often fills up on busy servers |
/var/lib/docker |
Docker images and volumes |
/mnt/backup |
External backup storage |