filetrace watch: live view of file transfers

Reference for filetrace watch: the live dashboard with its views and keys, the —no-ui snapshot mode, foreground collection, options and exit codes.

filetrace watch shows what the machine is sending, live: the file transfers in progress with the process, the destination, the method and the current rate of each. On a terminal it draws a dashboard that refreshes every second and switches between files, processes and connections with single keys; otherwise it prints a snapshot per interval. When no agent is running, it collects in the foreground for as long as it runs.

​

Usage

filetrace watch [options]

​

The dashboard

sudo filetrace watch

FILETRACE  web-01 · Linux 6.8  LIVE

4             13            6.67 MB/s
Transfers     Processes     Outbound

ACTIVE FILE TRANSFERS
PROCESS      FILE                         DESTINATION    METHOD           RATE  CONFIDENCE
nginx 1245   /var/www/stream.bin          203.0.113.25   sendfile    6.67 MB/s  EXACT
nginx 1245   /var/www/video.mp4           198.51.100.10  sendfile        0 B/s  EXACT
python 892   /data/export/customers.csv   203.0.113.50   read-write      0 B/s  INFERRED

● EXACT: 2   ● INFERRED: 1   LOST: 0
[F] Files  [P] Processes  [N] Network  [Space] Pause  [?] Help  [Q] Quit

From top to bottom:

• The header names the host, the system and its kernel version, and the state: LIVE, PAUSED while refreshing is paused, or DEGRADED when the collector has lost events recently.
• The counters give the transfers in progress, the active processes and the outbound rate of the whole machine. With --direction inbound the inbound rate replaces the outbound one; with --direction both both are shown.
• The view: file transfers, processes or connections, chosen with the keys below.
• The confidence line counts the transfers in progress by confidence, and the events the collector has lost since it started.
• The key line shows the keys, with the current view highlighted.

A transfer is in progress if it was updated within the last 5 seconds. Rates are bytes per second over the last one to two seconds, counted where the local socket accepts or delivers the bytes.

​

Views

View	Columns
Files: ACTIVE FILE TRANSFERS	PROCESS (name and PID), FILE, DESTINATION, METHOD, RATE, CONFIDENCE
Processes: PROCESSES	PID, PROCESS, OUTBOUND, FILES, CONNECTIONS, SENT
Network: CONNECTIONS	PID, PROCESS, PROTOCOL, LOCAL, REMOTE, OUTBOUND, INBOUND

In the files view, a path too long for the terminal is shortened at its start, with ..., so that the file name stays visible. A * after a confidence level marks a transfer during which events were lost. The processes view ranks processes by the rate they send at; with --direction inbound it shows INBOUND and RECEIVED instead of OUTBOUND and SENT, and with --direction both it shows OUTBOUND, FILES, CONNECTIONS, INBOUND and TOTAL. The network view lists open connections.

​

Keys

Key	Action
f	File transfers in progress
p	Processes, by the rate they send at
n	Network: open connections
space	Pause or resume refreshing
?	Show or hide the help screen, which also explains the columns
q	Quit; Ctrl-C also quits

The keys work in upper case too, and h also toggles the help screen.

​

Snapshots without the dashboard

With --no-ui, or whenever standard output or standard input is not a terminal, watch prints a snapshot per interval instead of a dashboard, so you can log activity to a file:

sudo filetrace watch --no-ui > activity.log

Each snapshot starts with a line holding the local time, then shows the counters, the file transfers in progress and the processes, and ends with the confidence line. It has no network view and no key line, and each table holds 10 rows unless --limit says otherwise:

sudo filetrace watch --no-ui --limit 5

--- 2026-11-11 20:07:58 ---
FILETRACE  web-01 · Linux 7.0  LIVE

4             13            4.18 MB/s
Transfers     Processes     Outbound

ACTIVE FILE TRANSFERS
PROCESS           FILE                                   DESTINATION  METHOD           RATE  CONFIDENCE
file-server 1024  /srv/export/media/files/stream.bin     127.0.0.1    sendfile    4.18 MB/s  EXACT
file-server 1016  /srv/export/media/files/backup.tar.gz  ::1          sendfile        0 B/s  EXACT
file-server 1018  /srv/export/media/files/customers.csv  127.0.0.1    read-write      0 B/s  INFERRED
file-server 1014  /srv/export/media/files/video.mp4      127.0.0.1    sendfile        0 B/s  EXACT

PROCESSES
PID   PROCESS       OUTBOUND  FILES  CONNECTIONS     SENT
1024  file-server  4.18 MB/s      1            2  8.34 MB
1014  file-server      0 B/s      1            0  47.7 MB
1018  file-server      0 B/s      1            0  11.4 MB
1016  file-server      0 B/s      1            0  7.63 MB
1020  file-server      0 B/s      0            0   195 KB

● EXACT: 3   ● INFERRED: 1   LOST: 0

[output] timestamps = false in the configuration leaves out the time line.

​

Without an agent

When no agent is serving the socket, watch starts a collector in the foreground and says so on standard error:

The Filetrace agent is not running; monitoring in the foreground for this
session. Only activity from now on is shown.

The collector needs the same privileges as the agent, uses the [agent] settings of the configuration file, exports nothing and stops when watch ends. If the agent is running but its socket is not accessible to your user, watch reports Permission denied instead; run it with sudo.

​

How the filters apply

Filter	Files view	Processes view	Network view
--pid, --process, --user, --cgroup, --namespace	yes	yes	yes
--path, --confidence, --sort	yes
--remote, --protocol	yes		yes
--min-bytes	yes	yes

--sort orders the transfers and defaults to rate.

​

Options

--interval · string · default: "1s"

Refresh interval, such as 500ms or 2s. The shortest is 100 ms.

--direction · string · default: "outbound"

Traffic that ranks processes and connections: outbound, inbound or both.

--no-ui · boolean

Print a snapshot per interval instead of a dashboard. This is the default when output is not a terminal.

--pid · number

Only this process.

--process · string

Only processes with this name. * matches any run of characters. Alias: --name.

--user · string

Only processes of this user, by name or numeric ID.

--cgroup · string

Only processes in this cgroup, by numeric ID or cgroup directory.

--namespace · number

Only processes in this network, PID or mount namespace, given as the inode number that ls -Li /proc/<pid>/ns shows.

--path · string

Only this file. * matches any run of characters, / included. Alias: --file.

--remote · string

Only this remote address or CIDR network.

--protocol · string · default: "all"

Only this protocol: tcp, udp or all.

--confidence · string

exact, strong, inferred, unknown or all.

--min-bytes · string

At least this many bytes, such as 1KB, 100MB or 1GB.

--sort · string · default: "rate"

Order of the transfers: bytes, rate, process or file.

--resolve-hostnames · boolean

Show the destinations of the files view by host name where a reverse DNS lookup finds one. A name appears on the refresh after its lookup finishes. The lookups tell the DNS resolver which addresses are being looked at.

--limit · number

Rows per table. By default, as many as fit on the terminal, or 10 with --no-ui.

Filters describes the value syntax. Watch transfers live shows how to use the view day to day.

​

Examples

sudo filetrace watch
sudo filetrace watch --remote 203.0.113.0/24 --confidence exact
sudo filetrace watch --sort bytes --min-bytes 1MB --interval 2s
sudo filetrace watch --no-ui > activity.log

​

Exit codes

Code	Meaning
0	Quit normally
1	General error
2	Invalid arguments
3	Permission denied: the agent socket is not accessible, or the foreground collector lacks privileges
5	Unsupported platform or capability
6	The configuration file cannot be read or is invalid
9	The collector had lost events by the time watch ended