File Metrics Exporter

Prometheus exporter that monitors file system statistics for specified directories and files.

Supported metrics

• File last modification time (as a Unix timestamp)
• File size (in bytes)

Features

• 📊 File Metrics Collection: Track file size and last modification time.
• 🔎 Configurable Targets: Define exactly which directories and files you want to monitor.
• 🔥 Prometheus Integration: Exposes metrics in standard Prometheus format.
• ⚡ Metrics Caching: Define a cache TTL (Time-To-Live) for metrics to reduce filesystem load when scraped by multiple Prometheus instances.
• 🛠️ Systemd Service: Ready-to-use systemd service file for easy deployment.

Use Cases

Monitor filesystem state directly in Prometheus with these common patterns:

Scenario	What to Monitor	Key Metric	Purpose
Log Management	/var/log/app/	file_size_bytes	Alert before logs fill the disk
Backup Verification	Backup files (e.g., backup-*.tar)	file_modification_time	Confirm backups run on schedule
Upload Monitoring	Upload directories (/srv/uploads/)	file_size_bytes	Track user activity & plan capacity
Security Audit	Critical configs (/etc/passwd, /etc/sudoers)	file_modification_time	Detect unauthorized changes
Cache Cleanup	Cache directories (/tmp/cache/)	file_modification_time	Identify & clean stale files
Cluster Sync	Shared configs across nodes	file_modification_time across labels	Verify configuration consistency

Quick Integration:
Add alerts in Prometheus based on metric thresholds, or visualize trends in Grafana using the directory and name labels.

🚀 Quick Start

1. Clone the repository:

git clone https://github.com/isoberemko/file-exporter.git
cd file-exporter

2. Build the binary:

make build

This creates the file-exporter binary in the project root.

If you are deploying in an air-gapped environment, you can build the executable on a machine with internet access and transfer it as part of the cloned repository folder.

3. Install as systemd service:

sudo make install

4. Configure targets: Edit the configuration file at /opt/file-exporter/targets.json. See the Configuration section for details and examples.

📝 Configuration

Environment Variables

Configure the exporter's behavior by setting the following environment variables in the /opt/file-exporter/.env file.

Environment variable	Type	Default value	Example	Description
EXPORTER_PORT	Integer	9215	8099	The port the exporter listens on.
EXPORTER_METRICS_ENDPOINT	String	/metrics	/mymetricspath	The HTTP endpoint where metrics are published.
EXPORTER_METRICS_CACHE_TTL	Integer	0	5	Cache TTL in seconds. Metrics will not be re-read from disk during this period.
TARGETS_CONFIG	String	-	/opt/myconfig/targets.json	Absolute path to the JSON configuration file defining targets.
LOG_FORMAT	String	json	text	Log output format. Options: json or text (human-readable plain text).
LOG_LEVEL	String	info	debug	Minimum log level to output. Options: debug, info, warn, error.

Configure your targets

Edit your targets configuration file:

• directories: List of directories to monitor (Array of strings). The exporter will collect metrics for all files within these directories. Supports nested directories.
• files: List of specific files to monitor (Array of strings).
• max_depth: Limits how deep the exporter traverses subdirectories (Integer).
  • max_depth: 0 monitor all nested directories (default)
  • max_depth: 1 monitor only immediate children (non-recursive behavior)
  • max_depth: 3 monitor up to 3 levels deep

Example 1: Monitoring both directories and specific files

{
    "directories": [
        "/var/log",
        "/tmp"
    ],
    "files": [
        "/etc/passwd",
        "/etc/hosts"
    ]
}

Example 2: Monitoring directories only

{
    "directories": [
        "/var/log",
        "/opt/app/data"
    ]
}

Example 3: Monitoring specific files only

{
    "files": [
        "/etc/shadow",
        "/boot/grub/grub.cfg"
    ]
}

Example 4: Monitoring cmbined targets with limited depth of directory recursion

{
    "directories": [
        "/var/log",
        "/etc"
    ],
    "files": [
        "/etc/passwd",
        "/etc/hosts"
    ],
    "max_depth": 2
}

Collectable metrics

Metric Name	Type	Description	Labels
file_modification_time	Gauge	Last modification time as Unix timestamp.	directory name
file_size_bytes	Gauge	File size in bytes.	directory name

Labels

Label	Description
directory	The absolute path to the directory where the collected file is located. For a file specified directly in the files list, this will be its parent directory.
name	The name of the collected file.