fatrace(8)

🌸 NAME 🌸

okay so this is the System Manager's Manual page (section 8) for fatrace 💅 — the tool that reports system wide file access events. that's it, that's the whole job, and it eats. 🔥

---

✨ SYNOPSIS ✨

fatrace [ OPTIONS ]

---

🦋 DESCRIPTION 🦋

bestie. fatrace reports file access events from all running processes. every single one. no cap. 👑

two things it deliberately does not do, and this is on purpose:

• It does not report file access by fatrace itself, because that would mean logging the events caused by writing its own output into a file, and we are not doing feedback loops today 🙈
• 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. it's the "who is spinning up my disk at 3am" detective 🕵️ and honestly? iconic.

By default, events are reported to stdout. ⚠️ heads up though: 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. periodt.

---

🌈 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. pick your fighter 💖

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

🧾 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. < and > both mean "move" and will always enable both directions.

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.
• -h, --help — Print help and exit.

---

👑 AUTHOR 👑

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

---

and that's the whole page, bestie 🫶 — penned by Martin Pitt on August 20, 2020, and it's giving System Manager's Manual energy from start to finish. go find out who's touching your files. mwah. 💋✨