filetrace-agent: the collector and its options

Reference for filetrace-agent, which loads the probes and serves queries: options with defaults and ranges, modes, socket access, logging, exit codes.

filetrace-agent is the program that collects. It loads the probes into the kernel, keeps what they report in bounded memory and answers queries from the filetrace command over a local socket. It is also what exports: the metrics page, the OTLP exporter and the gRPC API run inside it when the configuration turns them on. It runs in the foreground until it is stopped; the packages install it as the filetrace-agent service.

​

Usage

filetrace-agent [options]

sudo filetrace-agent

filetrace agent run runs the same code from the command-line interface. Service managers should start filetrace-agent directly; run the agent as a service covers systemd, OpenRC and SysV init.

​

Settings and options

Settings come from the configuration file; an option given on the command line overrides the file. The agent reads the file before it looks at its other options, so an option overrides the file wherever it stands on the command line. filetrace config show prints every setting of the file, and the configuration file reference describes them.

​

Options

--config · string · default: "/etc/filetrace/config.toml"

Configuration file. The default file is read if it exists; $FILETRACE_CONFIG names another default.

--socket · string · default: "/run/filetrace/agent.sock"

Listening socket. The agent creates its directory if needed.

--mode · string · default: "standard"

minimal or standard. See Modes.

--probes · string · default: "auto"

auto, trampoline or kprobe. Auto traces kernel functions through BPF trampolines where the kernel has them and through kprobes otherwise. Kernel instrumentation compares the two sets.

--flush-interval · string · default: "250ms"

How often counters are collected from the kernel, from 10ms to 60s.

--queue-size · string · default: "4MB"

Kernel event queue size, from 64KB to 1GB. The default is 1MB in minimal mode.

--event-log-size · string · default: "1MB"

Memory for the log of recent events that filetrace events reads, from 64KB to 256MB; 0 keeps none. The default is 256KB in minimal mode.

--correlation-window · string · default: "2s"

Longest read-to-send gap that still associates a file with a send. See file attribution and confidence.

--log-level · string · default: "info"

error, warn, info or debug.

--version · boolean

Print the version and exit.

-h, --help · boolean

Print the help and exit.

Times take a unit (ms, s, m, h, d) and sizes an optional one (KB, MB, GB), as described in filters. A value outside its range, or an unknown option, is reported with the help, and the agent exits with 2.

​

Modes

Mode	Collects
minimal	Processes, sockets and network byte counts
standard	Adds file identity and file-to-network attribution

In minimal mode, capabilities reports file read tracking, sendfile attribution and read+send correlation as DISABLED.

​

Socket access

The agent creates its socket so that only its owner can open it, and it accepts connections only from root and from the user it runs as; it logs a warning for any other client and closes the connection. When the agent runs as root, the commands that query it need sudo. If another agent already serves the socket, the agent reports it and exits with 1. When the agent stops, it removes the socket.

​

Running and stopping

The agent stops on SIGINT (Ctrl-C) or SIGTERM, and when filetrace agent stop asks it to. If the configuration sets [agent] enabled = false, the agent logs a warning and exits with 0 without collecting.

The agent logs to standard error, one line per message, prefixed with filetrace: and the level, such as filetrace: warn:. At the default level, it logs where its settings came from, the backend and mode it collects with, and the exporters it serves.

​

Examples

sudo filetrace-agent
sudo filetrace-agent --mode minimal
sudo filetrace-agent --probes kprobe --log-level debug
sudo filetrace-agent --config /etc/filetrace/config.toml --event-log-size 16MB
filetrace-agent --version

​

Exit codes

Code	Meaning
0	Stopped normally
1	Other errors, such as another agent already serving the socket
2	Invalid arguments
3	Permission denied: not allowed to load BPF programs or to create the socket
5	Unsupported platform or kernel
6	Invalid configuration
8	The metrics page cannot listen on its configured address

The systemd service does not restart an agent that exited with 2, 3, 5 or 6, because those causes do not go away on a retry.