filetrace capabilities: supported features and their limits

Reference for filetrace capabilities: each feature as FULL, PARTIAL, UNAVAILABLE or DISABLED with the reason, from the agent or a direct check.

filetrace capabilities lists the features available on this machine, each with a status and the reason when it is not available in full. It asks the running agent, which knows what it has attached and in which mode; when it cannot reach an agent, it checks the machine directly.

​

Usage

filetrace capabilities [--format table|json] [--json]

​

What it shows

sudo filetrace capabilities

FEATURE                STATUS       DETAIL
Process tracking       FULL         
File open tracking     UNAVAILABLE  open and close are not traced; a file is identified when it is read or sent
File read tracking     PARTIAL      read(2) and pread(2) on regular files; readv, io_uring and memory-mapped reads are not observed
File write tracking    UNAVAILABLE  writes are not traced
TCP tracking           FULL         
UDP tracking           FULL         received datagrams show their sender only when the application asks for it
IPv6                   FULL         
Sendfile attribution   FULL         
Read+send correlation  PARTIAL      a thread that reads a file and then sends is reported as INFERRED; reads and sends on different threads are not associated
Splice attribution     UNAVAILABLE  transfers through pipes with splice(2) are not followed
io_uring attribution   PARTIAL      bytes sent through io_uring are counted per socket; file reads through io_uring are not observed
Mmap provenance        UNAVAILABLE  data read through memory mappings is not observed
Packet-level egress    UNAVAILABLE  bytes are counted when the socket accepts them, not per packet
Container namespaces   PARTIAL      cgroup and namespace identifiers are recorded per process; container names are not resolved

Reported by the running agent.

Status	Meaning
FULL	Available in full
PARTIAL	Available with the limits given in DETAIL
UNAVAILABLE	Not available on this machine or in this build
DISABLED	Turned off: by the minimal mode or by the configuration

The last line says where the answer comes from: the running agent, or a check of this machine (no agent is running). The agent’s answer reflects its mode and configuration; in minimal mode, for example, file read tracking, sendfile attribution and read+send correlation are DISABLED. A direct check needs the same privileges as the agent, and it is also what happens when the agent’s socket is not accessible to your user, so run the command with sudo to get the agent’s answer. When every feature has the same status for the same reason, as when privileges are missing, the table drops the DETAIL column and states the reason once.

Known limitations explains the limits in more depth, and doctor shows the probes behind each feature.

​

JSON output

sudo filetrace capabilities --json

[
 {"feature":"process_tracking","status":"FULL"},
 {"feature":"file_open_tracking","status":"UNAVAILABLE","detail":"open and close are not traced; a file is identified when it is read or sent"},
 {"feature":"file_read_tracking","status":"PARTIAL","detail":"read(2) and pread(2) on regular files; readv, io_uring and memory-mapped reads are not observed"},
 {"feature":"file_write_tracking","status":"UNAVAILABLE","detail":"writes are not traced"},
 {"feature":"tcp_tracking","status":"FULL"},
 {"feature":"udp_tracking","status":"FULL","detail":"received datagrams show their sender only when the application asks for it"},
 {"feature":"ipv6","status":"FULL"},
 {"feature":"sendfile_attribution","status":"FULL"},
 {"feature":"read_send_correlation","status":"PARTIAL","detail":"a thread that reads a file and then sends is reported as INFERRED; reads and sends on different threads are not associated"},
 {"feature":"splice_attribution","status":"UNAVAILABLE","detail":"transfers through pipes with splice(2) are not followed"},
 {"feature":"io_uring_attribution","status":"PARTIAL","detail":"bytes sent through io_uring are counted per socket; file reads through io_uring are not observed"},
 {"feature":"mmap_provenance","status":"UNAVAILABLE","detail":"data read through memory mappings is not observed"},
 {"feature":"packet_level_egress","status":"UNAVAILABLE","detail":"bytes are counted when the socket accepts them, not per packet"},
 {"feature":"container_namespaces","status":"PARTIAL","detail":"cgroup and namespace identifiers are recorded per process; container names are not resolved"}
]

Each feature has a stable key, its status and, where there is one, the reason as detail.

Key	Feature
process_tracking	Process tracking
file_open_tracking	File open tracking
file_read_tracking	File read tracking
file_write_tracking	File write tracking
tcp_tracking	TCP tracking
udp_tracking	UDP tracking
ipv6	IPv6
sendfile_attribution	Sendfile attribution
read_send_correlation	Read+send correlation
splice_attribution	Splice attribution
io_uring_attribution	io_uring attribution
mmap_provenance	Mmap provenance
packet_level_egress	Packet-level egress
container_namespaces	Container namespaces

​

Options

--format · string · default: "table"

table or json.

--json · boolean

Short for --format json.

​

Examples

filetrace capabilities
sudo filetrace capabilities --format json

​

Exit codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	A direct check lacks the privileges to load BPF programs
5	Unsupported platform
6	The configuration file cannot be read or is invalid