Exit codes of filetrace and filetrace-agent

Both programs report their outcome through the exit code, so that scripts, monitoring checks and service managers can act on it without parsing text. This page lists the codes of the filetrace commands, the special meanings that doctor, agent status and stats give them, and the codes of filetrace-agent with the ones its systemd unit does not restart on. Code 9 deserves the most attention: the command succeeded, but its answer may be incomplete.

filetrace commands

Code	Meaning	Typical cause
`0`	Success
`1`	General error	The agent speaks a different protocol version; the file named with `--output` cannot be written; out of memory
`2`	Invalid arguments	An unknown option or command, a missing or malformed value, an invalid `--path-regex`
`3`	Permission denied	The agent’s socket is not accessible to this user
`4`	Agent unavailable	No agent is serving the socket, or the connection to it was lost
`5`	Unsupported platform or capability	The kernel or platform cannot be monitored; a `--method` this build does not observe
`6`	Invalid configuration	The configuration file cannot be read or does not parse
`9`	Partial results	Events were lost inside the queried time range

Errors are written to standard error. A usage error (code 2) ends with a pointer to the command’s help:

See 'filetrace help files' for usage.

3: permission denied

The agent’s socket admits only root and the agent’s own user. With the agent running as root, the commands that query it need sudo:

Permission denied.

The agent socket /run/filetrace/agent.sock is not accessible to this user.
Run the command with sudo.

4: agent unavailable

The message names the socket and the reason the connection failed:

The Filetrace agent is not running (/run/filetrace/agent.sock: No such file or directory).

Start it with:
  sudo filetrace agent run

To check what this machine supports:
  sudo filetrace doctor

filetrace watch and filetrace events --follow do not fail this way: without an agent they collect in the foreground for as long as they run.

5: unsupported

Besides an unsupported kernel or platform, code 5 answers a question this build cannot answer. --method splice, --method mmap and --method io_uring are accepted by files and transfers and refused with code 5, rather than answered with an empty list that would read as “nothing was sent this way”:

filetrace: transfers made with splice are not observed by this build, so none
can be listed. 'filetrace capabilities' shows what is observed.

6: invalid configuration

Every command except config and help reads the configuration file first, and stops with code 6 when the file cannot be read or does not parse. filetrace config validate reports the problem; it exits with 0 when the file is usable and 6 when it is not. See Configuration file reference.

9: partial results

Code 9 means the command printed its answer, but events were lost inside the queried time range, so byte counts or records may be missing. The output on standard output is complete and well-formed in every format; the warning goes to standard error:

WARNING: <n> events lost.

Affected monitoring window:
<first> - <last>

Attribution reliability:
DEGRADED

A transfer during which events were lost is marked incomplete: true in JSON and with * after its confidence in tables. Lost events are also counted by watch, stats and doctor. filetrace events --follow exits with 0 when it is interrupted, whatever was lost while it ran.

Commands with their own meanings

doctor

filetrace doctor exits with the code of its verdict, also printed as STATUS: and, with --json, as status:

Code	Status	Meaning
`0`	`READY`	The machine can be monitored
`3`	`NEEDS PRIVILEGES`	Loading BPF programs needs root, or `CAP_BPF` with `CAP_PERFMON`
`5`	`UNAVAILABLE`	This machine cannot be monitored
`9`	`DEGRADED`	Some probes are missing, or the running agent is losing events

agent status

Code	Meaning
`0`	An agent is running and healthy
`4`	No agent is running (`Monitoring: STOPPED`)
`9`	An agent is running but degraded: it has lost events within the last minute
`3`	An agent is running, but its socket is not accessible to this user

stats

filetrace stats exits with 9 while the agent reports recent event loss, that is, a loss within the last minute. The JSON output shows the same condition as "status": "degraded".

filetrace-agent

filetrace-agent and filetrace agent run exit with these codes:

Code	Meaning	Restarted by systemd
`0`	Stopped normally, by `SIGTERM`, `SIGINT` or `filetrace agent stop`, or not started because `[agent] enabled = false`	No
`1`	Other errors, such as another agent already serving the socket	Yes
`2`	Invalid arguments	No
`3`	Permission denied: the agent lacks the privileges to load BPF programs or to create its socket	No
`5`	Unsupported platform or kernel	No
`6`	Invalid configuration, including an exporter address of the wrong form (`[prometheus] listen`, `[otlp] endpoint`, `[grpc] listen`)	No
`8`	The metrics page cannot listen on `[prometheus] listen`, for example because the port is taken	Yes

The systemd unit restarts the agent on failure after 5 seconds, at most 5 times in 300 seconds, except on the codes that a retry does not fix:

Restart=on-failure
RestartSec=5
# Invalid arguments, missing privileges, an unsupported kernel and a broken
# configuration file do not go away on a retry.
RestartPreventExitStatus=2 3 5 6

The unit starts only where /sys/kernel/btf/vmlinux exists. Under OpenRC, the service checks for BTF and runs filetrace config validate before every start, and respawns the agent after 5 seconds, at most 5 times in 300 seconds. See Run the agent as a service.

Scripting

Treat 9 as a result to keep, with a warning, rather than as a failure:

#!/bin/sh
# Exports the last hour of file transfers; run as root.
filetrace files --since 1h --jsonl --output /var/tmp/transfers.jsonl
code=$?
case $code in
0)
    ;;
9)
    echo "events were lost in the last hour; byte counts may be low" >&2
    ;;
*)
    echo "filetrace files failed with exit code $code" >&2
    exit "$code"
    ;;
esac

A health check that tells a stopped agent from a degraded one:

#!/bin/sh
filetrace agent status >/dev/null
case $? in
0) echo "OK: agent running" ;;
9) echo "WARNING: agent running, events lost in the last minute"; exit 1 ;;
4) echo "CRITICAL: agent not running"; exit 2 ;;
*) echo "UNKNOWN: agent status could not be read"; exit 3 ;;
esac

Use Filetrace output in scripts has more patterns.

Configuration and output

Platform and security

Exit codes of filetrace and filetrace-agent

filetrace commands

3: permission denied

4: agent unavailable

5: unsupported

6: invalid configuration

9: partial results

Commands with their own meanings

doctor

agent status

stats

filetrace-agent

Scripting

​filetrace commands

​3: permission denied

​4: agent unavailable

​5: unsupported

​6: invalid configuration

​9: partial results

​Commands with their own meanings

​doctor

​agent status

​stats

​filetrace-agent

​Scripting

filetrace commands

3: permission denied

4: agent unavailable

5: unsupported

6: invalid configuration

9: partial results

Commands with their own meanings

doctor

agent status

stats

filetrace-agent

Scripting