> ## 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 events: the agent's records, past and live > Reference for filetrace events: event types, the text, raw and JSON formats, following events live, the bounded event log, options and exit codes. `filetrace events` prints the agent's records in the order they were made, oldest first: process, socket, network and transfer events, the raw material that the other commands add up. Past events come from a log kept in memory; `--follow` prints new events as they happen. ## Usage ```bash theme={null} filetrace events [options] ``` ## Event types | Type | Recorded when | | - | - | | `process_exec`, `process_fork`, `process_exit` | A process runs a program, is created or exits | | `socket_connect`, `socket_listen`, `socket_established`, `socket_close` | A socket connects, listens, is established or closes | | `file_seen` | A file was read or sent for the first time | | `network_send` | Bytes a socket accepted | | `network_receive` | Bytes a socket delivered | | `file_transfer` | File bytes attributed to a socket, with the method and the confidence of the association so far | | `event_loss` | Events the collector could not record | Byte counts are gathered in the kernel and collected several times a second, so a `network_send`, `network_receive` or `file_transfer` event carries the bytes of one such interval, not of one system call. File opens and individual system calls are not recorded. [Event types](https://filetrace.mintlify.site/reference/event-types.md) lists the fields of each. ## What it shows ```bash theme={null} sudo filetrace events --type file_transfer --limit 4 ``` ```text theme={null} 20:07:58.732 FILE_TRANSFER pid=1024 process=file-server file=/srv/export/media/files/stream.bin inode=626330 socket=16 remote=127.0.0.1:51871 bytes=1250000 method=sendfile confidence=exact 20:07:58.992 FILE_TRANSFER pid=1024 process=file-server file=/srv/export/media/files/stream.bin inode=626330 socket=16 remote=127.0.0.1:51871 bytes=1250000 method=sendfile confidence=exact 20:07:59.254 FILE_TRANSFER pid=1024 process=file-server file=/srv/export/media/files/stream.bin inode=626330 socket=16 remote=127.0.0.1:51871 bytes=1250000 method=sendfile confidence=exact 20:07:59.515 FILE_TRANSFER pid=1024 process=file-server file=/srv/export/media/files/stream.bin inode=626330 socket=16 remote=127.0.0.1:51871 bytes=1250000 method=sendfile confidence=exact 4 events. The event log reaches back to 2026-11-11 20:07:55; it is kept in memory and holds only the most recent events. ``` Each event starts with its local time to the millisecond and its type, followed by one `key=value` line per field that applies: | Fields | Events | | - | - | | `pid`, `process` | Every event that concerns a process | | `ppid`, `executable` | Process events that carry the program path | | `exit_status` or `signal` | `process_exit` | | `file`, `inode`; `device` and `size` for `file_seen`; `deleted=yes` | File events | | `socket`, `remote`; `protocol` and `local` except for `file_transfer` | Events that concern a socket | | `bytes` | `network_send`, `network_receive`, `file_transfer` | | `bytes_read`, `method`, `confidence` | `file_transfer`; `bytes_read` for `read-write` only, and `confidence=pending` while the association is below the reporting thresholds | | `events`, `cause` | `event_loss` | The last line counts the events printed and says how far back the event log reaches. ## The event log Past events come from a log of bounded size kept in the agent's memory: 1 MB by default, set with `--event-log-size` of [`filetrace-agent`](https://filetrace.mintlify.site/cli/filetrace-agent) or `[agent] event_log_size` in the configuration. It holds only the most recent events and starts empty when the agent starts. Transfer, network and process events have separate shares of the log, so a flood of one kind does not push out the others; when a share has discarded events, the log reaches back only to its oldest remaining one. ## Following events `--follow` (or `-f`) keeps printing events as they happen until you press Ctrl-C. It starts at the present, unless `--since` or `--limit` asks for past events first: ```bash theme={null} sudo filetrace events --follow --type file_transfer ``` Without a running agent, `--follow` starts a collector in the foreground for as long as it runs. This needs the same privileges as the agent and shows only activity from the moment it starts. A followed stream ends without the summary line. If a follower reads more slowly than events arrive and falls more than 1 MB behind, the agent skips events for it and then sends an `event_loss` event whose cause is `this reader fell behind`. ## Raw output `--raw` prints one line per event with every field unformatted, in a fixed order, with the free text last because it may contain spaces: ```bash theme={null} sudo filetrace events --raw --limit 6 ``` ```text theme={null} seq=158 time_ns=1794427679254230336 type=network_send pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=0 inode=0 file_size=0 method=0 confidence=255 loss_kind=0 flags=0 text= seq=159 time_ns=1794427679254613086 type=network_receive pid=1026 ppid=1024 uid=0 comm=file-server exit_status=0 socket=17 protocol=6 local_ip=127.0.0.1 local_port=51871 remote_ip=127.0.0.1 remote_port=41814 bytes=1250000 bytes_read=0 device=0 inode=0 file_size=0 method=0 confidence=255 loss_kind=0 flags=0 text= seq=160 time_ns=1794427679254613086 type=file_transfer pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=63 inode=626330 file_size=40000000 method=1 confidence=3 loss_kind=0 flags=2 text=/srv/export/media/files/stream.bin seq=161 time_ns=1794427679515076878 type=network_receive pid=1026 ppid=1024 uid=0 comm=file-server exit_status=0 socket=17 protocol=6 local_ip=127.0.0.1 local_port=51871 remote_ip=127.0.0.1 remote_port=41814 bytes=1250000 bytes_read=0 device=0 inode=0 file_size=0 method=0 confidence=255 loss_kind=0 flags=0 text= seq=162 time_ns=1794427679515076878 type=network_send pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=0 inode=0 file_size=0 method=0 confidence=255 loss_kind=0 flags=0 text= seq=163 time_ns=1794427679515076878 type=file_transfer pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=63 inode=626330 file_size=40000000 method=1 confidence=3 loss_kind=0 flags=2 text=/srv/export/media/files/stream.bin ``` `time_ns` is in nanoseconds since the Unix epoch, `protocol` is the IP protocol number, and `method`, `confidence`, `loss_kind` and `flags` are the internal numeric codes. `--raw` is a format of its own and cannot be combined with `--format`, `--json` or `--jsonl`. ## JSON output In JSON and JSON Lines, each event has its type, an RFC 3339 timestamp and a sequence number, and groups its fields under `process`, `file`, `network`, `transfer` and `loss`, with the same names as the transfer records of [`files`](https://filetrace.mintlify.site/cli/files): ```bash theme={null} sudo filetrace events --jsonl --limit 12 ``` ```json theme={null} {"event":"network_send","timestamp":"2026-11-11T20:07:58.731Z","sequence":152,"process":{"pid":1024,"ppid":772,"name":"file-server"},"network":{"protocol":"tcp","socket_id":16,"local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871,"bytes_sent":1250000}} {"event":"network_receive","timestamp":"2026-11-11T20:07:58.732Z","sequence":153,"process":{"pid":1026,"ppid":1024,"name":"file-server"},"network":{"protocol":"tcp","socket_id":17,"local_ip":"127.0.0.1","local_port":51871,"remote_ip":"127.0.0.1","remote_port":41814,"bytes_received":1250000}} {"event":"file_transfer","timestamp":"2026-11-11T20:07:58.732Z","sequence":154,"process":{"pid":1024,"ppid":772,"name":"file-server"},"file":{"path":"/srv/export/media/files/stream.bin","inode":626330,"device":63,"size":40000000,"deleted":false},"network":{"protocol":"tcp","socket_id":16,"local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871},"transfer":{"method":"sendfile","bytes_sent":1250000,"confidence":"exact"}} ``` The first three of the twelve events are shown. Process events carry the program path and the exit status: ```bash theme={null} sudo filetrace events --type process_exec,process_exit --limit 4 --json ``` ```json theme={null} [ {"event":"process_exit","timestamp":"2026-11-11T20:07:58.190Z","sequence":140,"process":{"pid":1029,"ppid":1027,"name":"sed","executable":"/usr/bin/sed","exit_status":0}}, {"event":"process_exit","timestamp":"2026-11-11T20:07:58.190Z","sequence":141,"process":{"pid":1027,"ppid":772,"name":"sh","exit_status":0}}, {"event":"process_exec","timestamp":"2026-11-11T20:07:58.193Z","sequence":143,"process":{"pid":1030,"ppid":772,"name":"timeout","executable":"/usr/bin/timeout"}}, ... ] ``` ## Options **--type** `string` Only these event types, separated by commas, such as `file_transfer,network_send`. An unknown type is reported with the list of valid ones. **--follow** `boolean` Keep printing events as they happen. Starts at the present unless `--since` or `--limit` is given. Short form: `-f`. **--raw** `boolean` One line per event with every field unformatted. **--pid** `number` Only this process. **--process** `string` Only processes with this name. `*` matches any run of characters. Alias: `--name`. **--path** `string` Only this file. `*` matches any run of characters, `/` included. Matches only `file_seen` and `file_transfer` events. Alias: `--file`. **--remote** `string` Only this remote address or CIDR network. Like the other network filters, it matches only events that concern a socket. **--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`. **--since** `string` Only events made at or after this time: a duration such as `10m`, `1h` or `7d`, or an RFC 3339 timestamp. **--until** `string` Only events made at or before this time. **--limit** `number` Only the most recent n matching events. **--format** `string` (default: table) `table`, `json` or `jsonl`. **--json** `boolean` Short for `--format json`. **--jsonl** `boolean` Short for `--format jsonl`. **--output** `string` Write to this file instead of standard output. Setting `[output] timestamps = false` in the configuration leaves the time out of each event in the text format. See [filters](https://filetrace.mintlify.site/cli/filters.md) and [output formats](https://filetrace.mintlify.site/cli/output-formats.md). ## Examples ```bash theme={null} sudo filetrace events --follow filetrace events --type file_transfer,network_send --pid 1245 --since 5m filetrace events --file '/data/*' --remote 203.0.113.0/24 filetrace events --since 1h --format jsonl ``` ## Exit codes | Code | Meaning | | - | - | | 0 | Success, including a `--follow` stream stopped with Ctrl-C | | 1 | General error | | 2 | Invalid arguments, including an unknown event type or `--raw` with a format | | 3 | Permission denied: the agent socket is not accessible to this user | | 4 | No agent is running (without `--follow`) | | 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.