wekan/docs/Features/Admin-Panel/Problems/Disk-usage.md

Design: Disk-usage monitor and Admin Panel → Problems report

Status: Design (proposed) · Owner: xet7 · Related (to be added): server/lib/diskMonitor.js, server/lib/diskLog.js, models/lib/diskHighTracker.js, models/eventLog.js, Admin Panel → Problems → Disk usage.

Sibling of the CPU-usage and RAM-usage monitors. A disk that fills up breaks WeKan (and FerretDB/SQLite) hard: uploads fail, the database cannot write, and other software on the same machine stops too. This subsystem watches free disk space on the filesystems WeKan uses and records only the start and end of each sustained high-usage period to an Admin Panel → Problems → Disk usage report, so operators get an early, self-describing warning before the disk is full — without a flood of rows.

1. Requirements

1. While WeKan (and FerretDB alongside it) run, watch how much disk space is used on the filesystems that matter: the data/state filesystem (FerretDB SQLite / Mongo data), the attachments storage path (WRITABLE_PATH / the configured storage), and the temp path used while sanitizing uploads.
2. Add an Admin Panel → Problems → Disk usage report.
3. Log when high usage starts and when high usage ends — only those two rows per episode, so the report never floods.
4. Each row records how much disk is used and free (used / total and percentage) per watched filesystem, the peak during the episode, its duration, and what WeKan/FerretDB were doing at the time.
5. Best-effort and never throws; a no-op where free-space info is unavailable (e.g. a sandbox where statfs is not permitted) — this mirrors the existing upload disk-space check in Filename, which already falls back to small-RAM chunked streaming when free space cannot be read.

2. Design

Mirrors the CPU/RAM subsystems so the three Problems monitors share one shape, one event-stream mechanism, and one report template.

Measurement — the filesystems WeKan uses

server/lib/diskMonitor.js samples on an interval (WEKAN_DISK_SAMPLE_INTERVAL_MS, default 30s — disks change more slowly than CPU/RAM, so a longer interval avoids needless statfs calls):

• Uses fs.statfs(path) (Node ≥ 18) for each watched path: bsize × blocks = total bytes, bsize × bavail = bytes available to non-root. Used% = (total − available) / total × 100.
• Watched paths (de-duplicated by the filesystem they resolve to, so one physical disk is reported once): the data/state directory, WRITABLE_PATH (attachments), and WRITABLE_PATH/files/temp (upload sanitizing). Configurable via WEKAN_DISK_WATCH_PATHS (a :-separated list) for non-standard layouts.

Start/end only — models/lib/diskHighTracker.js

A pure, unit-tested state machine (identical shape to cpuHighTracker.js), tracked per watched filesystem so a full data disk and a full attachments disk are distinct episodes. Hysteresis prevents flapping:

• enter the high state after WEKAN_DISK_HIGH_SAMPLES (2) consecutive samples at/above WEKAN_DISK_HIGH_PERCENT (default 90% used);
• leave it after WEKAN_DISK_LOW_SAMPLES (2) consecutive samples below WEKAN_DISK_LOW_PERCENT (default 85% used);
• track the peak used% seen during the episode for the end row.

Report — Admin Panel → Problems → Disk usage

Episodes are written to the eventLog collection on the disk stream (alongside cpu and ram), shown by the existing eventStreamReport template. Two rows per episode, per filesystem:

• start (detected): high disk usage started (>= 90%) on /var/lib/wekan (attachments): 92% used, 6.1 GB free of 80 GB, WeKan: <activity>
• end (remediated): high disk usage ended after 12m on /var/lib/wekan (peak 97%, back under 85%): 71% used, 23 GB free of 80 GB

Severity: high at ≥ 95% used (imminent failure), else medium.

3. Environment variables

Variable	Default	Meaning
WEKAN_DISK_MONITOR	true	Master on/off.
WEKAN_DISK_SAMPLE_INTERVAL_MS	30000	Sampling interval.
WEKAN_DISK_HIGH_PERCENT	90	Enter high state at/above this used %.
WEKAN_DISK_LOW_PERCENT	85	Leave high state below this used %.
WEKAN_DISK_HIGH_SAMPLES	2	Consecutive high samples to enter.
WEKAN_DISK_LOW_SAMPLES	2	Consecutive low samples to leave.
WEKAN_DISK_WATCH_PATHS	(auto)	:-separated paths to watch, overriding the defaults.

4. Notes

• The tracker and the statfs → percentage helper are pure functions unit-tested without Meteor (positive + negative: missing free-space info, zero-total filesystems, per-filesystem episodes), exactly like cpuHighTracker.js.
• Observe-and-report only, like RAM-usage: WeKan cannot free disk on its own, so the value is an early, self-describing warning. It complements the existing pre-upload free-space check in Filename, which already refuses/streams-carefully when the attachments disk is low.