Writing a Python Script That Monitors File System Quota Usage
A full disk can bring a Linux server to a halt long before anyone notices an obvious failure. Databases stop writing, SSH sessions behave unpredictably, web applications return errors, and log files may disappear just when they are needed for diagnosis. A small Python monitor can identify that risk early and preserve a useful audit trail.
Quota monitoring is especially valuable on shared development machines, hosting servers, build runners, and systems that store large application logs. A script can record capacity, calculate a percentage, compare it with a threshold, and emit an alert without requiring a large monitoring platform.
The example below uses Python’s os.statvfs() interface, which reports filesystem block statistics and is commonly available on Linux. It is suitable for checking paths such as /srv, /var/log, or a user’s home directory. User, group, and project quotas may need an additional check through tools such as quota or xfs_quota.
Why quota monitoring needs context
A filesystem can have free space while a particular account has reached its assigned quota. The reverse can also happen: a user may have a generous quota, but the underlying volume can be nearly full. These are separate conditions, so a dependable monitor should define whether it is measuring volume capacity, the current user’s available blocks, or a formal user and group limit.
statvfs() exposes total blocks and available blocks for a path. On many Linux configurations, the available-block value reflects what the calling user can consume, including quota restrictions. It should still be treated as an operational signal rather than a universal replacement for the system’s quota reporting utilities.
The path matters as well. Monitoring / does not necessarily reveal a full /var partition, while checking /home may miss a separate application volume mounted at /srv. Use the same mount points that matter to the services running on the machine.
Choose the right Linux signal
The most useful first step is to establish a threshold and a collection interval. An 80 per cent warning threshold gives administrators time to investigate, while a 90 or 95 per cent critical threshold indicates immediate action. The correct values depend on how quickly the workload grows and whether the system holds large files such as backups or media.
For a server in Sydney or Melbourne, the local hosting region does not change the filesystem calculation, but it can affect response procedures and alert routing. A team working across Brisbane, Perth, and Adelaide should store timestamps in UTC and convert them for local rosters, because Australian daylight-saving rules differ between states.
The following script records measurements as JSON lines. Each record can be searched with standard command-line tools, forwarded to a log collector, or imported into a small reporting utility.
#!/usr/bin/env python3
import json
import logging
import os
from datetime import datetime, timezone
WATCHED_PATHS = {
"/srv": 80,
"/var/log": 85,
}
LOG_FILE = "/var/log/quota-monitor.log"
logging.basicConfig(
filename=LOG_FILE,
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
)
def measure(path):
stats = os.statvfs(path)
total = stats.f_blocks * stats.f_frsize
available = stats.f_bavail * stats.f_frsize
used = total - available
percent = (used / total * 100) if total else 100.0
return {
"path": path,
"used_bytes": used,
"available_bytes": available,
"usage_percent": round(percent, 2),
}
for path, threshold in WATCHED_PATHS.items():
try:
result = measure(path)
result["timestamp"] = datetime.now(timezone.utc).isoformat()
result["threshold_percent"] = threshold
if result["usage_percent"] >= threshold:
logging.warning(json.dumps({"status": "warning", **result}))
else:
logging.info(json.dumps({"status": "ok", **result}))
except OSError as error:
logging.error(json.dumps({
"status": "error",
"path": path,
"message": str(error),
}))
Build a useful audit trail
A log entry should contain enough information to explain what happened later. The path, UTC timestamp, usage percentage, threshold, and available bytes are more useful than a sentence such as “disk nearly full”. JSON makes the output straightforward to process with jq, Python, or a central log service.
Protect the log itself from becoming the problem. Store it on a monitored partition, configure logrotate, and decide how long records should be retained. A simple rotation policy might keep daily files for a month, while regulated or business-critical environments may require a longer retention period.
A visual summary can help non-specialist operators identify growth trends quickly. If a team is preparing a lightweight status page or dashboard, visual reporting ideas can provide a useful reference for presenting thresholds and historical usage without obscuring the underlying data.
Schedule alerts without noise
Run the script with systemd timers or cron. A five-minute interval is appropriate for fast-growing temporary storage, while hourly checks may be enough for a stable archive volume. The scheduler should run under an account that can read every monitored path and write to the selected log file.
Logging every warning on every run can flood an inbox. A production version should remember the previous state and alert only when a path crosses into a warning or critical band, then send a recovery message after usage falls below the threshold. This hysteresis avoids repeated notifications when usage fluctuates around 80 per cent.
Email is still common in the Australian hosting market, but webhook delivery to an operations platform is often easier to route. Ensure the notification includes the hostname, mount path, percentage, and available bytes. A message that says “build01 /srv at 86.4%, 41 GB remaining” is actionable without opening a shell session.
Extend the check for real quotas
For formal user or group quotas, call the platform’s native reporting command and parse its structured output where possible. On ext4 systems, quota and repquota are common tools; XFS administrators may use xfs_quota. Command output varies by distribution, so test parsing against the exact Linux release used in production rather than relying on a single sample.
You can also enrich the monitor with inode usage. A volume may have plenty of bytes left but run out of inodes because an application creates millions of small cache files. statvfs() provides f_files and f_favail, allowing the same threshold approach to cover both storage blocks and file entries.
For an Australian business, this matters during predictable growth periods such as end-of-financial-year reporting, promotional campaigns, or large migration projects. A Sydney cloud instance and a Perth office server may have different workloads, but both benefit from consistent UTC logs, documented limits, and a local escalation path.
Practical safeguards for production
A short script becomes much more dependable when its operating assumptions are explicit. Document which paths are monitored, which account runs the check, how quota limits are configured, and who receives alerts. Test the warning path in a staging directory before deliberately filling a production volume.
Useful safeguards include:
- Use absolute paths and fail clearly when a mount point is missing.
- Keep timestamps in UTC, with local Australian time applied only in dashboards or rosters.
- Monitor both byte consumption and inode consumption.
- Rotate the monitor’s own log and protect it with appropriate file permissions.
- Add stateful alerting so repeated checks do not create notification fatigue.
This approach keeps the implementation small enough to audit while leaving room for native quota commands, centralised logging, and service-specific alerting as the environment grows.
