NAME

       btrfs-balance-least-used - Feed least used data block groups to btrfs balance first.

SYNOPSIS

       btrfs-balance-least-used [args] mountpoint

DESCRIPTION

       The btrfs-balance-least-used program is an example of a user space defined way to
       implement btrfs balance filters. It looks at the data block groups present in the file
       system and asks btrfs to empty them in order of actual usage, lowest usage first.

       In most cases (when not being in the process of conversion between block group profiles)
       this will result in the most optimal and quickest way to reclaim physical disk space
       because data will be rewritten into empty space into already existing block groups.

       What btrfs balance effectively does is just taking the data and feeding it back to the
       allocator of the filesystem as new writes, blacklisting their current location.
       Implementing user space balance filters can result in a higly optimized workflow to
       reclaim physical space, or to minimize the amount of data that has to be rewritten to
       rebalance complex filesystems with multiple devices.

       Usage of btrfs-balance-least-used can replace repeated invocations of btrfs balance with
       increased usage values. Additionally, the program will show live progress of the balance
       operation.

       Because the needed information is retrieved using the btrfs kernel API, and because btrfs
       balance is a privileged operation, it has to be run as root.

       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

       This clearly shows that balance packs data into existing other block groups, since the
       total amount of block groups is going down all the time.

       Also, along the way we see that usage of 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 back
       into the work queue. If their usage has gone up above the usage limit, ignore them.

       When there's nothing to do, the output reports the lowest used_pct 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.

       -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

                                               2017                   BTRFS-BALANCE-LEAST-USED(1)