Using node_exporter Textfile Collector to Expose Custom Metrics for Prometheus

node_exporter not only gathers system metrics but also supports custom monitoring through its textfile collector module, which can expose user‑generated metrics to Prometheus. To enable it, start node_exporter with the --collector.textfile.directory flag pointing to a directory where metric files ending with .prom are placed.

Custom metrics must follow the standard Prometheus text exposition format, for example:

# HELP example_metric Metric read from /some/path/textfile/example.prom
# TYPE example_metric untyped
example_metric 1

Each metric file should include consistent HELP and TYPE lines; mismatched definitions across files will cause collection errors.

Scripts that generate .prom files are typically run from crontab . To avoid race conditions where node_exporter reads a file while it is being written, write to a temporary file and then atomically rename it, e.g.:

*/5 * * * * $TEXTFILE/printMetrics.sh > /path/to/directory/metrics.prom.$$ && mv /path/to/directory/metrics.prom.$$ /path/to/directory/metrics.prom

node_exporter also adds a metric for the modification time of each textfile, node_textfile_mtime_seconds , which can be used to trigger alerts if a file has not been updated within a expected interval (e.g., less than 15 minutes).

Beyond numeric metrics, the textfile collector can expose static information such as system roles:

echo 'role{role="application_server"} 1' > /path/to/directory/role.prom.$$ 
mv /path/to/directory/role.prom.$$ /path/to/directory/role.prom

An example script directory-size.sh (from the official repository) collects directory usage and outputs it in Prometheus format:

#!/bin/sh
#
#  Expose directory usage metrics, passed as an argument.
#
#  Usage: add this to crontab:
#
#  */5 * * * * prometheus directory-size.sh /var/lib/prometheus | sponge /var/lib/node_exporter/directory_size.prom
#
#  sed pattern taken from https://www.robustperception.io/monitoring-directory-sizes-with-the-textfile-collector/
#
#  Author: Antoine Beaupré
echo "# HELP node_directory_size_bytes Disk space used by some directories"
echo "# TYPE node_directory_size_bytes gauge"
du --block-size=1 --summarize "$@" \
  | sed -ne 's/\\/\\\\/;s/"/\\"/g;s/^\([0-9]\+\)\t\(.*\)$/node_directory_size_bytes{directory="\2"} \1/p'

Configure node_exporter to watch the directory, for example /root/p8strain/textfile , then restart the service:

☸ ➜ systemctl daemon-reload
☸ ➜ systemctl restart node_exporter

To ensure atomic writes, the sponge utility from the moreutils package can be used; install it on CentOS with:

☸ ➜ yum -y install epel-release
☸ ➜ yum -y install moreutils

Save the script as directory-size.sh under /root/p8strain and add a cron job to run it every five minutes:

☸ ➜ crontab -e
#  加入如下所示定时任务
☸ ➜ crontab -l
*/5 * * * *  /root/p8strain/directory-size.sh /root/p8strain | sponge /root/p8strain/textfile/directory_size.prom

The generated directory_size.prom file will contain:

# HELP node_directory_size_bytes Disk space used by some directories
# TYPE node_directory_size_bytes gauge
node_directory_size_bytes{directory="/root/p8strain"} 459378688

Prometheus will scrape this metric, and you can query it to obtain the directory size information, as shown in the screenshots below.