filetrace events prints them in order, and the OpenTelemetry exporter can send them as log records. This page lists the twelve event types, when each is recorded and which fields it carries, and explains the bounded log that holds them.
How events are recorded
Process and socket lifecycle events travel from the kernel to the agent through a ring buffer and are recorded as they happen. Byte counts never become one event per system call. They accumulate in a kernel table keyed by socket, process and file, and the agent collects them every[agent] flush_interval (250 ms by default). A network_send, network_receive or file_transfer event therefore carries the bytes of one collection interval. A long transfer produces one file_transfer event per interval in which it moved bytes, and the bytes of those events add up to the transfer’s bytes_sent in filetrace files.
Not recorded at all:
- file opens and closes, file writes, and individual system calls;
- the processes that
[filters] exclude_processesmatches, and the transfers of files that[filters] exclude_pathsmatches; - sockets of a protocol or address family turned off in
[network].
The event log
Past events come from a log in the agent’s memory. It has a fixed size,[agent] event_log_size (1 MB by default, 256 KB in minimal mode), starts empty when the agent starts and holds only the most recent events. The log is divided into three shares, so that a flood of one kind of event does not push out the others:
When a share is full, its oldest events are discarded to make room.
filetrace stats buffers shows the log’s size, how many events it holds and how many it has discarded, and the table output of filetrace events ends with how far back the log reaches:
event_log_size = 0 the agent keeps no log; filetrace events --follow still prints new events as they happen.
Summary
process is left out when the event has no owning process. An accepted connection, for example, has no owning process until that process sends or receives on it.
Common fields
Every event in JSON and JSON Lines starts with these fields. The groups that follow use the same keys as the transfer records offiletrace files.
string
The event type.
string
RFC 3339 time in UTC with milliseconds. For byte counts, it is when the last byte of the interval was counted.
integer
Increases with every event the agent records. Gaps mean that a filter left events out or that the log discarded them.
Process events
process_exec, process_fork and process_exit describe the life of a process. The process group carries:
integer
Process ID.
integer
Parent process ID. Omitted when unknown.
string
The kernel’s name for the process. Omitted when unknown.
string
Path of the executable. Omitted when unknown, such as for a forked process whose parent’s executable the agent never saw.
integer
Only in
process_exit: the exit status of a process that exited.integer
Only in
process_exit: the signal that ended the process, in place of exit_status.Socket events
socket_connect, socket_listen, socket_established and socket_close follow the state of TCP sockets, as the kernel’s inet_sock_set_state tracepoint reports it. socket_close is recorded only for a socket the agent already knows. Each carries a process group with pid, ppid and name when the socket has an owner, and a network group:
string
tcp.integer
The socket’s ID, as in the
SOCKET column of filetrace connections.string, integer
The local end. Each is omitted when unknown.
string, integer
The remote end. Each is omitted when unknown, as for a listening socket.
File events
file_seen is recorded when a file is read or sent for the first time. It describes the file only, with no process or socket. The file group carries:
string
Path of the file. Omitted when it is not known.
integer
Inode number.
integer
Device number, as
stat(2) reports it.integer
Size in bytes when the file was seen.
boolean
true when the file no longer has a directory entry.Network events
network_send and network_receive carry the bytes one socket accepted or delivered for one process and remote endpoint during one collection interval. An interval with no bytes in a direction produces no event for it. Byte counts are what the local socket accepted or delivered, not bytes on the wire. Each event carries a process group (pid, ppid, name) and a network group with protocol (tcp or udp), socket_id, the local and remote ends, and one of:
integer
In
network_send: bytes the socket accepted during the interval.integer
In
network_receive: bytes the socket delivered during the interval.Transfer events
file_transfer carries the file bytes attributed to one socket during one collection interval. It has a process group (pid, ppid, name), the file group of file_seen, a network group with protocol, socket_id and the two ends, and a transfer group:
string
sendfile or read-write.integer
File bytes the socket accepted during the interval.
integer
Only for
read-write: bytes the thread read from the file during the interval.string
The confidence of the whole association so far, not of this interval alone:
exact or inferred. Omitted while a read-write association is still below the reporting thresholds ([correlation] inferred_min_bytes and inferred_min_percent) or below [correlation] confidence_threshold. The text output shows confidence=pending in that case.Loss events
event_loss is recorded when the agent finds that events were lost since it last checked. Any listing whose time range includes the loss exits with code 9. The event carries a loss group:
integer
How many events were lost.
string
Why they were lost.
The last cause is sent only to the
--follow reader concerned, in place of the events it missed. It is not stored in the log.
Output formats
filetrace events prints each event as a block of key=value lines by default, headed by its time and type in upper case. [output] timestamps = false leaves the time out. --format json prints one array, --format jsonl one event per line.
--raw prints one line per event with every field unformatted, in a fixed order, with the text field (a path or an executable) last because it may hold spaces:
--raw cannot be combined with --format.
Selecting events
--type takes a comma-separated list of the types above; an unknown name prints the list of types and exits with code 2. The other filters (--pid, --process, --path, --remote, --port, --since, --limit and more) are described on the events page.
Export over OTLP
The OTLP exporter sends events as log records, one per event, with the event namefiletrace.<type>. By default it sends file_transfer and event_loss; [otlp] events names any other types from the list above. Within each [otlp] flush_interval, the bytes of one transfer, or of one socket and peer, are summed into a single record, so a long transfer produces one record per interval. OpenTelemetry (OTLP) describes the records and Metrics and attributes reference their attributes.