BTRFS-HEATMAP(1)

📦 version 9, in arch rolling, debian bookworm, debian trixie, fedora 43, fedora 44, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 BTRFS-HEATMAP 💖

okay bestie, so this is the manual page for btrfs-heatmap, section 1 of the manual (that's the BTRFS-HEATMAP(1) bit if you were wondering why the vibes were so official). it's a script. it makes pictures. the pictures are of your filesystem. let's get into it 💅

✨ NAME ✨

btrfs-heatmap — visualize the layout of data on your btrfs filesystem

like... it makes a picture of where your data literally is on the disk. it's giving map, it's giving heat, it's giving art gallery but for block devices 🎨

🦋 SYNOPSIS 🦋

btrfs-heatmap [args] mountpoint

that's it. you give it args (optional, queen) and a mountpoint (not optional, bestie). no mountpoint no picture. periodt.

🌸 DESCRIPTION 🌸

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.

so basically it looks at your btrfs filesystem, looks at all the block devices chillin' underneath it, and is like "here's how you're using the space, in one (1) image." iconic behavior honestly.

The resulting PNG image will show unallocated disk space as black pixels. 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.

ok so read that again because the colors are doing a LOT of work here:

  • black = unallocated disk space. nobody's using it. it's napping.
  • white = raw disk space allocated for data
  • blue = raw disk space allocated for metadata
  • red = raw disk space allocated for system
  • and the brighter the color gets, the higher the fill factor of those block groups is. so bright = packed. dim = mostly empty. it's a vibe check for your block groups fr fr ✨

Because the needed information is retrieved using the btrfs kernel API, it has to be run as root.

⚠️ no cap, you literally cannot run this as a normal user. kernel API says root only. sorry bestie, sudo up 💀

By default, the filename of the PNG image is a combination of the filesystem ID and a timestamp, so that if you create multiple of them, they nicely pile up as input for creating a timelapse video.

so it names the file for you (filesystem ID + timestamp) and if you keep running it, you get a whole lil collection of images that you can stitch into a timelapse. main character energy for real 🎬✨

🧚 About the ordering of data in the picture 🧚

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.

so bottom-left corner = lowest physical address. then it does the little curvy walk: up, right, down. that's the Hilbert curve, it's iconic, it's math, it's slay 🌀

👑 In btrfs technical terms speaking... 👑

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.

ngl that's a lot of words so here's the translation: it walks every dev extent of every device (using the search ioctl), smashes them all into one big image, and figures out the usage numbers by looking up usage counters in the block group items from the extent tree. that's the physical-address-space default picture. 💅

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 by using the --blockgroup option.

so you got options (literally): sort by virtual address space instead, OR zoom all the way into block group contents at extent level with --blockgroup. pick your fighter 🫶

💅 OPTIONS 💅

  • -h, --help — Show the built-in help message and exit.
  • --order order — Hilbert curve order (default: automatically chosen)
  • --size size — Image size (default: 10). Height/width is 2^size
  • --sort {physical|virtual} — Show disk usage sorted on dev_extent (physical, default) or chunk/stripe (virtual).
  • --blockgroup vaddr — Instead of a filesystem overview, show extents in the block group starting at virtual address vaddr.
  • --curve {hilbert|linear|snake} — Space filling curve type or alternative. Default is hilbert.
  • -v, --verbose — Increase debug output verbosity. May be specified multiple times to increase verbosity. (-v, -vv, -vvv, etc...)
  • -o, --output {filename|directory|-} — Output png file name or directory (default: filename automatically chosen). When using the special value '-' as file, the png data will be written to the standard output instead of to a file on disk, so it can be directly viewed by an image viewer, e.g. with catimg.

🎀 SEE ALSO 🎀

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

ok that's the whole page bestie, go make some heatmaps, run it as root, and remember: -o - + catimg is the combo meal 🔥🐱

this manual page is dated 2017 and belongs to the BTRFS-HEATMAP(1) family — mwah, love that for us 💖

📦 where this page comes from