Filter options of the listing commands

The filter options that the listing commands share: value syntax for times, sizes, addresses, wildcards and regular expressions, and which command takes which.

The listing commands (watch, files, transfers, processes, connections, flows, top, events and inspect) share one set of filter options. This page describes the syntax of each value, how filters combine, how --since and --until select records, and which command accepts which filter.

​

How filters combine

Every filter you give narrows the result: a record is listed only if it matches all of them. Giving the same option twice keeps the last value. --path and --path-regex set the same pattern, so the one given last applies.

Each command accepts only the filters that apply to what it lists. Any other option is reported as an unknown argument, and the command exits with 2.

sudo filetrace files --process nginx --remote 203.0.113.0/24 --since 1h --min-bytes 100MB

​

Value syntax

​

Times

--since and --until take either a duration back from now or an RFC 3339 timestamp.

Form	Examples	Notes
Duration	500ms, 30s, 10m, 1h, 7d, 1.5h	A number with one of the units ms, s, m, h, d. The unit is required.
RFC 3339 timestamp	2026-11-11T20:00:00Z, 2026-11-11T21:00:00.250+01:00	A time zone, Z or an offset, is required. A space may replace the T if you quote the value.

History starts when the agent starts, so a time before that selects everything the agent has.

​

Sizes

--min-bytes and --min-size take a number with an optional unit: B, K or KB, M or MB, G or GB, T or TB, in upper or lower case. Units are powers of 1024, so 1KB is 1024 bytes and 100MB is 104857600 bytes. A number without a unit counts bytes, and a fraction such as 1.5GB is accepted.

​

Addresses and ports

--remote and --local take an IPv4 or IPv6 address, or a network in CIDR notation:

sudo filetrace files --remote 203.0.113.42
sudo filetrace files --remote 203.0.113.0/24
sudo filetrace connections --local 2001:db8::/32

An address without a prefix length matches that address only. An IPv4 network never matches an IPv6 endpoint, and the other way round.

--port takes a number from 1 to 65535 and matches records whose local or remote port is that number.

​

Process names

--process, and its alias --name, match the process name shown in the PROCESS column: the kernel’s command name, which holds at most 15 characters. A * matches any run of characters; without one, the name must match exactly, including case.

sudo filetrace processes --process 'python*'

​

Paths

--path, and its alias --file, match the whole path of a file. A * matches any run of characters, / included, so /data/* also matches files in the subdirectories of /data. Without a *, the path must match exactly. Quote patterns so that the shell does not expand them:

sudo filetrace files --path '/data/*' --since 1h
sudo filetrace files --path '*.csv'

​

Regular expressions

--path-regex takes a POSIX extended regular expression. It matches if it occurs anywhere in the path; anchor it with ^ and $ to match the whole path. An invalid expression is reported and the command exits with 2.

sudo filetrace files --path-regex '^/srv/(exports|backups)/.*\.tar\.gz$'

​

Users, cgroups and namespaces

Option	Value
--user	A user name or a numeric user ID
--cgroup	A numeric cgroup ID, or a directory of the cgroup tree, whose inode number is its ID
--namespace	The inode number of a network, PID or mount namespace, as ls -Li /proc/<pid>/ns shows it

These filters select processes, and the sockets, flows and transfers of those processes. Machine-readable output of processes carries the matching values as cgroup_id, pid_namespace, mount_namespace and network_namespace.

​

Keywords

Option	Values
--protocol	tcp, udp or all (default all)
--family	ipv4 or ipv6; matches when either end of the socket has that family
--confidence	exact, strong, inferred, unknown or all. unknown lists sent bytes that no file accounts for. No probe produces strong.
--method	sendfile or read-write. splice, mmap and io_uring are accepted, but this build does not observe them: the command says so and exits with 5 instead of printing an empty list.
--state	connecting, established, listening, closed for TCP sockets; active and idle for UDP sockets, which turn idle after 30 seconds without traffic

See file attribution and confidence for what the confidence levels and methods rest on.

​

Time ranges and activity

--since selects records that were active at or after the given time; --until selects records that started at or before it. Together they select the records whose observed lifetime overlaps the range.

--since and --until choose which records are listed, not which bytes are counted. Byte counts always cover a record’s whole observed lifetime. A transfer that started two hours ago and is still running shows all of its bytes with --since 10m.

In events, every record is one point in time, and the range selects the events made within it.

If the agent lost events within the queried range, the command still prints its result, warns on standard error and exits with 9.

The activity options refer to the last few seconds:

Option	Commands	Selects
--active	files, transfers	Transfers updated within the last 5 seconds
--completed	files, transfers	Transfers not updated within the last 5 seconds
--active	flows	Flows with traffic within the last 5 seconds
--active	connections	Sockets that are open: not closed and not idle
--active-only	processes	Running processes with at least one open connection

--active and --completed together select everything.

​

Which commands take which filters

Filter	watch	files	transfers	processes	connections	flows	top	events	inspect
--pid	yes	yes	yes	yes	yes	yes	yes	yes
--process, --name	yes	yes	yes	yes	yes	yes	yes	yes
--user	yes	yes	yes	yes	yes	yes
--cgroup	yes	yes	yes	yes	yes	yes
--namespace	yes	yes	yes	yes	yes	yes
--path, --file	yes	yes	yes					yes
--path-regex		yes	yes
--min-size		yes	yes
--remote	yes	yes	yes		yes	yes		yes
--local		yes	yes		yes	yes		yes
--port		yes	yes		yes	yes		yes
--protocol	yes	yes	yes		yes	yes	yes	yes
--family					yes	yes		yes
--state					yes
--method		yes	yes
--confidence	yes	yes	yes
--min-bytes	yes	yes	yes			yes
--deleted		yes	yes
--active		yes	yes		yes	yes
--completed		yes	yes
--since		yes	yes	yes	yes	yes	yes	yes	yes
--until		yes	yes	yes	yes	yes	yes	yes
--sort	yes	yes	yes	yes	yes	yes
--limit	yes	yes	yes	yes	yes	yes	yes	yes	yes
--resolve-hostnames	yes	yes	yes		yes	yes			yes

Notes on the table:

• In top, --protocol applies to the files, destinations and connections subjects; top processes, the default, does not accept it.
• In watch, the process filters (--pid, --process, --user, --cgroup, --namespace) apply to every view; watch lists which view each of the others applies to.
• In events, --path matches only file events (file_seen and file_transfer), and the network filters match only events that concern a socket.
• In inspect, the target itself (a path, PID, socket ID, flow ID or address) does the selecting; --since narrows the history.

​

Sorting and limits

--sort orders the rows by one key. The keys each command accepts:

Command	Keys	Default order
files, transfers	bytes, time, pid, rate, duration, process, file	Most recently active first
processes	outbound, inbound, connections, bytes, time, pid, process	Outbound rate, then bytes sent
connections	outbound, inbound, bytes, time, pid, rate, duration, process	Most recently active first
flows	outbound, inbound, bytes, time, pid, rate, duration, process	Bytes sent, largest first
watch	bytes, rate, process, file	Current rate

Numeric keys sort largest first, except pid, which sorts in ascending order. process and file sort by name or path in ascending order. bytes is the bytes sent for transfers and the bytes sent and received together for processes, connections and flows.

--limit takes a positive number and caps the rows; in inspect it caps every list in the report. See each command’s page for its default.

​

Related pages

• Output formats describes --format, --json, --jsonl and --output.
• Records and identifiers explains what a process, socket, flow and transfer record is.