> ## Documentation Index > Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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`](https://filetrace.mintlify.site/cli/inspect) takes, and `--group-by` merges flows into totals per process, remote address, port or protocol. ## Usage ```bash theme={null} filetrace flows [options] ``` ## What it shows ```bash theme={null} sudo filetrace flows --limit 8 ``` ```text theme={null} 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: ```bash theme={null} sudo filetrace flows --group-by remote ``` ```text theme={null} 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//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](https://filetrace.mintlify.site/cli/filters.md) and [output formats](https://filetrace.mintlify.site/cli/output-formats.md). ## Examples ```bash theme={null} 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: ```bash theme={null} sudo filetrace flows --json --limit 2 ``` ```json theme={null} [ {"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`](https://filetrace.mintlify.site/cli/top) ranks remote addresses the same way as `--group-by remote`, and [`inspect ip`](https://filetrace.mintlify.site/cli/inspect) 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 | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.