BTRFS\-HEATMAP

Section: Btrfs Heatmap (1)
Updated: 2017
Page Index

NAME

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

SYNOPSIS

btrfs-heatmap [args] mountpoint

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.

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.

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.

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.

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.

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.