filetrace agent: run, check and stop the agent

Reference for filetrace agent: run the collector in the foreground, report whether an agent serves the socket and how healthy it is, or stop it.

filetrace agent runs or controls the background agent from the command-line interface. run collects in the foreground and serves queries, like filetrace-agent; status reports whether an agent is serving the socket; stop asks the running agent to stop.

​

Usage

filetrace agent run [options]
filetrace agent status
filetrace agent stop

​

run

agent run starts the agent in the foreground: it loads the probes, collects and answers the other commands on the socket until you press Ctrl-C. It runs the same code as filetrace-agent and takes the same options. The global options --socket and --config given before agent, and $FILETRACE_SOCKET, are passed on to it.

sudo filetrace agent run

Service managers should start filetrace-agent directly. Run the agent as a service shows how.

​

status

agent status reports whether an agent is serving the socket, with its backend, mode, PID, start time, uptime and health:

sudo filetrace agent status

Monitoring: RUNNING
Backend:    Linux eBPF (trampolines)
Mode:       standard
PID:        1008
Started:    2026-11-11 20:07:55
Uptime:     0s
Health:     Healthy

Health is Degraded while the agent has lost events within the last 60 seconds; stats gives the details. When no agent is running, status prints Monitoring: STOPPED with the command that starts one. Because the exit code carries the answer, status suits scripts and health checks:

sudo filetrace agent status >/dev/null; echo $?

​

stop

agent stop asks the running agent to stop. It prints The agent is stopping. and returns; the agent closes its socket and removes it as it exits.

sudo filetrace agent stop

​

Options

status and stop take no options. The options of run:

--mode · string · default: "standard"

minimal or standard. Minimal collects processes, sockets and network byte counts; standard adds file identity and file-to-network attribution.

--probes · string · default: "auto"

auto, trampoline or kprobe. Auto uses BPF trampolines where the kernel has them and kprobes otherwise.

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

How often counters are collected from the kernel.

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

Kernel event queue size. The default is 1MB in minimal mode.

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

Longest read-to-send gap that still associates a file with a send.

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

error, warn, info or debug.

agent run also accepts --event-log-size and the other options of filetrace-agent, which lists their accepted ranges, and filetrace agent run --help prints the agent’s own help.

​

Examples

sudo filetrace agent run
sudo filetrace agent run --mode minimal
sudo filetrace agent status

​

Exit codes

Command	Code	Meaning
status	0	An agent is running and healthy
status	4	No agent is running
status	9	An agent is running but degraded
status, stop	3	The agent socket is not accessible to this user
stop	0	The agent was asked to stop
stop	4	No agent is running
run	0, 1, 2, 3, 5, 6, 8	As for filetrace-agent
any	2	Invalid arguments, such as a missing or unknown action