fatrace(8)

NAME
fatrace - report system wide file access events

SYNOPSIS
fatrace [ OPTIONS ] [ -- ] [ DIR... ]

DESCRIPTION
fatrace reports file access events from all running processes. It does not report file access by fatrace itself, to avoid logging events caused by writing the output into a file. It also ignores events on virtual and kernel file systems such as sysfs, proc, and devtmpfs. Its main purpose is to find processes which keep waking up the disk unnecessarily and thus prevent some power saving. By default, events are reported to stdout. This will cause some loops if you run this tool in e. g. gnome-terminal, as this causes a disk access for every output line. To avoid this, redirect the output into a file.

OUTPUT FORMAT
There are two output formats. The default text format is easier on human eyes, while the JSONL format is more suitable for automatic processing. In text format, a typical event looks like
    rsyslogd(875): W /var/log/auth.log
    compiz(1971): O device 8:2 inode 658203
In text format, the line has the following fields:

•   The current time, if you specify the --timestamp option.

•   Process name. This is read from /proc/pid/comm, which might be abbreviated for long process names.

•   Process ID

•   UID and GID, if you specify the --user option. It is formatted as "[uid:gid]".

•   Event type: Open, Read, Write, Close. Events on directories are + (create), Delete, < (moved from), or > (moved to). Combinations are possible, such as CW for closing a written file, or <> for renaming a file within the same directory. Directory events can only be detected on Linux 5.1 or higher.

•   Affected file. In some cases the path and name cannot be determined, e. g. because it is a temporary file which is already deleted. In that case, it prints the devices' major and minor number and the inode number. To examine such a process in more detail, you should consider using strace(1).

•   Path to executable, if you specify the --exe option. This is read from /proc/pid/exe.

•   Parent process information, if you specify the --parents option. This information includes, for each successive parent process, the process ID, the process name, and the executable path if you specify the --exe option. If fatrace fails to determine some of this information, fields may be missing or the list may end before the process with ID 1.
In JSONL format, the line is a JSON-encoded object with the following fields:

timestamp
    The current time, if you specify the --timestamp option.

comm
    Process name. This is read from /proc/pid/comm, which might be abbreviated for long process names.

comm_raw
    The raw bytes of the process name, in case it is invalid UTF-8 or would require escaping.

pid Process ID

uid UID, if you specify the --user option.

gid GID, if you specify the --user option.

types
    Event type: Open, Read, Write, Close. Events on directories are + (create), Delete, < (moved from), or > (moved to). Combinations are possible, such as CW for closing a written file, or <> for renaming a file within the same directory. Directory events can only be detected on Linux 5.1 or higher.

device
    device ID in {"major":major,"minor":minor} form.

inode
    The file inode.

path
    The path to the affected file.

path_raw
    The raw bytes of the path to the affected file, in case it is invalid UTF-8 or would require escaping.

exe The path to the executable, if you specify the --exe option.

exe_raw
    The raw bytes of the executable path, in case it is not valid UTF-8 or would require escaping.

parents
    An array of parent processes, if you specify the --parents option. Each item is an object containing pid, comm, comm_raw, exe and exe_raw fields as appropriate. If fatrace fails to determine some of this information, fields may be missing or the list may end before the process with ID 1.

OPTIONS

-c, --current-mount
    Only record events on partition/mount of current directory. Without this option, all (real) partitions/mount points are being watched.

-o FILE, --output=FILE
    Write events to given file instead of standard output.

-s SECONDS, --seconds=SECONDS
    Stop after the given number of seconds.

-t, --timestamp
    Add timestamp to events. When this option is given once, the format will be a human readable hour:minute:second.microsecond; when given twice, the timestamp is printed as seconds/microseconds since the epoch.

-u, --user
    Add process user information to events.

-p PID, --ignore-pid=PID
    Ignore events for this process ID. Can be specified multiple times.

-f TYPES, --filter=TYPES
    Show only the given event types. TYPES is a list of C, R, O, W, D, +, <, or > with the above meanings. E. g. use --filter=OC to only show open and close events.

-C COMMAND, --command=COMMAND
    Show only events for this command.

-j, --json
    Write events in JSONL format (see definition above).

-P, --parents
    Print information about all parent processes.

-e, --exe
    Print executable path.

-d DIR, --dir=DIR
    Show only events where the affected file is directly under this directory. Can be specified multiple times to include events from several directories.

    This is not recursive. For example, -d /home/user will show events for /home/user/file but not for /home/user/subdir/file.

    DIRs can also be specified at the end of the command line, advisably preceded by the -- separator. As long as no directories will be created or moved under a subtree, it's possible to watch that subtree like so:

        fatrace -- $(find /path/to/subtree -type d)

    The attachment is to a directory inode, not the path. For example, this means that 1) If you move a watched directory while fatrace runs, you may receive events for a path that is not listed on the command line; 2) If you delete and recreate a watched directory you will no longer receive events.

-h , --help
    Print help and exit.

AUTHOR
fatrace is developed by Martin Pitt <martin@piware.de>.