Performance Tuning

This guide covers the key tuning parameters for optimizing flexFS performance across different workloads.

Block size

The block size determines how file data is split into chunks for storage. It is configured at volume creation time and cannot be changed afterward.

Block size	Best for	Trade-offs
256Ki (256 KiB)	Small files, random access	More metadata overhead, more requests per large file
512Ki (512 KiB)	Mixed workloads	Balanced
1Mi (1 MiB)	General purpose	Good default for most workloads
2Mi (2 MiB)	Large sequential files	Less metadata, fewer requests
4Mi (4 MiB)	Large files, HPC, genomics	Default. Optimal for files > 100 MB
8Mi (8 MiB)	Very large sequential files, streaming	Highest throughput for large files, wastes space on small files

Tip

For workloads dominated by large files (genomics BAM/CRAM, AI/ML training data, video), use 4Mi or 8Mi. For workloads with many small files (source code, configuration), use 256Ki or 512Ki.

Memory cache sizing

The in-memory block cache reduces latency by keeping recently accessed blocks in RAM.

Flag	Default	Description
--dirtyCapacity	Auto-tuned	Number of dirty (unwritten) blocks to buffer in memory before flushing.
--memCapacity	Auto-tuned	In-memory LRU cache capacity. Accepts a percentage of system RAM (e.g. 2%), a human-readable size (e.g. 4G, 512M), or a number of blocks (e.g. 2000).
--poolCapacity	Auto-tuned	Size of the block buffer pool.

The defaults are automatically calculated based on available system RAM. Override them for specific workloads:

mount.flexfs start my-volume /mnt/data --memCapacity 4G --dirtyCapacity 512

Higher --memCapacity improves read performance for working sets that fit in memory. Higher --dirtyCapacity improves write throughput by allowing more blocks to be buffered before being flushed to storage.

Disk cache

The on-disk cache provides a second tier of caching that survives process restarts and can be much larger than the memory cache.

Flag	Default	Description
--diskFolder	~/.flexfs/mount/cache/<pid>	Path to the on-disk cache folder
--diskMaxBlockSize	262144	Maximum processed block size (bytes) that will be cached to disk
--diskQuota	(disabled)	Maximum disk space to use. Accepts absolute values (e.g., 50G) or percentages (e.g., 80%). Disk caching is disabled unless this is set.

mount.flexfs start my-volume /mnt/data \
  --diskFolder /var/cache/flexfs \
  --diskQuota 100G

Disk writeback

Enable disk-level writeback caching to mask write latency:

mount.flexfs start my-volume /mnt/data \
  --diskFolder /var/cache/flexfs \
  --diskWriteback

With --diskWriteback enabled, writes are acknowledged as soon as the block is written to the local disk cache. The block is then asynchronously uploaded to object storage (or the proxy). This significantly reduces write latency for workloads that can tolerate a short window where data exists only on local disk.

Caution

With disk writeback, data written but not yet uploaded to object storage will be lost if the local disk fails. Use a reliable local storage medium.

Write tuning

Flag	Default	Description
--dirtyActive	Auto-tuned	Maximum number of dirty blocks that can be actively syncing to storage simultaneously. Higher values increase write throughput at the cost of more concurrent network connections.
--maxBops	Auto-tuned	Maximum number of block operations (reads and writes) that can run in parallel.

For write-heavy workloads:

mount.flexfs start my-volume /mnt/data --dirtyActive 64 --maxBops 128

Prefetch tuning

Block prefetching detects sequential read patterns and preloads upcoming blocks before they are requested.

Flag	Default	Description
--noPrefetch	false	Disable prefetching entirely.
--prefetchActive	Auto-tuned	Maximum number of prefetch operations running in parallel.

For sequential workloads (e.g., streaming large files, genomics pipelines):

mount.flexfs start my-volume /mnt/data --prefetchActive 32

For purely random workloads, prefetching adds overhead. Disable it:

mount.flexfs start my-volume /mnt/data --noPrefetch

FUSE tuning

These flags control the Linux FUSE interface behavior:

Flag	Default	Description
--asyncRead	false	Enable FUSE async reads. Allows the kernel to issue multiple read requests concurrently.
--attrValid	28800	Time in seconds for which file attributes are cached in the kernel. Higher values reduce metadata server load. The invalidation event bus keeps cached attributes coherent across mounts, so the TTL is only a fallback bound.
--entryValid	1	Time in seconds for which directory entry (name) lookups — including negative/not-found results — are cached in the kernel. When a peer changes a name the kernel may have cached, the client asks it to drop its cached answer straight away, so most peer changes are reflected within milliseconds. That is best-effort — no client can know every name the kernel has cached — so cross-mount name coherence is still bounded by this TTL; lower it if peers must observe created/renamed/deleted names quickly.
--noMaxPages	false	Do not set the FUSE max_pages option to its maximum value. By default, flexFS maximizes FUSE page size for best throughput.

For maximum single-client throughput, enable async reads — the 8-hour --attrValid / --entryValid defaults already maximize metadata caching:

mount.flexfs start my-volume /mnt/data \
  --asyncRead

The defaults suit multi-client workloads for attributes: the invalidation event bus keeps cached attributes coherent across mounts (typically within milliseconds), and a disrupted notification channel triggers an attribute/data flush on reconnect — so attribute freshness does not depend on a short --attrValid. Directory-entry (name) coherence is weaker. A peer’s create, rename, or delete does prompt an immediate invalidation of the kernel’s cached name, so it is usually visible within milliseconds — but no client can know every name the kernel holds, so that is best-effort, and --entryValid remains the worst case for an already-cached name. It is also the one bound the reconnect flush does not cover: recovery flushes inodes, not names. The mount client’s internal dentry cache absorbs the extra LOOKUPs a lower --entryValid produces, so most are answered locally instead of becoming metadata-server round trips (see Caching Architecture). Lower --attrValid for a tighter bound on a missed attribute invalidation, and lower --entryValid if clients must observe each other’s name changes quickly:

mount.flexfs start my-volume /mnt/data \
  --attrValid 60 \
  --entryValid 60

Kernel readahead

Linux kernel readahead can complement flexFS prefetching. Increase it for sequential workloads:

# Set readahead to 4 MB for the FUSE device
echo 4096 > /sys/class/bdi/0:$(stat -c %T /dev/fuse)/read_ahead_kb

Directory tuning

Flag	Default	Description
--dirPageSize	5000	Number of directory entries per page in the directory stream. Larger values improve performance for large directories.
--dirTTL	10	Time in seconds for which directory stream pages are cached.

Proxy group placement

For Enterprise deployments using proxy groups:

• Place proxy servers in the same region as the mount clients they serve.
• Mount clients automatically select the lowest-latency proxy group via RTT probing.
• Use multiple proxy servers per group for load distribution (blocks are distributed via rendezvous hashing).

Workload-specific recommendations

Genomics / HPC

mount.flexfs start genomics-vol /mnt/data \
  --diskFolder /nvme/cache \
  --diskQuota 500G \
  --prefetchActive 32 \
  --asyncRead

AI/ML training data

mount.flexfs start training-vol /mnt/data \
  --diskFolder /nvme/cache \
  --diskQuota 1T \
  --asyncRead \
  --prefetchActive 64

General interactive workloads

mount.flexfs start shared-vol /mnt/data \
  --diskFolder /var/cache/flexfs \
  --diskQuota 80%

Next steps

• Capacity planning
• Logging and diagnostics — use RTT logging to identify bottlenecks
• Caching architecture — understand the three-tier cache model