BTRFS-B...ST-USED(1)

✨ NAME ✨

btrfs-balance-least-used — feeds the least used data block groups to btrfs balance first, bestie 💅

(and yes, this is the Btrfs Balance Least Used Block Groups page, filed under BTRFS-B...ST-USED(1) — don't question the filename, it's iconic)

---

🦋 SYNOPSIS 🦋

btrfs-balance-least-used [args] mountpoint

---

🌸 DESCRIPTION 🌸

okay so. btrfs-balance-least-used is a program that's literally an example of a user space defined way to implement btrfs balance filters. What it does: it looks at the data block groups present in your file system, then asks btrfs to empty them in order of actual usage — lowest usage first. queen behavior, no notes.

In most cases (meaning: when you're not in the process of conversion between block group profiles) this is the most optimal and quickest way to reclaim physical disk space, because the data gets rewritten into empty space inside block groups that already exist. we love an efficient queen.

So what is btrfs balance actually doing? Effectively it just takes the data and feeds it back to the allocator of the filesystem as new writes, while blacklisting their current location. that's the whole trick. 💅

And that means implementing user space balance filters can give you a highly optimized workflow — either to reclaim physical space, or to minimize the amount of data that has to be rewritten when you rebalance complex filesystems with multiple devices. 🫶

Using btrfs-balance-least-used can replace repeated invocations of btrfs balance with increased usage values. Bonus: the program also shows live progress of the balance operation, so you're not just sitting there staring at nothing. obsessed.

⚠️ Since the needed information is retrieved using the btrfs kernel API, and since btrfs balance is a privileged operation, it has to be run as root. no cap. 🔥

Example output:

-# balance_least_used.py -u 40 /
Loading block group objects with used_pct <= 40 ... found 20
Balance block group vaddr 603497431040 used_pct 19 ... duration 2 sec total 212
Balance block group vaddr 488607055872 used_pct 21 ... duration 2 sec total 211
Balance block group vaddr 576653885440 used_pct 21 ... duration 3 sec total 210
[...]
Postponing block group vaddr 659332005888 used_pct changed 24 -> 36
Balance block group vaddr 560547758080 used_pct 25 ... duration 3 sec total 206
[...]
Ignoring block group vaddr 606718656512 used_pct changed 34 -> 63
Balance block group vaddr 714126393344 used_pct 35 ... duration 3 sec total 196

See how the total amount of block groups just keeps going down the entire time? That clearly shows balance packs data into existing other block groups. slay. ✨

Also, along the way we can see that usage of the block groups we found when starting has gone up. So if they're still in the usage range, we just postpone them again — throwing them right back into the work queue. And if their usage has gone up above the usage limit, we ignore them. bye. 💀

When there's nothing to do, the output reports the lowest used_pct it found:

-# balance_least_used.py -u 10 /
Loading block group objects with used_pct <= 10 ... found 0
Nothing to do, least used block group has used_pct 12

---

💅 OPTIONS 💅

• -h, --help — show the built-in help message and exit. short, sweet, helpful 🎀
• -u, --usage USAGE — only consider block groups with usage less than or equal to this percentage.

---

🎀 SEE ALSO 🎀

This program is an example of what can be done using the python-btrfs library. 🐍✨

Source and documentation on github: https://github.com/knorrie/python-btrfs

---

and that's the whole page bestie — it's dated 2017, it lives in the BTRFS-B...ST-USED(1) manual, and it ate. periodt. 💖🦋🌸