.TH fatrace 8 "August 20, 2020" "Martin Pitt"

.SH NAME

fatrace \- report system wide file access events

.SH SYNOPSIS

.B fatrace
[
.I OPTIONS
]

.SH DESCRIPTION

.B 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.

.SH 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

.RS 4
rsyslogd(875): W /var/log/auth.log
.br
compiz(1971): O device 8:2 inode 658203
.RE

In text format, the line has the following fields:

.IP \(bu 2
The current time, if you specify the \fB\-\-timestamp\fR option.

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

.IP \(bu 2
Process ID

.IP \(bu 2
UID and GID, if you specify the \fB\-\-user\fR option. It is formatted as
"[uid:gid]".

.IP \(bu 2
Event type: \fBO\fRpen, \fBR\fRead, \fBW\fRrite, \fBC\fRlose. Events on
directories are \fB+\fR (create), \fBD\fRelete, \fB<\fR (moved from),
or \fB>\fR (moved to).
Combinations are possible, such as \fBCW\fR for closing a written file, or
\fB<>\fR for renaming a file within the same directory.

Directory events can only be detected on Linux 5.1 or higher.

.IP \(bu 2
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
.BR strace (1).

.IP \(bu 2
Path to executable, if you specify the \fB\-\-exe\fR option. This is read from
/proc/pid/exe.

.IP \(bu 2
Parent process information, if you specify the \fB\-\-parents\fR option. This
information includes, for each successive parent process, the process ID, the
process name, and the executable path if you specify the \fB\-\-exe\fR 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.

.RE

In JSONL format, the line is a JSON-encoded object with the following fields:

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

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

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

.TP
.B pid
Process ID

.TP
.B uid
UID, if you specify the \fB\-\-user\fR option.

.TP
.B gid
GID, if you specify the \fB\-\-user\fR option.

.TP
.B types
Event type: \fBO\fRpen, \fBR\fRead, \fBW\fRrite, \fBC\fRlose. Events on
directories are \fB+\fR (create), \fBD\fRelete, \fB<\fR (moved from),
or \fB>\fR (moved to).
Combinations are possible, such as \fBCW\fR for closing a written file, or
\fB<>\fR for renaming a file within the same directory.

Directory events can only be detected on Linux 5.1 or higher.

.TP
.B device
device ID in \fB{"major":major,"minor":minor}\fR form.

.TP
.B inode
The file inode.

.TP
.B path
The path to the affected file.

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

.TP
.B exe
The path to the executable, if you specify the \fB\-\-exe\fR option.

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

.TP
.B parents
An array of parent processes, if you specify the \fB\-\-parents\fR option. Each
item is an object containing \fBpid\fR, \fBcomm\fR, \fBcomm_raw\fR, \fBexe\fR
and \fBexe_raw\fR 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.

.SH OPTIONS

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

.TP
.B \-o \fIFILE\fR, \fB\-\-output=\fIFILE
Write events to given file instead of standard output.

.TP
.B \-s \fISECONDS\fR, \fB\-\-seconds=\fISECONDS
Stop after the given number of seconds.

.TP
.B \-t\fR, \fB\-\-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.

.TP
.B \-u\fR, \fB\-\-user
Add process user information to events.

.TP
.B \-p \fIPID\fR, \fB\-\-ignore\-pid=\fIPID
Ignore events for this process ID. Can be specified multiple times.

.TP
.B \-f \fITYPES\fR, \fB\-\-filter=\fITYPES
Show only the given event types. \fBTYPES\fR is a list of
.BR C ", " R ", " O ", " W ", " D ", " + ", or " <
with the above meanings. \fB<\fR and \fB>\fR both mean "move" and will always
enable both directions.

E. g. use \fB\-\-filter=OC\fR to only show open and close events.

.TP
.B \-C \fICOMMAND\fR, \fB\-\-command=\fICOMMAND
Show only events for this command.

.TP
.B \-j\fR, \fB\-\-json
Write events in JSONL format (see definition above).

.TP
.B \-P\fR, \fB\-\-parents
Print information about all parent processes.

.TP
.B \-e\fR, \fB\-\-exe
Print executable path.

.TP
.B \-h \fR, \fB\-\-help
Print help and exit.

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