The btrfs heatmap script creates a visualization of how a btrfs filesystem is using the underlying disk space of the block devices that are added to it.
| 238GiB file system |
|---|
 |
This picture shows the 238GiB filesystem in my computer at work. It was
generated using the command btrfs-heatmap --size 9 /, resulting in a 512x512
pixel png. The black parts are unallocated disk space. Raw disk space that is
allocated to be used for data (white), metadata (blue) or system (red) gets
brighter if the fill factor of block groups is higher.
Well, first install the program. It's probably available as package 'btrfs-heatmap' in your favourite Linux distro.
When pointing btrfs-heatmap to a mounted btrfs filesystem location, it will ask the linux kernel for usage information and build a png picture reflecting that low level information. Because the needed information is retrieved using the btrfs kernel API, it has to be run as root user:
-$ sudo btrfs-heatmap /mountpoint
The filename of the png picture is a combination of the filesystem ID and a timestamp by default, so that if you create multiple of them, they nicely pile up as input for creating a timelapse video.
Creating multiple ones is as easy as doing watch 'btrfs-heatmap /mountpoint'
Yes! For this, output to stdout can be used. When using a dash as output
filename (-o -), the resulting png data is written to stdout directly, which
can be connected to an image viewer like catimg for displaying the image
right away in a terminal screen using ansi color codes. For a pop up window, a
program like feh can be used.
A typical use case for using this functionality and catimg is to conveniently
view results on a remote server without having to copy resulting png files
around.
By default, the ordering inside the picture is based on a Hilbert Curve. The lowest physical address of the block devices is located in the bottom left corner. From there it walks up, to the right and down again.
| Hilbert Curve | Example Image |
|---|---|
 |
 |
The picture that is generated by default shows the physical address space of a filesystem, by walking all dev extents of all devices in the filesystem using the search ioctl and concatenating all information into a single big image. The usage values are computed by looking up usage counters in the block group items from the extent tree.
It's also possible to have the picture sorted by btrfs virtual address space instead, or to create pictures of the contents of block groups, on extent level. For more information, see links to additional documentation below.
Here's an example command to create an mp4 video out of all the png files if you create multiple ones over time:
ffmpeg -framerate 2 -pattern_type glob -i '*.png' -c:v libx264 -r 25 -pix_fmt yuv420p btrfs-heatmap.mp4
By varying the -framerate option, you can make the video go faster or slower.
Another option is to create an animated gif. By varying the -delay option,
you change the speed.
convert -layers optimize-frame -loop 0 -delay 20 *.png btrfs-heatmap.gif
The next picture is an animated gif of running btrfs balance on the data of
the filesystem which the first picture was also taken of. You can see how all
free space is defragmented by packing data together:
| btrfs balance |
|---|
 |
- The built-in
--helpoption will show all functionality that is available through the command line. - Different ways to walk the pixel grid: Hilbert, Snake, Linear.
- Sorting the picture on virtual instead of physical address space.
- Extent level pictures show detailed usage of the virtual address space inside block groups.
- By scripting btrfs-heatmap it's possible to make pictures of single devices, or any combination of block groups.
Let me know if this program was useful for you, or if you have brilliant ideas about how to improve it.
You can reach me on IRC in #btrfs on Freenode (I'm Knorrie), use the github issue system or send me an email on hans@knorrie.org