> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
filetrace stats [events|buffers|resources] [options]
```

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

## What it shows

```bash theme={null}
sudo filetrace stats
```

```text theme={null}
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](https://filetrace.mintlify.site/guides/performance.md).

One section:

```bash theme={null}
sudo filetrace stats events
```

```text theme={null}
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:

```bash theme={null}
sudo filetrace stats --json
```

```json theme={null}
{"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](https://filetrace.mintlify.site/integrations/prometheus.md) metrics include the events processed and dropped and the agent's CPU and memory use.

## Examples

```bash theme={null}
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`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.