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	Balanced for mixed 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.

Disk cache

The on-disk cache provides a second tier of caching that can be much larger than the memory cache. It is per-process and does not survive a restart: the mount client deletes and recreates the cache folder at startup, so --diskFolder must point at a directory dedicated to the flexFS cache. The default path is <pid>-scoped for that reason — keep the <pid> component if you override it, or two mounts on the same host will destroy each other’s cache.

Flag	Description
--diskFolder	Path to the on-disk cache folder
--diskMaxBlockSize	Maximum processed block size that will be cached to disk (e.g. 256K, 1M)
--diskQuota	Maximum disk space to use. Accepts absolute values (e.g., 50G) or percentages (e.g., 80%). Disk caching is disabled unless this is set.

See the mount.flexfs CLI reference for types and defaults.

mount.flexfs start <volume-name> /mnt/data \
  --diskFolder '/var/cache/flexfs/<pid>' \
  --diskQuota 100G

Disk writeback

Enable disk-level writeback caching to mask write latency:

mount.flexfs start <volume-name> /mnt/data \
  --diskFolder '/var/cache/flexfs/<pid>' \
  --diskQuota 100G \
  --diskWriteback

Disk writeback requires a disk cache, so --diskQuota must be set — without it there is no disk cache and --diskWriteback has no effect.

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.

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/flexfs-cache/<pid>' \
  --diskQuota 500G

The prefetch budget and readahead window are both auto-tuned and are deliberately left alone here.

AI/ML training data

mount.flexfs start training-vol /mnt/data \
  --diskFolder '/nvme/flexfs-cache/<pid>' \
  --diskQuota 1T

General interactive workloads

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

Next steps

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