> ## 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.

# JSON output schema

> Field-by-field reference of the JSON and JSON Lines records of files, transfers, processes, connections, flows, top, inspect, stats, capabilities and doctor.

Every listing command of `filetrace` prints machine-readable records with `--format json` (or `--json`) and `--format jsonl` (or `--jsonl`), and the report commands `inspect`, `stats`, `capabilities` and `doctor` print one JSON document with `--format json`. This page describes the shape of each record and what every field means, so that scripts and log pipelines can rely on it. [Output formats](https://filetrace.mintlify.site/cli/output-formats.md) covers the other formats.

## Documents and lines

`json` prints one document per command run. For a listing it is an array that opens with `[`, holds one record per line and closes with `]`; an empty result is `[]`. `jsonl` prints one record per line and nothing else, which suits `grep`, `jq` and log shippers.

| Command | Record | `json` | `jsonl` |
| - | - | - | - |
| `files`, `transfers` | [Transfer](#transfer-records) | array | yes |
| `processes` | [Process](#process-records) | array | yes |
| `connections` | [Connection](#connection-records) | array | yes |
| `flows` | [Flow](#flow-records), or [group](#top-and-grouped-flows) with `--group-by` | array | yes |
| `top` | depends on the subject, see [Top and grouped flows](#top-and-grouped-flows) | array | yes |
| `events` | [Event](https://filetrace.mintlify.site/reference/event-types.md) | array | yes |
| `inspect` | [Inspect report](#inspect) | object | no |
| `stats` | [Statistics](#stats) | object | no |
| `capabilities` | [Feature](#capabilities) | array | no |
| `doctor` | [Diagnosis](#doctor) | object | no |

```bash theme={null}
filetrace files --jsonl
```

```text theme={null}
{"event":"file_transfer","transfer_id":"tr_3","timestamp":"2026-11-11T20:07:59.514Z","host":"web-01","platform":"linux","process":{"pid":1024,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/stream.bin","inode":626330,"device":63,"size":40000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":16,"local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871},"transfer":{"method":"sendfile","bytes_sent":16250000,"bytes_per_second":4273270,"operations":65,"started":"2026-11-11T20:07:56.193Z","duration_ms":3320,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
{"event":"file_transfer","transfer_id":"tr_2","timestamp":"2026-11-11T20:07:56.072Z","host":"web-01","platform":"linux","process":{"pid":1018,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/customers.csv","inode":626326,"device":63,"size":12000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":9,"local_ip":"127.0.0.1","local_port":60088,"remote_ip":"127.0.0.1","remote_port":52535},"transfer":{"method":"read-write","bytes_sent":12000000,"bytes_read":12000000,"bytes_per_second":0,"operations":184,"started":"2026-11-11T20:07:56.070Z","duration_ms":1,"state":"active","confidence":"inferred","evidence":["file_identity","socket_identity","remote_endpoint","thread_read_then_send","repeated_read_then_send","byte_balance"],"incomplete":false}}
```

## Conventions

* **Byte counts** are exact whole numbers of bytes. They are what the local socket accepted, not bytes on the wire and not what the remote end acknowledged.
* **Byte rates** (`bytes_per_second`, `bytes_sent_per_second`, `bytes_received_per_second`) are whole bytes per second over the last one to two seconds.
* **Times** are RFC 3339 timestamps in UTC with milliseconds, such as `2026-11-11T20:07:56.063Z`.
* **Missing values are left out.** A field the agent has no value for is omitted rather than set to `null`, and an empty list is omitted. Check for a key before reading it.
* **One schema per kind of record.** A transfer has the same groups and keys whether it comes from `files`, `transfers` or `inspect`; an event of `events` uses the same groups for the part it shares.
* **Host names.** With `--resolve-hostnames`, connection, flow and transfer records gain a `remote_host` field where a reverse DNS lookup found a name.
* **Partial results.** When events were lost inside the queried time range, the command still prints a complete document, writes a warning to standard error and exits with code 9. See [Exit codes](https://filetrace.mintlify.site/reference/exit-codes.md).
* `--output <file>` writes the same document to a file instead of standard output.

## Transfer records

`files` and `transfers` print one record per transfer: one process sending one file over one socket by one method, over the transfer's whole observed lifetime. `transfers` also lists, as `network_transfer` records, the bytes sent on a socket that no file accounts for; `files --include-unknown` includes them too. The `transfers` arrays of `inspect` hold the same records.

A read-write transfer from `filetrace files --jsonl`, formatted for reading:

```json theme={null}
{
  "event": "file_transfer",
  "transfer_id": "tr_2",
  "timestamp": "2026-11-11T20:07:56.072Z",
  "host": "web-01",
  "platform": "linux",
  "process": {
    "pid": 1018,
    "ppid": 772,
    "name": "file-server",
    "executable": "/usr/local/bin/file-server"
  },
  "file": {
    "path": "/srv/export/media/files/customers.csv",
    "inode": 626326,
    "device": 63,
    "size": 12000000,
    "owner": "root",
    "filesystem": "overlay",
    "deleted": false
  },
  "network": {
    "protocol": "tcp",
    "socket_id": 9,
    "local_ip": "127.0.0.1",
    "local_port": 60088,
    "remote_ip": "127.0.0.1",
    "remote_port": 52535
  },
  "transfer": {
    "method": "read-write",
    "bytes_sent": 12000000,
    "bytes_read": 12000000,
    "bytes_per_second": 0,
    "operations": 184,
    "started": "2026-11-11T20:07:56.070Z",
    "duration_ms": 1,
    "state": "active",
    "confidence": "inferred",
    "evidence": ["file_identity", "socket_identity", "remote_endpoint",
                 "thread_read_then_send", "repeated_read_then_send", "byte_balance"],
    "incomplete": false
  }
}
```

Bytes that no file accounts for, from `filetrace transfers --json`, formatted for reading:

```json theme={null}
{
  "event": "network_transfer",
  "transfer_id": "tr_s1001",
  "timestamp": "2026-11-11T20:07:56.180Z",
  "host": "web-01",
  "platform": "linux",
  "process": {
    "pid": 152,
    "ppid": 1,
    "name": "metrics-daemon",
    "executable": "/metrics-daemon"
  },
  "network": {
    "protocol": "tcp",
    "socket_id": 4097,
    "local_ip": "192.0.2.7",
    "local_port": 2376,
    "remote_ip": "198.51.100.1",
    "remote_port": 25374
  },
  "transfer": {
    "bytes_sent": 473,
    "bytes_per_second": 0,
    "started": "2026-11-11T20:07:56.063Z",
    "duration_ms": 116,
    "state": "active",
    "confidence": "unknown",
    "incomplete": false
  }
}
```

> [!NOTE]
>
> `file.size`, `transfer.bytes_read` and `transfer.bytes_sent` are three different numbers: the size of the file when it was first seen, what a thread read from it, and what the socket accepted. In `files` a record covers a transfer's whole lifetime; a `file_transfer` event of `filetrace events` covers one collection interval.

**event** `string`

`file_transfer` for bytes associated with a file. `network_transfer` for bytes a socket sent that no file accounts for.

**transfer\_id** `string`

The transfer's ID, as in the `ID` column of `transfers`. A file transfer is `tr_` followed by a hexadecimal number; a `network_transfer` is `tr_s` followed by the socket ID in hexadecimal (`tr_s1001` is socket 4097).

**timestamp** `string`

When the transfer's latest bytes were sent.

**host** `string`

The host name of the machine.

**platform** `string`

The operating system, `linux`.

**process** `object`

The process that sent the bytes.

**process**

**pid** `integer`

Process ID.

**ppid** `integer`

Parent process ID. Omitted when unknown.

**name** `string`

The kernel's name for the process, as in the `PROCESS` column.

**executable** `string`

Path of the executable. Omitted when unknown.

**file** `object`

The file. Only in `file_transfer` records. A file is identified by device and inode; its path, size and owner are read from the kernel when the file is first seen and are labels.

**file**

**path** `string`

Path of the file. Omitted when it is not known. A path too deep to be read whole starts with `...`.

**inode** `integer`

Inode number.

**device** `integer`

Device number, as `stat(2)` reports it.

**size** `integer`

Size in bytes when the file was first seen. Omitted when the path is not known.

**owner** `string`

User name of the file's owner, or the numeric user ID when it has no name. Omitted when the path is not known.

**filesystem** `string`

Type of the filesystem, such as `overlay`.

**deleted** `boolean`

`true` when the file no longer has a directory entry.

**network** `object`

The socket the bytes were sent on.

**network**

**protocol** `string`

`tcp` or `udp`.

**socket\_id** `integer`

The socket's ID, as in the `SOCKET` column of `connections`. `filetrace inspect socket <id>` takes it.

**local\_ip** `string`

Local address. Omitted when unknown.

**local\_port** `integer`

Local port. Omitted when unknown.

**remote\_ip** `string`

Remote address. Omitted when unknown, such as on a UDP socket that sends to several peers.

**remote\_port** `integer`

Remote port. Omitted when unknown.

**remote\_host** `string`

Host name of the remote address. Only with `--resolve-hostnames`, and only where a reverse lookup found a name.

**transfer** `object`

What was sent and how sure the association is.

**transfer**

**method** `string`

`sendfile` or `read-write`. Omitted in `network_transfer` records.

**bytes\_sent** `integer`

Bytes the socket accepted from this file (for `network_transfer`, bytes it accepted that no file accounts for).

**bytes\_read** `integer`

Bytes the thread read from the file. Only for `read-write`.

**bytes\_per\_second** `integer`

Current rate.

**operations** `integer`

Number of sends that carried the file's bytes. Omitted in `network_transfer` records.

**started** `string`

When the first byte was sent.

**duration\_ms** `integer`

Milliseconds from the first to the latest byte.

**state** `string`

`active` when bytes were sent within the last five seconds, otherwise `completed`.

**confidence** `string`

`exact`, `inferred` or `unknown`. `strong` is defined but no probe produces it. A filter or output format never raises the level. See [File attribution and confidence](https://filetrace.mintlify.site/concepts/attribution.md).

**evidence** `string[]`

The observations behind the confidence, from the table below. Omitted when empty.

**incomplete** `boolean`

`true` when events were lost while the transfer was in progress, so its byte count may be low. The table formats mark such a transfer with `*` after its confidence.

| Evidence | Meaning |
| - | - |
| `direct_file_to_socket_transfer` | The kernel moved the file's data to the socket in a single operation. |
| `file_identity` | The file was identified by device and inode from the kernel file object. |
| `socket_identity` | The socket was identified by its kernel socket cookie. |
| `remote_endpoint` | The socket identity resolved to the remote endpoint. |
| `thread_read_then_send` | One thread read the file and then sent on the socket with no receive in between. |
| `repeated_read_then_send` | The read-then-send sequence repeated. |
| `byte_balance` | The bytes sent are close to the bytes read from the file. |

## Process records

`processes` prints one record per process with network activity. `top` and `top processes` print the same records, highest outbound traffic first. One record of `filetrace processes --json`, formatted for reading:

```json theme={null}
{
  "pid": 1024,
  "ppid": 772,
  "name": "file-server",
  "user": "root",
  "uid": 0,
  "gid": 0,
  "executable": "/usr/local/bin/file-server",
  "bytes_sent": 16250000,
  "bytes_received": 0,
  "bytes_sent_per_second": 4227370,
  "bytes_received_per_second": 0,
  "connections": 2,
  "files": 1,
  "transfers": 1,
  "active_transfers": 1,
  "started": "2026-11-11T20:07:56.180Z",
  "status": "running",
  "cgroup_id": 631,
  "pid_namespace": 4026531836,
  "mount_namespace": 4026532557,
  "network_namespace": 4026532561
}
```

**pid** `integer`

Process ID. `--format quiet` prints this field.

**ppid** `integer`

Parent process ID.

**name** `string`

The kernel's name for the process.

**user** `string`

User name, or the numeric user ID when it has no name.

**uid** `integer`

User ID.

**gid** `integer`

Group ID.

**executable** `string`

Path of the executable. Omitted when unknown.

**bytes\_sent** `integer`

Bytes the process's sockets accepted, since the agent first saw the process.

**bytes\_received** `integer`

Bytes its sockets delivered to it.

**bytes\_sent\_per\_second** `integer`

Current outbound rate.

**bytes\_received\_per\_second** `integer`

Current inbound rate.

**connections** `integer`

Open sockets the process owns.

**files** `integer`

Distinct files it sent. A file sent over several sockets counts once.

**transfers** `integer`

Reported transfers.

**active\_transfers** `integer`

Transfers with bytes within the last five seconds.

**started** `string`

When the process started. Omitted when unknown.

**status** `string`

`running` or `exited`.

**cgroup\_id** `integer`

The cgroup's ID, which `--cgroup` takes. Omitted when unknown.

**pid\_namespace** `integer`

Inode number of the PID namespace, which `--namespace` takes. Omitted when unknown.

**mount\_namespace** `integer`

Inode number of the mount namespace. Omitted when unknown.

**network\_namespace** `integer`

Inode number of the network namespace. Omitted when unknown.

With `processes --include-children`, the byte counts, rates and counts of a process include those of its descendants.

## Connection records

`connections` prints one record per socket. One record of `filetrace connections --json`, formatted for reading:

```json theme={null}
{
  "socket_id": 16,
  "protocol": "tcp",
  "pid": 1024,
  "process": "file-server",
  "local_ip": "127.0.0.1",
  "local_port": 41814,
  "remote_ip": "127.0.0.1",
  "remote_port": 51871,
  "state": "established",
  "bytes_sent": 16250000,
  "bytes_received": 0,
  "bytes_sent_per_second": 4217235,
  "bytes_received_per_second": 0,
  "first_seen": "2026-11-11T20:07:56.193Z",
  "last_seen": "2026-11-11T20:07:59.514Z"
}
```

**socket\_id** `integer`

The socket's ID. `filetrace inspect socket <id>` takes it, and `--format quiet` prints it.

**protocol** `string`

`tcp` or `udp`.

**pid** `integer`

Process that owns the socket. Omitted when there is none yet: an accepted connection has no owning process until that process sends or receives on it.

**process** `string`

The owning process's name. Omitted with `pid`.

**local\_ip, local\_port, remote\_ip, remote\_port** `string, integer`

The two ends. Each is omitted when unknown.

**remote\_host** `string`

Host name of the remote address, with `--resolve-hostnames`.

**state** `string`

`connecting`, `established`, `listening` or `closed` for TCP. For UDP, `active`, or `idle` after 30 seconds without traffic.

**bytes\_sent, bytes\_received** `integer`

Bytes the socket accepted and delivered.

**bytes\_sent\_per\_second, bytes\_received\_per\_second** `integer`

Current rates.

**first\_seen, last\_seen** `string`

When the agent first and last saw the socket.

## Flow records

`flows` prints one record per flow: one process's traffic with one remote endpoint on one socket. `top connections` prints the same records. One record of `filetrace flows --json`, formatted for reading:

```json theme={null}
{
  "flow_id": 12,
  "socket_id": 3,
  "protocol": "tcp",
  "pid": 1014,
  "process": "file-server",
  "local_ip": "127.0.0.1",
  "local_port": 43090,
  "remote_ip": "127.0.0.1",
  "remote_port": 34477,
  "bytes_sent": 50000000,
  "bytes_received": 0,
  "bytes_sent_per_second": 0,
  "bytes_received_per_second": 0,
  "send_operations": 763,
  "receive_operations": 0,
  "first_seen": "2026-11-11T20:07:56.059Z",
  "last_seen": "2026-11-11T20:07:56.063Z"
}
```

**flow\_id** `integer`

The flow's ID. `filetrace inspect flow <id>` takes it, and `--format quiet` prints it.

**socket\_id** `integer`

The socket the flow belongs to.

**protocol, pid, process** `string, integer, string`

As in connection records.

**local\_ip, local\_port, remote\_ip, remote\_port, remote\_host** `string, integer`

The two ends, as in connection records.

**bytes\_sent, bytes\_received, bytes\_sent\_per\_second, bytes\_received\_per\_second** `integer`

Byte counts and current rates of this flow.

**send\_operations, receive\_operations** `integer`

Number of sends and receives counted on the flow.

**first\_seen, last\_seen** `string`

When the flow's first and latest bytes were seen.

## Top and grouped flows

`top processes` (the default subject) prints [process records](#process-records) and `top connections` prints [flow records](#flow-records). `top files`, `top destinations` and `flows --group-by` print group records, in which every value of the grouping key is a string:

| Command | Key | Other fields |
| - | - | - |
| `top files` | `file` | `bytes_sent`, `transfers`, `confidence` |
| `top destinations` | `remote_ip` | `bytes_sent`, `bytes_received`, `flows` |
| `flows --group-by process` | `process` | `bytes_sent`, `bytes_received`, `flows` |
| `flows --group-by remote` | `remote_ip` | `bytes_sent`, `bytes_received`, `flows` |
| `flows --group-by port` | `remote_port` | `bytes_sent`, `bytes_received`, `flows` |
| `flows --group-by protocol` | `protocol` | `bytes_sent`, `bytes_received`, `flows` |

**file** `string`

The file's path, or `(device <n> inode <n>)` when the path is not known.

**remote\_ip** `string`

The remote address, or its host name with `flows --group-by remote --resolve-hostnames` where a reverse lookup found one.

**bytes\_sent, bytes\_received** `integer`

Sums over the group.

**transfers, flows** `integer`

Number of transfers or flows in the group.

**confidence** `string`

The lowest confidence among the file's transfers: a group is only as certain as its least certain member.

## inspect

`inspect --format json` prints one object. Every report has `kind`, the arrays and objects listed for it, and two closing fields:

**kind** `string`

`file`, `process`, `socket`, `flow` or `ip`.

**observed\_since** `string`

When the agent's history starts. Nothing earlier is kept.

**events\_lost** `integer`

Events lost within the report's time range. Nonzero values also make the command exit with code 9.

| Kind | Fields |
| - | - |
| `file` | `path`; `totals` with `bytes_sent`, `transfers`, `active_transfers`, `destinations`, `processes`; `provenance` with `methods` (`sendfile`, `read-write`) and `confidence` (`exact`, `strong`, `inferred`, `unknown`) counts; `transfers`, an array of [transfer records](#transfer-records) |
| `process` | `pid`; `process`, a [process record](#process-records), when the agent knows the process; `cgroup` (path) and `open_files` (count) while the process runs; `destinations`, an array of objects with `remote_ip`, `bytes_sent`, `bytes_received`, `bytes_sent_per_second`; `transfers` |
| `socket` | `socket_id`; `connection`, a [connection record](#connection-records), when the socket is known; `flows`, an array of [flow records](#flow-records); `transfers` |
| `flow` | `flow_id`; `flow`, a [flow record](#flow-records), when the flow is known; `transfers` |
| `ip` | `network`, the address or network given; `totals` with `bytes_sent`, `bytes_received`, `bytes_sent_per_second`, `flows`, `processes`, `transfers`; `processes`, an array of objects with `pid`, `name`, `bytes_sent`, `bytes_received`, `bytes_sent_per_second`; `transfers` |

A file report prints its transfers one per line, like a listing:

```bash theme={null}
filetrace inspect file /srv/export/media/files/video.mp4 --json
```

```text theme={null}
{"kind":"file","path":"/srv/export/media/files/video.mp4","totals":{"bytes_sent":50000000,"transfers":1,"active_transfers":1,"destinations":1,"processes":1},"provenance":{"methods":{"sendfile":1,"read-write":0},"confidence":{"exact":1,"strong":0,"inferred":0,"unknown":0}},"transfers":[
 {"event":"file_transfer","transfer_id":"tr_1","timestamp":"2026-11-11T20:07:56.063Z","host":"web-01","platform":"linux","process":{"pid":1014,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/video.mp4","inode":626324,"device":63,"size":50000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":3,"local_ip":"127.0.0.1","local_port":43090,"remote_ip":"127.0.0.1","remote_port":34477},"transfer":{"method":"sendfile","bytes_sent":50000000,"bytes_per_second":0,"operations":1,"started":"2026-11-11T20:07:56.063Z","duration_ms":0,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
],"observed_since":"2026-11-11T20:07:55.984Z","events_lost":0}
```

## stats

`stats --format json` prints one object with the agent's own statistics, whatever section is named. With `--watch` it prints one object per interval, each on its own line. `filetrace stats --json`, formatted for reading:

```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
  }
}
```

**status** `string`

`healthy`, or `degraded` while the agent has lost events within the last minute. `stats` exits with code 9 while it is `degraded`.

**backend, mode, version, pid** `string, string, string, integer`

The collection backend and the probe set it settled on, `standard` or `minimal`, the agent's version and its process ID.

**started, uptime\_seconds** `string, integer`

When the agent started and how long it has run.

**events** `object`

Events from the kernel.

**events**

**received** `integer`

Events the kernel produced, including the ones that were lost.

**processed** `integer`

Events the agent applied to its tables.

**dropped** `integer`

Events lost, the sum of the three causes below.

**per\_second** `number`

Recent event rate, with three decimals.

**dropped\_queue\_overflow** `integer`

Lost because the kernel-to-agent queue (`[agent] ring_buffer_size`) was full.

**dropped\_counter\_table\_full** `integer`

Lost because the kernel counter table (`[limits] kernel_counters`) was full.

**dropped\_socket\_unidentified** `integer`

Lost because a transfer's socket had no usable identity.

**resources** `object`

The agent's own use: `cpu_percent` (three decimals), `memory_bytes` (resident memory) and `open_fds`.

**collector** `object`

Queues, the event log and the bounded tables.

**collector**

**event\_queue\_bytes, event\_queue\_peak\_bytes** `integer`

Size of the kernel-to-agent queue and the most it has held.

**candidates\_below\_threshold** `integer`

Read-write associations not reported because they are below the confidence or inference thresholds.

**event\_log\_bytes, event\_log\_events, event\_log\_discarded** `integer`

Size of the event log, the events it holds, and the older events it has discarded to make room.

**processes, sockets, flows, files, transfers** `object`

Each table's `entries`, `capacity` (from `[limits]`) and `evictions`, the entries it forgot to make room.

**network** `object`

Totals since the agent started: `bytes_sent`, `bytes_received`, their current rates, `open_sockets`, `active_flows` and `active_transfers`.

## capabilities

`capabilities --format json` prints an array with one object per feature.

```bash theme={null}
filetrace capabilities --json
```

```text theme={null}
[
 {"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"}
]
```

**feature** `string`

The feature's key. The list above is complete.

**status** `string`

`FULL`, `PARTIAL`, `UNAVAILABLE` or `DISABLED` (turned off by the mode or the configuration).

**detail** `string`

Why the status is what it is. Omitted when there is nothing to add.

## doctor

`doctor --format json` prints one object. Its exit code matches `status`. Formatted for reading, with some probes and features left out:

```json theme={null}
{
  "status": "ready",
  "platform": "Linux",
  "kernel": "7.0.14-linuxkit",
  "architecture": "aarch64",
  "backend": "Linux eBPF (trampolines)",
  "checks": [
    {"name": "BTF", "status": "ok"},
    {"name": "CAP_BPF", "status": "ok"},
    {"name": "CAP_PERFMON", "status": "ok"},
    {"name": "BPF", "status": "ok", "detail": "libbpf v1.5"},
    {"name": "BPF trampolines", "status": "ok"},
    {"name": "BPF programs", "status": "ok", "detail": "loaded; every kernel field they read was found"}
  ],
  "probes": [
    {"name": "tracepoint sched_process_exec", "status": "ok"},
    {"name": "fexit inet_sendmsg", "status": "ok"},
    {"name": "fexit vfs_read", "status": "ok"},
    {"name": "fexit do_splice_direct", "status": "ok"},
    {"name": "fentry __destroy_inode", "status": "ok"}
  ],
  "features": [
    {"feature": "process_tracking", "status": "FULL"},
    {"feature": "sendfile_attribution", "status": "FULL"}
  ],
  "agent": {"state": "stopped"}
}
```

**status** `string`

`ready` (exit code 0), `needs_privileges` (3), `unavailable` (5) or `degraded` (9: some probes are missing, or the agent is losing events).

**platform, kernel, architecture, backend** `string`

The machine, and the backend with the probe set it would use.

**checks** `object[]`

Requirements such as BTF, capabilities and BPF support, each with `name`, `status` (`ok`, `warn` or `fail`) and an optional `detail`.

**probes** `object[]`

Every instrumentation point, loaded and attached for the check, in the same form as `checks`.

**features** `object[]`

The features the attached probes add up to, in the form of [capabilities](#capabilities).

**agent** `object`

`state` is `running`, `stopped` or `unreachable` (running, but its socket is not accessible to this user). A running agent adds `pid`, `mode`, `events_received`, `events_dropped`, `ring_buffer_bytes` and `event_log_bytes`.

## Events

`filetrace events --format json` and `--format jsonl` print the agent's event records. Each has `event`, `timestamp` and `sequence`, then the `process`, `file`, `network`, `transfer` or `loss` groups its type carries. [Event types](https://filetrace.mintlify.site/reference/event-types.md) describes them.


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