Monitor Directory Sizes with Prometheus Folder Exporter: Don’t Wait for a Full Disk to Panic

A 2 AM Nightmare

Your phone vibrates incessantly. Alertmanager reports that the production server is running out of storage. You jump up, SSH into the server, and type the familiar command: df -h. Result: The / partition is 98% full. The problem is, this partition contains everything from system logs and Docker volumes to user data.

Usually, you’d have to run du -sh /* and wait forever to find which directory is hogging resources. If the server has millions of small files, this command could take ten minutes. Previously, I often spent an hour just finding which log file was looping. Now, I just look at the Grafana Dashboard to instantly see which folder is “eating” the disk and fix it in seconds.

While Node Exporter monitors partitions excellently, it’s blind to what’s happening inside individual folders. That’s why you should install Prometheus Folder Exporter.

Why Node Exporter Alone Isn’t Enough

Node Exporter provides the node_filesystem_avail_bytes metric, which tells you the remaining free space. However, when running Microservices or Docker, knowing exactly which directory is growing is the key to fast incident response.

• Log Monitoring: Catch log files that spike by gigabytes per hour due to application debug errors.
• Database Monitoring: Monitor data directories to know when to expand storage before the database hangs.
• Backup Management: Verify that periodic backups are created with the correct size, avoiding empty (0-byte) backup files.

Installing Prometheus Folder Exporter

There are several exporter versions, but I prefer the Go version by pavelly because it’s extremely lightweight and stable. Here is how to install it directly on Linux.

Step 1: Download and Install the Binary

First, create a dedicated user to run the exporter to ensure system security:

# Create a user without login privileges
sudo useradd --no-create-home --shell /bin/false folder_exporter

# Download the binary from GitHub
wget https://github.com/pavelly/prometheus-folder-exporter/releases/download/v1.1.0/prometheus-folder-exporter-linux-amd64 -O folder-exporter

# Set permissions and move to the executable directory
chmod +x folder-exporter
sudo mv folder-exporter /usr/local/bin/

Step 2: Configure Directories to Monitor

This exporter uses a YAML file to define the paths to “watch”. Create a file at /etc/folder-exporter.yaml with the following content:

folders:
  - mount_point: "/var/log"
    name: "system_logs"
  - mount_point: "/var/lib/docker/volumes"
    name: "docker_volumes"
  - mount_point: "/data/database"
    name: "db_storage"

Step 3: Run Service with Systemd

To have the exporter automatically restart if the server reboots, create a service file at /etc/systemd/system/folder-exporter.service:

[Unit]
Description=Prometheus Folder Exporter
After=network-online.target

[Service]
User=root
Group=root
Type=simple
ExecStart=/usr/local/bin/folder-exporter -config /etc/folder-exporter.yaml -addr :9102

[Install]
WantedBy=multi-user.target

Note: I’m using root privileges because directories like /var/lib/docker often restrict access for regular users. Then, enable the service:

sudo systemctl daemon-reload
sudo systemctl enable --now folder-exporter

Connecting to Prometheus and Grafana

Once the exporter is running on port 9102, simply add it to your Prometheus scrape list:

scrape_configs:
  - job_name: 'folder_monitoring'
    static_configs:
      - targets: ['localhost:9102']

On Grafana, you can use the following query to convert the unit to GB for easier reading:

folder_size_bytes{name="system_logs"} / 1024 / 1024 / 1024

Alerting on Abnormal Data Growth

Don’t wait until the disk is 100% full to trigger an alarm. Set up alerts if a directory grows by 500MB within just 1 hour. This is a typical sign of application log errors or a DDoS attack.

Add this rule to your Alertmanager:

- alert: FolderGrowthSpike
  expr: (folder_size_bytes - folder_size_bytes offset 1h) > 500 * 1024 * 1024
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Storage spike on {{ $labels.instance }}"
    description: "Folder {{ $labels.name }} has increased by more than 500MB in the last hour. Check it now!"

A Few Practical Tips from Experience

Through actual deployment, I’ve drawn three important conclusions:

1. Don’t scan too frequently: Calculating folder size (equivalent to the du command) consumes disk I/O. For heavy folders, you should set the scrape_interval to about 2-5 minutes instead of the default 15 seconds.
2. Careful Permissioning: If you don’t want to use root, you must add the folder_exporter user to a group that has read permissions for the target directories.
3. Use in Parallel: Use Node Exporter for “critical threshold” alerts (e.g., disk at 5% remaining) and use Folder Exporter to find the root cause.

This tool is small but extremely powerful in helping you proactively control resources. Good luck with your configuration, and may you have peaceful nights undisturbed by alarm bells!