filetrace events: the agent's records, past and live

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

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 lists the fields of each.

What it shows

sudo filetrace events --type file_transfer --limit 4

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

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:

sudo filetrace events --raw --limit 6

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:

sudo filetrace events --jsonl --limit 12

{"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:

sudo filetrace events --type process_exec,process_exit --limit 4 --json

[
 {"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

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.

boolean

Keep printing events as they happen. Starts at the present unless --since or --limit is given. Short form: -f.

boolean

One line per event with every field unformatted.

number

Only this process.

string

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

string

Only this file. * matches any run of characters, / included. Matches only file_seen and file_transfer events. Alias: --file.

string

Only this remote address or CIDR network. Like the other network filters, it matches only events that concern a socket.

string

Only this local address or CIDR network.

number

Only this local or remote port.

string

default:"all"

Only this protocol: tcp, udp or all.

string

Only this address family: ipv4 or ipv6.

string

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

string

Only events made at or before this time.

number

Only the most recent n matching events.

string

default:"table"

table, json or jsonl.

boolean

Short for --format json.

boolean

Short for --format jsonl.

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 and output formats.

Examples

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

Using the CLI

Monitoring commands

Agent and system

filetrace events: the agent's records, past and live

Usage

Event types

What it shows

The event log

Following events

Raw output

JSON output

Options

Examples

Exit codes

​Usage

​Event types

​What it shows

​The event log

​Following events

​Raw output

​JSON output

​Options

​Examples

​Exit codes

Usage

Event types

What it shows

The event log

Following events

Raw output

JSON output

Options

Examples

Exit codes