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 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.
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,transfersorinspect; an event ofeventsuses the same groups for the part it shares. - Host names. With
--resolve-hostnames, connection, flow and transfer records gain aremote_hostfield 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.
--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:
filetrace transfers --json, formatted for reading:
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.string
file_transfer for bytes associated with a file. network_transfer for bytes a socket sent that no file accounts for.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).string
When the transfer’s latest bytes were sent.
string
The host name of the machine.
string
The operating system,
linux.object
The process that sent the bytes.
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.object
The socket the bytes were sent on.
object
What was sent and how sure the association is.
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:
integer
Process ID.
--format quiet prints this field.integer
Parent process ID.
string
The kernel’s name for the process.
string
User name, or the numeric user ID when it has no name.
integer
User ID.
integer
Group ID.
string
Path of the executable. Omitted when unknown.
integer
Bytes the process’s sockets accepted, since the agent first saw the process.
integer
Bytes its sockets delivered to it.
integer
Current outbound rate.
integer
Current inbound rate.
integer
Open sockets the process owns.
integer
Distinct files it sent. A file sent over several sockets counts once.
integer
Reported transfers.
integer
Transfers with bytes within the last five seconds.
string
When the process started. Omitted when unknown.
string
running or exited.integer
The cgroup’s ID, which
--cgroup takes. Omitted when unknown.integer
Inode number of the PID namespace, which
--namespace takes. Omitted when unknown.integer
Inode number of the mount namespace. Omitted when unknown.
integer
Inode number of the network namespace. Omitted when unknown.
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:
integer
The socket’s ID.
filetrace inspect socket <id> takes it, and --format quiet prints it.string
tcp or udp.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.
string
The owning process’s name. Omitted with
pid.string, integer
The two ends. Each is omitted when unknown.
string
Host name of the remote address, with
--resolve-hostnames.string
connecting, established, listening or closed for TCP. For UDP, active, or idle after 30 seconds without traffic.integer
Bytes the socket accepted and delivered.
integer
Current rates.
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:
integer
The flow’s ID.
filetrace inspect flow <id> takes it, and --format quiet prints it.integer
The socket the flow belongs to.
string, integer, string
As in connection records.
string, integer
The two ends, as in connection records.
integer
Byte counts and current rates of this flow.
integer
Number of sends and receives counted on the flow.
string
When the flow’s first and latest bytes were seen.
Top and grouped flows
top processes (the default subject) prints process records and top connections prints flow records. top files, top destinations and flows --group-by print group records, in which every value of the grouping key is a string:
string
The file’s path, or
(device <n> inode <n>) when the path is not known.string
The remote address, or its host name with
flows --group-by remote --resolve-hostnames where a reverse lookup found one.integer
Sums over the group.
integer
Number of transfers or flows in the group.
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:
string
file, process, socket, flow or ip.string
When the agent’s history starts. Nothing earlier is kept.
integer
Events lost within the report’s time range. Nonzero values also make the command exit with code 9.
A file report prints its transfers one per line, like a listing:
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:
string
healthy, or degraded while the agent has lost events within the last minute. stats exits with code 9 while it is degraded.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.string, integer
When the agent started and how long it has run.
object
Events from the kernel.
object
The agent’s own use:
cpu_percent (three decimals), memory_bytes (resident memory) and open_fds.object
Queues, the event log and the bounded tables.
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.
string
The feature’s key. The list above is complete.
string
FULL, PARTIAL, UNAVAILABLE or DISABLED (turned off by the mode or the configuration).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:
string
ready (exit code 0), needs_privileges (3), unavailable (5) or degraded (9: some probes are missing, or the agent is losing events).string
The machine, and the backend with the probe set it would use.
object[]
Requirements such as BTF, capabilities and BPF support, each with
name, status (ok, warn or fail) and an optional detail.object[]
Every instrumentation point, loaded and attached for the check, in the same form as
checks.object[]
The features the attached probes add up to, in the form of capabilities.
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 describes them.