Observability

Stats

Every mount exposes a read-only Prometheus text file at <mount>/.stats:

cat /mnt/brewfs/.stats
watch -n 1 'cat /mnt/brewfs/.stats | head -80'

It contains FUSE throughput and latency, metadata operations, object-store traffic, cache hits and misses, prefetch activity, and writeback pressure. For a live terminal dashboard, build the dedicated client:

cargo build -p brewfs-stats --release
./target/release/brewfs-stats /mnt/brewfs
./target/release/brewfs-stats /mnt/brewfs -i 2

Tracing & logging

Structured logs and tracing spans cover the full IO pipeline — from FUSE request to object commit — so a slow write can be attributed to a specific stage.

RUST_LOG=brewfs=info brewfs mount --config /etc/brewfs/mount.yaml
RUST_LOG=brewfs::vfs::io::reader=trace,brewfs::chunk=debug,brewfs=info \
  brewfs mount --config /etc/brewfs/mount.yaml

Profiling

CPU and allocation profiles can be captured from a running daemon to analyze hot paths under real agent workloads (flamegraph-friendly output).

Use BREWFS_TRACE_CHROME=/tmp/brewfs.trace.json for a Perfetto timeline or BREWFS_TRACE_FLAME=/tmp/brewfs.folded for tracing-flame output. For system-level CPU analysis, tools/perf/run_perf.sh --quick emits on-CPU and off-CPU flamegraphs. These modes add overhead and should be enabled for diagnosis, not as production defaults.