Using --filemap, it is possible to create regions that correspond
to the extents of a file in the file system. This allows IO
statistics to be monitored on a per-file basis, for example to
observe large database files, virtual machine images, or other
files of interest.
To be able to use file mapping, the file must be backed by a
device-mapper device, and in a file system that supports the
FIEMAP ioctl (and which returns data describing the physical
location of extents). This currently includes xfs(5) and ext4(5).
By default the regions making up a file are placed together in a
group, and the group alias is set to the basename(3) of the file.
This allows statistics to be reported for the file as a whole,
aggregating values for the regions making up the group. To see
only the whole file (group) when using the list and report
commands, use --group.
Since it is possible for the file to change after the initial
group of regions is created, the update_filemap command, and
dmfilemapd daemon are provided to update file mapped groups
either manually or automatically.
File follow modes
The file map monitoring daemon can monitor files in two distinct
ways: follow-inode mode, and follow-path mode.
The mode affects the behaviour of the daemon when a file under
monitoring is renamed or unlinked, and the conditions which cause
the daemon to terminate.
If follow-inode mode is used, the daemon will hold the file open,
and continue to update regions from the same file descriptor.
This means that the mapping will follow rename, move (within the
same file system), and unlink operations. This mode is useful if
the file is expected to be moved, renamed, or unlinked while it
is being monitored.
In follow-inode mode, the daemon will exit once it detects that
the file has been unlinked and it is the last holder of a
reference to it.
If follow-path is used, the daemon will re-open the provided path
on each monitoring iteration. This means that the group will be
updated to reflect a new file being moved to the same path as the
original file. This mode is useful for files that are expected to
be updated via unlink and rename.
In follow-path mode, the daemon will exit if the file is removed
and not replaced within a brief tolerance interval (one second).
To stop the daemon, delete the group containing the mapped
regions: the daemon will automatically shut down.
The daemon can also be safely killed at any time and the group
kept: if the file is still being allocated the mapping will
become progressively out-of-date as extents are added and removed
(in this case the daemon can be re-started or the group updated
manually with the update_filemap command).
See the create command and --filemap, --follow, and --nomonitor
options for further information.
Limitations
The daemon attempts to maintain good synchronisation between the
file extents and the regions contained in the group, however,
since it can only react to new allocations once they have been
written, there are inevitably some IO events that cannot be
counted when a file is growing, particularly if the file is being
extended by a single thread writing beyond end-of-file (for
example, the dd program).
There is a further loss of events in that there is currently no
way to atomically resize a dmstats region and preserve its
current counter values. This affects files when they grow by
extending the final extent, rather than allocating a new extent:
any events that had accumulated in the region between any prior
operation and the resize are lost.
File mapping is currently most effective in cases where the
majority of IO does not trigger extent allocation. Future updates
may address these limitations when kernel support is available.
