filetrace flows: bytes per process and remote endpoint

Reference for filetrace flows: bytes per process, socket and remote endpoint, grouping by process, remote, port or protocol, options and exit codes.

filetrace flows lists the bytes exchanged per process, socket and remote endpoint, largest sender first. A flow is one process’s traffic with one remote endpoint on one socket, so a socket shared by several processes has a flow for each. The FLOW column gives the ID that inspect flow takes, and --group-by merges flows into totals per process, remote address, port or protocol.

​

Usage

filetrace flows [options]

​

What it shows

sudo filetrace flows --limit 8

PID   PROCESS         PROTOCOL  LOCAL              REMOTE                 SENT  RECEIVED   OUTBOUND  FLOW
1014  file-server     TCP       127.0.0.1:43090    127.0.0.1:34477     47.7 MB       0 B      0 B/s    12
1024  file-server     TCP       127.0.0.1:41814    127.0.0.1:51871     15.5 MB       0 B  4.02 MB/s     7
1018  file-server     TCP       127.0.0.1:60088    127.0.0.1:52535     11.4 MB       0 B      0 B/s     8
1016  file-server     TCP       [::1]:55572        [::1]:46399         7.63 MB       0 B      0 B/s     5
1020  file-server     TCP       127.0.0.1:49084    127.0.0.1:40477      195 KB       6 B      0 B/s     4
1022  file-server     UDP       0.0.0.0:49570      127.0.0.1:45789     48.8 KB       0 B      0 B/s     9
152   metrics-daemon  TCP       192.168.65.7:2376  192.168.65.1:25374    473 B       0 B      0 B/s     3
1021  file-server     TCP       127.0.0.1:40477    127.0.0.1:49084         6 B    195 KB      0 B/s    13

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.

Column	Meaning
PID, PROCESS	The process
PROTOCOL	TCP or UDP
LOCAL, REMOTE	The local and remote ends of the socket
SENT	Bytes the local socket accepted from this process for this endpoint, not bytes the remote end acknowledged
RECEIVED	Bytes the socket delivered to this process from this endpoint
OUTBOUND	The current sending rate
FLOW	The flow ID

​

Grouped flows

--group-by merges the flows that share a process name, a remote address, a remote port or a protocol, and prints the totals with the number of flows merged:

sudo filetrace flows --group-by remote

REMOTE           SENT  RECEIVED  FLOWS
127.0.0.1     74.9 MB   73.4 MB      9
::1           7.63 MB   5.92 MB      2
192.168.65.1    473 B       0 B      1
*                 0 B   48.8 KB      1

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.

The first column is PROCESS, REMOTE, REMOTE PORT or PROTO, depending on the key; * collects flows without a remote end. Groups are ordered by bytes sent, or by bytes received with --direction inbound, and --limit caps the number of groups. In machine-readable formats the first field is process, remote_ip, remote_port or protocol, followed by bytes_sent, bytes_received and flows.

​

Options

--group-by · string

Merge flows by process, remote, port or protocol.

--direction · string · default: "outbound"

Order by inbound (bytes received), outbound (bytes sent) or both (bytes sent and received together).

--active · boolean

Only flows with traffic within the last 5 seconds.

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

--remote · string

Only this remote address or CIDR network.

--local · string

Only this local address or CIDR network.

--port · number

Only this local or remote port.

--protocol · string · default: "all"

Only this protocol: tcp, udp or all.

--family · string

Only this address family: ipv4 or ipv6.

--min-bytes · string

At least this many bytes, sent and received together, such as 1KB, 100MB or 1GB.

--since · string

Only flows active at or after this time: a duration such as 10m, 1h or 7d, or an RFC 3339 timestamp.

--until · string

Only flows that started at or before this time.

--sort · string

outbound, inbound, bytes, time, pid, rate, duration or process. --sort and --direction set the same order; the one given last applies.

--resolve-hostnames · boolean

Show remote addresses by host name where a reverse DNS lookup finds one. The lookups tell the DNS resolver which addresses are being looked at.

--limit · number

Show at most this many rows.

--format · string · default: "table"

table, json, jsonl, csv or quiet. Quiet prints one flow ID per row.

--json · boolean

Short for --format json.

--jsonl · boolean

Short for --format jsonl.

--output · string

Write to this file instead of standard output.

Byte counts cover a record’s whole observed lifetime; --since and --until select which records are listed. See filters and output formats.

​

Examples

filetrace flows --group-by remote
filetrace flows --pid 1842 --min-bytes 10MB
filetrace flows --direction inbound --since 1h

Machine-readable output adds the socket ID, the current rates, the number of send and receive operations, and when the flow was first and last seen:

sudo filetrace flows --json --limit 2

[
 {"flow_id":12,"socket_id":3,"protocol":"tcp","pid":1014,"process":"file-server","local_ip":"127.0.0.1","local_port":43090,"remote_ip":"127.0.0.1","remote_port":34477,"bytes_sent":50000000,"bytes_received":0,"bytes_sent_per_second":0,"bytes_received_per_second":0,"send_operations":763,"receive_operations":0,"first_seen":"2026-11-11T20:07:56.059Z","last_seen":"2026-11-11T20:07:56.063Z"},
 {"flow_id":7,"socket_id":16,"protocol":"tcp","pid":1024,"process":"file-server","local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871,"bytes_sent":16250000,"bytes_received":0,"bytes_sent_per_second":4209187,"bytes_received_per_second":0,"send_operations":260,"receive_operations":0,"first_seen":"2026-11-11T20:07:56.193Z","last_seen":"2026-11-11T20:07:59.514Z"}
]

top destinations ranks remote addresses the same way as --group-by remote, and inspect ip shows one address or network with its processes and the files sent to it.

​

Exit codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Permission denied: the agent socket is not accessible to this user
4	No agent is running
5	Unsupported platform or capability
6	The configuration file cannot be read or is invalid
9	Partial results: events were lost in the queried time range