BTRFS Performance Considerations: Page Caching, Writes, Fragmentation, and Optimizations

storage driver. > [!NOTE] > > Many of these factors are mitigated by using Docker volumes for write-heavy > workloads, rather than relying on storing data in the container's writable > layer. However, in the case of Btrfs, Docker volumes still suffer from these > draw-backs unless `/var/lib/docker/volumes/` isn't backed by Btrfs. ### Page caching Btrfs doesn't support page cache sharing. This means that each process accessing the same file copies the file into the Docker host's memory. As a result, the `btrfs` driver may not be the best choice for high-density use cases such as PaaS. ### Small writes Containers performing lots of small writes (this usage pattern matches what happens when you start and stop many containers in a short period of time, as well) can lead to poor use of Btrfs chunks. This can prematurely fill the Btrfs filesystem and lead to out-of-space conditions on your Docker host. Use `btrfs filesys show` to closely monitor the amount of free space on your Btrfs device. ### Sequential writes Btrfs uses a journaling technique when writing to disk. This can impact the performance of sequential writes, reducing performance by up to 50%. ### Fragmentation Fragmentation is a natural byproduct of copy-on-write filesystems like Btrfs. Many small random writes can compound this issue. Fragmentation can manifest as CPU spikes when using SSDs or head thrashing when using spinning disks. Either of these issues can harm performance. If your Linux kernel version is 3.9 or higher, you can enable the `autodefrag` feature when mounting a Btrfs volume. Test this feature on your own workloads before deploying it into production, as some tests have shown a negative impact on performance. ### SSD performance Btrfs includes native optimizations for SSD media. To enable these features, mount the Btrfs filesystem with the `-o ssd` mount option. These optimizations include enhanced SSD write performance by avoiding optimization such as seek optimizations that don't apply to solid-state media. ### Balance Btrfs filesystems often Use operating system utilities such as a `cron` job to balance the Btrfs filesystem regularly, during non-peak hours. This reclaims unallocated blocks and helps to prevent the filesystem from filling up unnecessarily. You can't rebalance a totally full Btrfs filesystem unless you add additional physical block devices to the filesystem. See the [Btrfs Wiki](https://btrfs.wiki.kernel.org/index.php/Balance_Filters#Balancing_to_fix_filesystem_full_errors). ### Use fast storage Solid-state drives (SSDs) provide faster reads and writes than spinning disks. ### Use volumes for write-heavy workloads Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and don't incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting even when no running container is using them. ## Related Information - [Volumes](../volumes.md) - [Understand images, containers, and storage drivers](index.md) - [Select a storage driver](select-storage-driver.md)

This section discusses performance factors affecting Docker's Btrfs storage driver, including page caching (no sharing, impacting high-density use), small writes (leading to space issues), sequential writes (journaling can reduce performance), fragmentation (due to copy-on-write), and SSD performance (using `-o ssd` mount option). It recommends balancing the filesystem regularly, using fast storage, and using volumes for write-heavy workloads to improve performance. Also mentioned is that while Docker volumes mitigate performance concerns, they still suffer drawbacks unless `/var/lib/docker/volumes/` is not backed by Btrfs.