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

# FiletraceService gRPC API reference

> Every RPC, message, field and enum value of filetrace.v1.FiletraceService, the gRPC API of the Filetrace agent, with what each field holds and when it is empty.

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`](https://github.com/OrlovEvgeny/filetrace/blob/master/proto/filetrace/v1/filetrace.proto); the [gRPC API guide](https://filetrace.mintlify.site/integrations/grpc-api.md) shows how to enable the API and call it.

## Service

The package is `filetrace.v1`, in proto3 syntax.

```protobuf theme={null}
// 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

**version** `string`

The agent's version.

**host** `string`

The host name of the machine the agent runs on.

**platform** `string`

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

**backend** `string`

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

**mode** `string`

`"minimal"` or `"standard"`.

**start\_time\_unix\_nano** `fixed64`

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

**degraded** `bool`

Events were lost within the last minute.

**events\_processed** `uint64`

Events the agent took from the kernel since it started.

**events\_dropped** `uint64`

Events lost before the agent could record them since it started, of every [loss kind](https://filetrace.mintlify.site/integrations/telemetry-reference.md#loss-kinds).

**bytes\_sent** `uint64`

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

**bytes\_received** `uint64`

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

**active\_transfers** `uint32`

File transfers in progress.

**active\_processes** `uint32`

Processes with network traffic in the last few seconds.

**open\_connections** `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

**filter** `TransferFilter`

Selects transfers; every field that is set narrows the result. See [TransferFilter](#transferfilter).

**active\_only** `bool`

Only transfers still in progress.

**include\_unattributed** `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`.

**min\_bytes** `uint64`

Smallest number of bytes sent.

**limit** `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

**transfers** `repeated Transfer`

The transfers. See [Transfer](#transfer).

**observed\_since\_unix\_nano** `fixed64`

Nothing earlier than this is known to the agent.

**lost\_events** `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

**filter** `TransferFilter`

Selects events; every field that is set narrows the stream. A `confidence` filter passes only events that have exactly that level. See [TransferFilter](#transferfilter).

### WatchTransfersResponse

**event** `TransferEvent`

The file bytes attributed to one socket during one collection interval. See [TransferEvent](#transferevent).

**missed** `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`](https://filetrace.mintlify.site/cli/files) lists it.

**id** `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** `Process`

The process that sent the bytes. See [Process](#process).

**file** `File`

The file. Absent for sent bytes that no file accounts for. See [File](#file).

**connection** `Connection`

The socket the bytes were sent on. See [Connection](#connection).

**method** `Method`

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

**confidence** `Confidence`

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

**evidence** `repeated string`

What the confidence rests on. Empty for unattributed bytes.

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

**bytes\_sent** `uint64`

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

**bytes\_read** `uint64`

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

**bytes\_per\_second** `uint64`

Rate over the last one to two seconds.

**operations** `uint64`

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

**start\_time\_unix\_nano** `fixed64`

When the transfer was first observed.

**last\_time\_unix\_nano** `fixed64`

When the transfer was last observed.

**active** `bool`

The transfer is still in progress.

**incomplete** `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`](https://filetrace.mintlify.site/cli/events) prints them. The bytes of a transfer's events add up to the transfer.

**sequence** `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.

**time\_unix\_nano** `fixed64`

When the agent recorded the event.

**process** `Process`

The sending process. `executable` is always empty in an event. See [Process](#process).

**file** `File`

The file: `path`, `inode`, `device`, `size` and `deleted` are set; `owner_uid`, `filesystem` and `path_truncated` are not. See [File](#file).

**connection** `Connection`

The socket the bytes were sent on. See [Connection](#connection).

**method** `Method`

The system calls that carried the bytes.

**confidence** `Confidence`

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

**bytes\_sent** `uint64`

Bytes the socket accepted during the interval.

**bytes\_read** `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`.

**pid** `uint32`

Process ID.

**process** `string`

Process name; `*` matches any run of characters.

**path** `string`

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

**remote** `string`

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

**port** `uint32`

Local or remote port, up to 65535.

**transport** `Transport`

`TRANSPORT_TCP` or `TRANSPORT_UDP`.

**method** `Method`

`METHOD_SENDFILE` or `METHOD_READ_WRITE`.

**confidence** `Confidence`

Exactly this level.

### Process

**pid** `uint32`

Process ID.

**parent\_pid** `uint32`

Parent process ID.

**name** `string`

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

**executable** `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.

**path** `string`

Empty when the path is not known.

**inode** `uint64`

Inode number.

**device** `uint64`

Device number of the file system that holds the file.

**size** `uint64`

Size in bytes when the file was first seen.

**owner\_uid** `uint32`

User ID of the file's owner.

**filesystem** `string`

File system type, such as `overlay`.

**deleted** `bool`

The file has no remaining links.

**path\_truncated** `bool`

The path was longer than the agent keeps.

### Connection

**socket\_id** `uint64`

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

**transport** `Transport`

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

**local** `Endpoint`

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

**Endpoint**

**address** `string`

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

**port** `uint32`

Port number.

**remote** `Endpoint`

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

### Endpoint

**address** `string`

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

**port** `uint32`

Port number.

## Enums

### Confidence

How sure the agent is that the bytes of a transfer came from the file. [Attribution and confidence](https://filetrace.mintlify.site/concepts/attribution.md) 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 |


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