FiletraceService gRPC API reference

This is the complete reference of filetrace.v1.FiletraceService, the gRPC API that the Filetrace agent serves when [grpc] enabled = true. It lists each RPC with its request and response, every message with every field, and every enum value. The schema is defined in proto/filetrace/v1/filetrace.proto; the gRPC API guide shows how to enable the API and call it.

Service

The package is filetrace.v1, in proto3 syntax.

// What a Filetrace agent has observed on its host: which files were sent over
// the network, by which process, and where they went.
service FiletraceService {
  // The agent's identity, health and totals.
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);

  // The transfers the agent holds, each covering its whole observed lifetime.
  rpc ListTransfers(ListTransfersRequest) returns (ListTransfersResponse);

  // Transfer activity as the agent records it, until the caller cancels.
  rpc WatchTransfers(WatchTransfersRequest) returns (stream WatchTransfersResponse);
}

RPC	Kind	Path
`GetStatus`	Unary	`/filetrace.v1.FiletraceService/GetStatus`
`ListTransfers`	Unary	`/filetrace.v1.FiletraceService/ListTransfers`
`WatchTransfers`	Server streaming	`/filetrace.v1.FiletraceService/WatchTransfers`

Times are fixed64 nanoseconds since the Unix epoch. In proto3, a field at its zero value (0, an empty string, false, the _UNSPECIFIED enum value) cannot be told apart from one that was not set; the descriptions say where a zero value or an absent message means that something is not known.

GetStatus

The agent’s identity, health and totals. The request, GetStatusRequest, has no fields.

GetStatusResponse

string

The agent’s version.

string

The host name of the machine the agent runs on.

string

"linux", "macos" or "freebsd".

string

The collection backend and how it instruments the kernel, as filetrace agent status shows it, such as Linux eBPF (trampolines).

string

"minimal" or "standard".

fixed64

When the agent started. Nothing earlier than this is known to the agent.

bool

Events were lost within the last minute.

uint64

Events the agent took from the kernel since it started.

uint64

Events lost before the agent could record them since it started, of every loss kind.

uint64

Bytes that local sockets accepted from processes since the agent started.

uint64

Bytes that local sockets delivered to processes since the agent started.

uint32

File transfers in progress.

uint32

Processes with network traffic in the last few seconds.

uint32

Sockets that are open or have recent traffic.

ListTransfers

The transfers the agent holds, each covering its whole observed lifetime, most recently active first.

ListTransfersRequest

TransferFilter

Selects transfers; every field that is set narrows the result. See TransferFilter.

bool

Only transfers still in progress.

bool

Also list sent bytes that no file accounts for, one entry per socket, as CONFIDENCE_UNKNOWN with no file. They are left out when the filter sets path, method, or a confidence other than CONFIDENCE_UNKNOWN.

uint64

Smallest number of bytes sent.

uint32

default:"1000"

The most transfers to return, most recently active first. At most 1000, which is also what 0 asks for; a larger value returns 1000.

ListTransfersResponse

repeated Transfer

The transfers. See Transfer.

fixed64

Nothing earlier than this is known to the agent.

uint64

Events the agent lost so far. Above zero, the list may be incomplete.

A response larger than 4 MB is not sent: the call fails with RESOURCE_EXHAUSTED and asks for a filter or a limit.

WatchTransfers

Transfer activity as the agent records it, from the moment the call starts until the caller cancels. Each response message carries one event.

WatchTransfersRequest

TransferFilter

Selects events; every field that is set narrows the stream. A confidence filter passes only events that have exactly that level. See TransferFilter.

WatchTransfersResponse

TransferEvent

The file bytes attributed to one socket during one collection interval. See TransferEvent.

uint64

Events left out before this one because the caller read too slowly: once more than 1 MB is waiting unread on the stream, the agent sends nothing further until the reader catches up.

Messages

Transfer

One transfer over its whole observed lifetime, as filetrace files lists it.

uint64

The transfer’s ID. For sent bytes that no file accounts for, it is the socket’s ID. The command-line interface shows the same number in hexadecimal, as tr_<hex> for a transfer and tr_s<hex> for unattributed bytes.

Process

The process that sent the bytes. See Process.

File

The file. Absent for sent bytes that no file accounts for. See File.

Connection

The socket the bytes were sent on. See Connection.

Method

The system calls that carried the file to the socket. METHOD_UNSPECIFIED for unattributed bytes.

Confidence

How sure the agent is that the bytes came from the file. CONFIDENCE_UNKNOWN for unattributed bytes.

repeated string

What the confidence rests on. Empty for unattributed bytes.

Show evidence values

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

uint64

Bytes the local socket accepted; not bytes on the wire.

uint64

Bytes the sending thread read from the file. Set for METHOD_READ_WRITE.

uint64

Rate over the last one to two seconds.

uint64

Send operations that carried the transfer’s bytes. 0 for unattributed bytes.

fixed64

When the transfer was first observed.

fixed64

When the transfer was last observed.

bool

The transfer is still in progress.

bool

Events were lost while the transfer was in progress, so its counts may be short.

TransferEvent

File bytes attributed to a socket during one collection interval, as filetrace events --type file_transfer prints them. The bytes of a transfer’s events add up to the transfer.

uint64

Increases with every record the agent makes. Records of other types and events outside the filter take numbers too, so consecutive messages can skip values.

fixed64

When the agent recorded the event.

Process

The sending process. executable is always empty in an event. See Process.

File

The file: path, inode, device, size and deleted are set; owner_uid, filesystem and path_truncated are not. See File.

Connection

The socket the bytes were sent on. See Connection.

Method

The system calls that carried the bytes.

Confidence

That of the whole association so far. CONFIDENCE_UNSPECIFIED while the association is below the reporting thresholds.

uint64

Bytes the socket accepted during the interval.

uint64

Bytes the sending thread read from the file during the interval. Set for METHOD_READ_WRITE.

TransferFilter

Every field that is set narrows the result; a field at its zero value does not filter. A value that cannot be applied ends the call with INVALID_ARGUMENT.

uint32

Process ID.

string

Process name; * matches any run of characters.

string

File path; * matches any run of characters, / included.

string

Remote address or CIDR network, such as "203.0.113.0/24".

uint32

Local or remote port, up to 65535.

Transport

TRANSPORT_TCP or TRANSPORT_UDP.

Method

METHOD_SENDFILE or METHOD_READ_WRITE.

Confidence

Exactly this level.

Process

uint32

Process ID.

uint32

Parent process ID.

string

The kernel’s name for the process, at most 15 bytes.

string

Path of the executable; empty when it was not observed.

File

A file is identified by device and inode; the other fields describe it as it was when first seen.

string

Empty when the path is not known.

uint64

Inode number.

uint64

Device number of the file system that holds the file.

uint64

Size in bytes when the file was first seen.

uint32

User ID of the file’s owner.

string

File system type, such as overlay.

bool

The file has no remaining links.

bool

The path was longer than the agent keeps.

Connection

uint64

Stable for the lifetime of the socket; the SOCKET column and socket_id field of the commands.

Transport

TRANSPORT_TCP or TRANSPORT_UDP; TRANSPORT_UNSPECIFIED for any other protocol, or when the protocol is not known.

Endpoint

The local end. Absent when neither its address nor its port is known.

Show Endpoint

string

An IPv4 or IPv6 address in text form; empty when not known.

uint32

Port number.

Endpoint

The remote end. Absent when neither its address nor its port is known. Same fields as local.

Endpoint

string

An IPv4 or IPv6 address in text form; empty when not known.

uint32

Port number.

Enums

Confidence

How sure the agent is that the bytes of a transfer came from the file. Attribution and confidence explains the levels.

Value	Number	Meaning
`CONFIDENCE_UNSPECIFIED`	0	Not given. In a filter: any level. In a `TransferEvent`: the association is below the reporting thresholds
`CONFIDENCE_UNKNOWN`	1	Bytes were sent and no file could be associated with them
`CONFIDENCE_INFERRED`	2	A thread read the file and then sent on the socket
`CONFIDENCE_STRONG`	3	Provenance followed through intermediate operations. Defined, but no probe produces it
`CONFIDENCE_EXACT`	4	The kernel moved the file’s data to the socket in one operation

Method

The system calls that carried a file to a socket.

Value	Number	Meaning
`METHOD_UNSPECIFIED`	0	Not given. In a filter: any method. In a `Transfer`: sent bytes that no file accounts for
`METHOD_SENDFILE`	1	`sendfile`
`METHOD_READ_WRITE`	2	A read of the file followed by a send

Transport

Value	Number	Meaning
`TRANSPORT_UNSPECIFIED`	0	Not given. In a filter: any transport. In a `Connection`: another protocol, or not known
`TRANSPORT_TCP`	1	TCP
`TRANSPORT_UDP`	2	UDP

​Service

​GetStatus

​GetStatusResponse

​ListTransfers

​ListTransfersRequest

​ListTransfersResponse

​WatchTransfers

​WatchTransfersRequest

​WatchTransfersResponse

​Messages

​Transfer

​TransferEvent

​TransferFilter

​Process

​File

​Connection

​Endpoint

​Enums

​Confidence

​Method

​Transport

Service

GetStatus

GetStatusResponse

ListTransfers

ListTransfersRequest

ListTransfersResponse

WatchTransfers

WatchTransfersRequest

WatchTransfersResponse

Messages

Transfer

TransferEvent

TransferFilter

Process

File

Connection

Endpoint

Enums

Confidence

Method

Transport