filetrace stats: the agent's own statistics

Reference for filetrace stats: events received and lost, CPU and memory use, how full the bounded tables are, network totals and health, with options.

filetrace stats reports on the collector itself: the events it received and lost, its CPU and memory use, how full its bounded tables and event log are, the machine’s network totals and whether it is healthy. Use it to check that the agent keeps up and to size its limits.

​

Usage

filetrace stats [events|buffers|resources] [options]

Without a section, stats prints every section. events, buffers and resources print one.

​

What it shows

sudo filetrace stats

FILETRACE STATISTICS

UPTIME
3s (since 2026-11-11 20:07:55)

EVENTS
Received:         162
Processed:        162
Dropped:          0
Events/sec:       11

RESOURCES
CPU:              0.19%
Memory:           11.8 MB
Open FDs:         41

COLLECTOR
Event queue:      4.00 MB
Peak utilization: 0%
Event log:        1.00 MB, holding 163 events
Processes:        20 of 4,096
Sockets:          19 of 16,384
Flows:            13 of 16,384
Files:            17 of 16,384
Transfers:        4 of 16,384

NETWORK
Outbound:         82.5 MB (3.94 MB/s)
Inbound:          79.4 MB (3.94 MB/s)
Open sockets:     7
Active flows:     13
Active transfers: 4

BACKEND
Linux eBPF (trampolines), standard mode

STATUS
Healthy

Section	Lines
UPTIME	How long the agent has been running, and since when
EVENTS	Events received, processed and dropped, and the current rate. When events were dropped, the causes follow (Queue overflow, Counter table full, Socket unidentified) with the time of the last loss.
RESOURCES	The agent’s CPU use, resident memory and open file descriptors
COLLECTOR	The size of the kernel event queue and its peak use; the size of the event log and the events it holds, with the number of older ones discarded; the entries of each bounded table against its capacity, with the number forgotten to make room; and the read-write candidates still below the inference thresholds
NETWORK	Bytes sent and received on all observed sockets since the agent started, with current rates; open sockets; flows and transfers active within the last 5 seconds
BACKEND	The backend, the probe set (trampolines or kprobes) and the mode
STATUS	Healthy, or Degraded while the collector has lost events within the last 60 seconds

Every table forgets its least recently updated entry when it is full, and the event log discards its oldest events. Forgotten entries, discarded events or a peak utilization of the event queue near 100% are signs that a limit is small for the machine’s activity; see overhead and sizing.

One section:

sudo filetrace stats events

EVENTS
Received:         162
Processed:        162
Dropped:          0
Events/sec:       11

​

JSON output

--json prints one object with exact numbers, including the loss counters by cause and the queue’s peak in bytes:

sudo filetrace stats --json

{"status":"healthy","backend":"Linux eBPF (trampolines)","mode":"standard","version":"26.11.1.147","pid":1008,"started":"2026-11-11T20:07:55.984Z","uptime_seconds":3,"events":{"received":162,"processed":162,"dropped":0,"per_second":11.780,"dropped_queue_overflow":0,"dropped_counter_table_full":0,"dropped_socket_unidentified":0},"resources":{"cpu_percent":0.194,"memory_bytes":12337152,"open_fds":41},"collector":{"event_queue_bytes":4194304,"event_queue_peak_bytes":11096,"candidates_below_threshold":0,"event_log_bytes":1048576,"event_log_events":163,"event_log_discarded":0,"processes":{"entries":20,"capacity":4096,"evictions":0},"sockets":{"entries":19,"capacity":16384,"evictions":0},"flows":{"entries":13,"capacity":16384,"evictions":0},"files":{"entries":17,"capacity":16384,"evictions":0},"transfers":{"entries":4,"capacity":16384,"evictions":0}},"network":{"bytes_sent":86500479,"bytes_received":83218251,"bytes_sent_per_second":4131418,"bytes_received_per_second":4131418,"open_sockets":7,"active_flows":13,"active_transfers":4}}

The JSON object always holds every section; a section name selects what the table shows. With --watch, each repetition prints one object on its own line.

​

Options

--watch · boolean

Repeat until interrupted.

--interval · string · default: "1s"

Repeat at this interval, such as 5s. Implies --watch. The shortest is 100 ms.

--format · string · default: "table"

table or json.

--json · boolean

Short for --format json.

The Prometheus metrics include the events processed and dropped and the agent’s CPU and memory use.

​

Examples

filetrace stats
filetrace stats events --watch
filetrace stats --format json

​

Exit codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments, including an unknown section
3	Permission denied: the agent socket is not accessible to this user
4	No agent is running
6	The configuration file cannot be read or is invalid
9	The collector reports recent event loss (STATUS is Degraded)