Skip to main content
Filetrace consists of two programs with separate jobs. filetrace-agent collects: it loads BPF programs into the kernel, turns what they report into records, and keeps those records in memory. filetrace asks: every command sends a query to the agent over a local socket and prints the answer. This page explains how the two fit together, which one needs privileges, and how data flows from the kernel to your terminal.

​
The agent

filetrace-agent is the only part that needs privileges, because only loading BPF programs does. It runs as a service (systemd, OpenRC or SysV init) or in the foreground with sudo filetrace agent run. It reads /etc/filetrace/config.toml once when it starts; its command-line options override the file. Inside the agent, data takes two paths:
  • Lifecycle events (process exec, fork and exit; socket connect, listen, establish and close) travel from the kernel through a ring buffer, 4 MB by default.
  • Byte counts never become one event per system call. They accumulate in a kernel hash map keyed by socket, process and file. Every 250 ms the agent swaps that map for an empty one and reads the idle one, so no update is lost while it reads.
The agent folds both into bounded tables of processes, sockets, flows, files and transfers, and into an event log of bounded size. Rates are bytes per second over the last one to two seconds. Records and identifiers describes what each table holds. The exporters are also part of the agent: the Prometheus page, the OTLP exporter and the gRPC API run inside it and are off until the configuration turns them on. They read the same state the commands read and add nothing to what the probes do. See Integrations.

​
The command

filetrace is the command-line interface. It connects to the agent’s socket, /run/filetrace/agent.sock by default, sends a query and prints the result as a table, JSON, JSON Lines, CSV or bare identifiers. The command itself loads nothing into the kernel. The socket admits root and the user the agent runs as. With the agent running as root, as the packaged service does, the commands that query it need sudo. --socket or $FILETRACE_SOCKET names another socket, and --config or $FILETRACE_CONFIG names another configuration file. The command takes its default output format and the agent’s socket from the configuration file.

​
Collection without an agent

Two commands can collect on their own. Without a running agent, filetrace watch and filetrace events --follow load the probes themselves and collect in the foreground for as long as they run. This needs the same privileges as the agent. Such a collector exports nothing, and what it saw is gone when it exits. Every other command needs the agent and exits with code 4 when it is not running:

​
Modes

The agent runs in one of two modes, set with [agent] mode or --mode:

​
Version coupling

The command and the agent speak one protocol version. A package upgrade therefore restarts a running agent together with the new command. See Installation.

Kernel instrumentation

Which kernel functions are traced, and how.

Run the agent as a service

Service managers, permissions and the systemd hardening.