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 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
string
default:"/etc/filetrace/config.toml"
Configuration file. The default file is read if it exists;
$FILETRACE_CONFIG names another default.string
default:"/run/filetrace/agent.sock"
Listening socket. The agent creates its directory if needed.
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.string
default:"250ms"
How often counters are collected from the kernel, from
10ms to 60s.string
default:"4MB"
Kernel event queue size, from
64KB to 1GB. The default is 1MB in minimal mode.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.string
default:"2s"
Longest read-to-send gap that still associates a file with a send. See file attribution and confidence.
string
default:"info"
error, warn, info or debug.boolean
Print the version and exit.
boolean
Print the help and exit.
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
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 needsudo. 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 onSIGINT (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
Exit codes
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.