Skip to main content
Filetrace reports what the kernel lets it prove, and says how sure it is. This page collects what it does not see, what it cannot attribute, and what this build leaves out, by topic, so that you can judge an empty or partial answer. filetrace capabilities reports the same limits for the machine it runs on, and filetrace doctor checks the kernel.

​
Platform support

  • Collection needs BTF (/sys/kernel/btf/vmlinux); the systemd unit does not start without it.
  • Continuous integration builds and tests x86-64 and arm64 on the kernel of GitHub’s Ubuntu 24.04 runners. Other kernels are expected to work through CO-RE but are untested.
  • SELinux in enforcing mode is untested.
  • Kernel functions are traced through BPF trampolines where the kernel can attach them and through kprobes where it cannot, as on arm64 before 6.4. The kprobe set has limits of its own, listed below.

​
Attribution

A file is associated with a send in two ways: sendfile (EXACT) and a thread that reads a file and then sends (INFERRED). File attribution and confidence explains both. Outside them:
  • A file read by one thread and sent by another, or passed through a pipe, is not associated with the send.
  • Files read with readv, through io_uring or through a memory mapping are not seen as read. Bytes sent through io_uring are still counted per socket.
  • splice transfers through pipes are not followed. --method splice, --method mmap and --method io_uring are accepted and refused with exit code 5 rather than answered with an empty list.
  • A file read entirely before a fresh TLS connection is opened is not associated: the handshake’s receive ends the association.
  • An inferred association can be wrong when a thread reads one file and then sends unrelated data of similar size without receiving in between.
  • STRONG confidence is defined for provenance followed through intermediate operations; no probe produces it.
  • File opens and writes are not traced. A file is identified when it is read or sent.
  • An accepted connection has no owning process until that process sends or receives on it.
  • Received UDP datagrams show their sender only when the application asks for it.
  • Byte counts are what the local socket accepted. They are not the number of bytes on the wire and not what the remote end acknowledged; packet-level counters are not included.

​
With the kprobe set

Where the kernel cannot attach BPF trampolines, or with --probes kprobe, the agent probes function entries only and reads the results from counters the kernel keeps. Kernel instrumentation explains why. With this 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.

​
File identity

A file is identified by device and inode; its path, size and owner are read from the kernel when the file is first seen and are only labels.
  • 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.
  • A file that is given the inode number of a deleted one is a separate file with its own path.
  • cgroup and namespace identifiers are recorded per process; container names are not resolved.

​
History and memory

  • All state is in memory and bounded. Every table has a fixed capacity ([limits]) and forgets its least recently updated entry when it is full.
  • History starts when the agent starts and is not kept across restarts; every report that depends on it says from when it reaches.
  • The event log has a fixed size (1 MB by default) and holds only the most recent events.
  • --since and --until select records by when they were active; byte counts cover each record’s whole observed lifetime.
  • Exported counters, and the OTLP batches waiting for a collector, live in memory and do not survive a restart of the agent. While the collector cannot be reached, the agent keeps up to 16 batches (8 MB) and then gives up the oldest.

​
Exporters and API

  • The OTLP exporter and the gRPC API speak without TLS and do not resolve host names: the OTLP endpoint is a collector on the same host, given by numeric address or Unix socket.
  • The gRPC API has no server reflection, so a client names the schema.
  • The Prometheus page has no authentication.
Security describes how to keep these interfaces local.

​
Not included in this build

  • Persistent history. The [storage] section is accepted and ignored.
  • OpenTelemetry traces, and OTLP over HTTP.
  • Packet-level counters. [network] tc_egress is accepted and ignored.
  • TLS attribution.
  • The record, replay, monitor and integrations commands.
The configuration keys of these and other missing features are accepted, and setting one to true is reported as a warning; see Configuration file reference.