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.

SEE ALSO

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

                                               2017                              BTRFS-HEATMAP(1)