Skip to main content
Filetrace’s agent attaches BPF programs to kernel tracepoints and kernel functions. Kernel functions are traced through BPF trampolines (fentry and fexit) where the kernel can attach them, and through kprobes where it cannot, as on arm64 before Linux 6.4. This page lists what each probe records and explains why the kprobe set reads kernel counters instead of return values. The programs are compiled once and adapted to the running kernel through CO-RE, using the kernel’s BTF type information. A probe counts as attached only if the kernel accepted the program and every kernel field it reads was found.

​
Choose a probe set

The probes setting selects the set: Set it in the configuration file or on the agent’s command line:
filetrace doctor loads and attaches every probe of a set, reports which set is in use and what the kernel accepted, and removes the probes again. filetrace without arguments shows the set the running agent uses, for example Linux eBPF (trampolines), standard mode.

​
Trampoline set

The probes see the kernel’s own file and socket objects, so nothing is keyed on file descriptor numbers, and descriptor reuse cannot misattribute a transfer.

​
Kprobe set

The trampoline set needs the return value of each traced function. Where the kernel cannot attach trampolines, the usual substitute is a return probe (kretprobe), and it does not hold up for this workload: a return probe keeps one of a small pool of instances for as long as the call blocks, as many as there are CPUs on a kernel without full preemption. A few threads waiting in recv are enough for every other return to go unseen. The kprobe set therefore probes function entries only and reads the results from counters the kernel keeps anyway: Sequence numbers cannot miss a call: whatever was sent since the socket was last looked at is the difference.

​
Differences of the kprobe set

  • The bytes of the last send on a connection are counted when the socket is next used or closed.
  • Kernel TLS sockets count encrypted bytes.
  • Raw and ICMP sockets are not counted.
  • File reads need a kernel built with CONFIG_TASK_XACCT.
  • What a thread reads with readv between a file read and a send is counted as read from that file.
  • The kernel holds about 8 MB more in BPF maps for the kprobe set’s socket table.

​
Kernels and architectures

Collection needs Linux 6.1 or later with BTF. Filetrace is tested on Linux 6.1, 6.12 and 7.0 on arm64; Debian’s 6.1 arm64 kernel has no BPF trampolines and exercises the kprobe set as shipped. Continuous integration builds and tests x86-64 and arm64. Other kernels are expected to work through CO-RE but are untested.