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", "0.0.0.0:9091"]

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:

Metric	Type	Description
`zerofs_files_created_total`	counter	Files created
`zerofs_files_deleted_total`	counter	Files deleted
`zerofs_files_renamed_total`	counter	Files renamed
`zerofs_directories_created_total`	counter	Directories created
`zerofs_directories_deleted_total`	counter	Directories deleted
`zerofs_directories_renamed_total`	counter	Directories renamed
`zerofs_links_created_total`	counter	Links created
`zerofs_links_deleted_total`	counter	Links deleted
`zerofs_links_renamed_total`	counter	Links renamed

I/O

Metric	Type	Description
`zerofs_read_operations_total`	counter	Total read operations
`zerofs_write_operations_total`	counter	Total write operations
`zerofs_bytes_read_total`	counter	Total bytes read
`zerofs_bytes_written_total`	counter	Total bytes written
`zerofs_total_operations`	counter	Total operations across all types

Garbage Collection

Metric	Type	Description
`zerofs_tombstones_created_total`	counter	Tombstones created for deleted data
`zerofs_tombstones_processed_total`	counter	Tombstones processed by GC
`zerofs_gc_chunks_deleted_total`	counter	Data chunks reclaimed by GC
`zerofs_gc_runs_total`	counter	Number of GC cycles completed

Filesystem State

Metric	Type	Description
`zerofs_used_bytes`	gauge	Total bytes stored in the filesystem
`zerofs_used_inodes`	gauge	Total active inodes (files, directories, symlinks)

Memory (jemalloc)

Gauges that report the state of the jemalloc allocator:

Metric	Type	Description
`zerofs_jemalloc_allocated_bytes`	gauge	Bytes actively allocated by the application
`zerofs_jemalloc_resident_bytes`	gauge	Bytes in physically resident pages mapped by the allocator
`zerofs_jemalloc_mapped_bytes`	gauge	Bytes in active pages mapped by the allocator
`zerofs_jemalloc_retained_bytes`	gauge	Bytes in virtual memory mappings retained for future reuse
`zerofs_jemalloc_metadata_bytes`	gauge	Bytes dedicated to allocator metadata

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.

SlateDB (LSM Engine)

ZeroFS exposes internal metrics from the SlateDB storage engine. These are prefixed with slatedb_ and include compaction and storage statistics. The exact metrics depend on the SlateDB version and are discovered at runtime.

Common SlateDB metrics include:

Metric	Type	Description
`slatedb_compactor_bytes_compacted`	counter	Total bytes processed by compaction
`slatedb_compactor_running_compactions`	gauge	Number of active compaction tasks
`slatedb_compactor_total_bytes_being_compacted`	gauge	Bytes currently being compacted

SlateDB metrics are only available in read-write mode. Read-only instances do not expose SlateDB metrics.

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.