DOKK / manpages / debian 12 / btrfs-heatmap / btrfs-heatmap.1.en
BTRFS-HEATMAP(1) Btrfs Heatmap BTRFS-HEATMAP(1)

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

btrfs-heatmap [args] mountpoint

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.

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.

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

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.

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.

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

Show the built-in help message and exit.
Hilbert curve order (default: automatically chosen)
Image size (default: 10). Height/width is 2^size
Show disk usage sorted on dev_extent (physical, default) or chunk/stripe (virtual).
Instead of a filesystem overview, show extents in the block group starting at virtual address vaddr.
Space filling curve type or alternative. Default is hilbert.
Increase debug output verbosity. May be specified multiple times to increase verbosity. (-v, -vv, -vvv, etc...)
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.

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

2017