Our Blog

Monitoring MooseFS with Prometheus

July 16th, 2025 | MooseFS Team

post_thumbnail

If you’re running MooseFS in production, you know how important it is to have full visibility into its performance and health. Since the latest release, MooseFS offers native support for exporting system metrics in a format compatible with Prometheus, making it easy to build robust monitoring and alerting pipelines.

In this post, we’ll walk you through how to integrate MooseFS with Prometheus, configure your metric exports efficiently, and avoid overloading your monitoring infrastructure – all while getting the critical insights you need.

Why Prometheus?

Prometheus is a popular open-source toolkit for monitoring and alerting. It’s designed for reliability and real-time performance analysis – making it a perfect match for distributed systems like MooseFS.

The good news: everything visible in the MooseFS GUI is also available as Prometheus metrics, meaning you can plug into familiar visualizations and metrics tooling with ease. These metrics are also annotated with descriptions that appear as tooltips in the MooseFS GUI, Prometheus, and Grafana.

Exporting Metrics from MooseFS

MooseFS exposes two primary data sources for metrics:

  1. Command-Line Data Sets – Retrieved via mfscli, and aligned with GUI data panels.
  2. Chart Metrics – Real-time stats for Master and Chunk Servers, available through the MooseFS GUI.

By default, all data sets and chart metrics are exported – but this can lead to performance issues if you’re running a large cluster. Fortunately, you can filter what you collect.

Recommended CLI Scopes

Here are the most useful and permitted mfscli data sets:

  • SIM: Master states
  • SLI: License info
  • SIG: General master info
  • SMU: Master memory usage
  • SIC: Chunk health status
  • SIL: Loop stats
  • SCS: Chunkserver connections
  • SMB: Metadata backups
  • SHD: HDD stats
  • SSC: Storage classes
  • SMO: Operation counters
  • SQU: Quotas

Some scopes (e.g., SMFSOFSMS) are intentionally not allowed, due to the risk of exporting excessive data.

Setting Up Prometheus to Scrape MooseFS Metrics

Prometheus scrapes MooseFS metrics from the same host and port as the GUI (default: 9425). Here’s a simple scrape config:

scrape_configs:
- job_name: "MooseFS_metrics"
scrape_interval: 60s

scrape_timeout: 20s
static_configs:
- targets: ['your-moosefs-gui-host:9425']

For more fine-tuned setups, you can customize:

  • Host/port of the MooseFS Master
  • Which scopes and charts to include
  • Prefixes to include or exclude

Example of an advanced configuration:

params:
masterhost: ['mfsmaster.my.lan']
masterport: ['9421']
scope: ['SIC,SCS']
mastercharts: ['cpu,mem']
cscharts: ['usedspace']
prefix_whitelist: ['mfs_disks', 'mfs_chunkservers']
prefix_blacklist: ['mfs_info_memory']

You can preview what metrics would be returned using this URL pattern:

http://<mfsguihost>:9425/metrics?masterhost=...&scope=...&mastercharts=...&cscharts=...

Example:

http://localhost:9425/metrics?masterhost=my_masterhost&masterport=9421&scope=SIN,SLI&mscharts=ucpu&cscharts=scpu,ucpu

Example Use Cases

Here are a few real-world configurations based on different monitoring goals:

Full Metrics (for testing or dev clusters)
scope: ['SIM,SLI,SIG,SIC,SIL,SCS,SMB,SHD']
mastercharts: ['all']
cscharts: ['all']
Only HDD Usage from Chunkservers
scope: ['SHD']
mastercharts: ['none']
cscharts: ['none']
prefix_whitelist: ['mfs_disks_total', 'mfs_disks_used', 'mfs_disks_used_percent']
Cluster Throughput (Total In/Out)
scope: ['none']
mastercharts: ['mountbytrcvd', 'mountbytsent']
cscharts: ['none']
Resource Usage (CPU & Memory)
scope: ['SIM,SIG,SMU']
cscharts: ['cpu', 'mem', 'usedspace']
prefix_blacklist: ['mfs_info_masters_misc', 'mfs_info_memory']

A Note on Performance

MooseFS can expose hundreds or thousands of metrics, especially when exporting charts per Chunkserver. If you don’t need all this data in Prometheus, consider using:

  • The MooseFS GUI for occasional deep dives
  • Prefix whitelisting/blacklisting to fine-tune what’s collected
  • Reduced scrape intervals for lightweight metrics

How MooseFS Metrics Are Structured

All metric names start with the mfs_ prefix and mirror the nested structure of the MooseFS JSON output (via mfscli -j).

Examples:

  • mfs_disks_total
  • mfs_chunkservers_hdd_used
  • mfs_info_chunks_summary_regularchunks

Two meta-metrics are also always included:

  • mfs_cli_execution_time: how long it took to collect metrics
  • mfs_cgi_info: version and status info of the CGI endpoint

Wrapping Up

Integrating MooseFS with Prometheus gives you full visibility into your storage infrastructure. Whether you want high-level trends or deep-dive operational metrics, you can shape the integration to suit your performance and visibility needs.