Skip to main content
Every Filetrace command reads the same set of records that the agent keeps in memory. Knowing what each record represents, how records refer to each other and how long they last makes the output of the commands, the JSON fields and the exported telemetry easier to interpret.

​
Record types

​
Identifiers

Sockets, flows and transfers have stable IDs that the inspect command takes:
A process is identified by its PID and a file by its path, so inspect process 1245 and inspect file /var/www/video.mp4 need no ID.

​
File identity

A file is identified by device and inode, not by path. Its path, size and owner are read from the kernel when the file is first seen and are labels only: a file renamed during a transfer is still the same file. When a file is deleted and its inode number is given to a new file, the new file is a separate file with its own path; the agent notices the end of the old one through the __destroy_inode probe. Inside a container on overlayfs, device and inode are those of the overlay mount. On btrfs, files in different subvolumes can share an inode number.

​
Three byte counts

For a file, three numbers describe different things: Byte counts are what the local socket accepted. They are not bytes on the wire and not what the remote end acknowledged.

​
Lifetime and time ranges

A record in files or transfers covers a transfer’s whole observed lifetime. A record in events covers one collection interval: byte counts are gathered in the kernel and collected several times a second, so a network or transfer event carries the bytes of one such interval, not of one system call. --since and --until select records by when they were active. The byte counts of a selected record still cover its whole observed lifetime.

​
Ownership of accepted connections

A socket created by accept(2) has no owning process until that process sends or receives on it.

​
Bounded, in-memory history

All state is in memory and bounded:
  • Every table has a fixed capacity, set in the [limits] section of the configuration, and forgets its least recently updated entry when it is full.
  • The event log has a fixed size (1 MB by default, [agent] event_log_size) and keeps separate shares for transfers, network events and process events, so a flood of one kind does not push out the others.
  • History starts when the agent starts and is not kept across restarts. Every report that depends on history says from when it reaches:
filetrace stats shows how full each table is:

​
Lost events

If the kernel produces events faster than the agent reads them, some are lost. Lost events are counted in watch, stats and doctor, and a transfer during which events were lost is marked incomplete in JSON and with * after its confidence in tables. A query whose time range contains lost events exits with code 9, meaning the answer may be incomplete. See Overhead and sizing for how to avoid loss.