Prometheus Metrics

ZeroFS can expose metrics in Prometheus format over an HTTP endpoint.

Configuration

Add a [prometheus] section to your configuration file:

[prometheus]
addresses = ["127.0.0.1:9091"]

This starts an HTTP server on the specified address. Metrics are available at /metrics:

curl http://127.0.0.1:9091/metrics

Multiple bind addresses are supported, following the same pattern as other ZeroFS servers:

[prometheus]
addresses = ["127.0.0.1:9091", "[::1]:9091"]  # Dual-stack localhost

Each entry binds one listener, so the addresses must not overlap. 0.0.0.0:9091 already accepts loopback connections; adding 127.0.0.1:9091 alongside it conflicts on the same port, and the losing bind is logged and dropped.

addresses defaults to 127.0.0.1:9091. An empty [prometheus] section is valid and starts the endpoint on that address. When the [prometheus] section is absent, no metrics endpoint is started.

Available Metrics

Filesystem Operations

Counters that track cumulative operations since server start:

I/O

Tombstone Cleanup

The metrics above cover the tombstone-cleanup worker that removes a deleted file's extents. Segment reclamation and repacking, which recover dead space inside the immutable segment objects that hold file data, are reported separately below.

Segment Footprint

These gauges describe encoded frame bytes tracked by segment counters, including committed frames still in the open or sealing buffers. They are seeded from a counter scan at open and updated as writes, repoints, and deletions commit, so dead space remains current between reclamation cycles.

Segment Reclamation and Repacking

Counters accumulate across reclamation cycles since server start. Safety-window gauges describe pending deletion, while executor gauges measure work in flight at scrape time. Each cycle scans the segment counters, deletes fully dead segments, and drives concurrent repack jobs; the daily orphan sweep handles counter-less objects.

Segment reclamation and repacking run only on the read-write leader. Read replicas and checkpoint mounts run no reclamation, so these series stay flat there.

Filesystem State

Memory (jemalloc)

Gauges that report the state of the jemalloc allocator:

zerofs_jemalloc_resident_bytes tracks the allocator's physical memory footprint. zerofs_jemalloc_retained_bytes counts virtual address space kept for reuse and does not consume physical memory, so memory alerts should key on resident, not retained or mapped.

Metadata LSM

ZeroFS exposes internal metrics from its metadata LSM tree, which holds inode and directory metadata plus per-extent pointers; file content lives in segment objects outside the LSM. These metrics are prefixed with lsm_ and include compaction and storage statistics. The exact metrics depend on the engine version and are discovered at runtime.

Common metadata metrics include:

Compaction metrics cover metadata compaction only. Segment objects holding file data are not part of the LSM and are never rewritten by it.

Prometheus Scrape Configuration

Add ZeroFS as a target in your prometheus.yml:

scrape_configs:
  - job_name: 'zerofs'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9091']

A background task collects all metric values every 5 seconds, and the endpoint serves the last collected values. A scrape_interval below 5 seconds does not increase resolution.