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

# Event types of filetrace events

> The twelve event types the agent records, when each one is recorded, the fields it carries in text, JSON and raw output, the bounded event log, and OTLP export.

The agent records what it observes as a sequence of events: processes starting and exiting, TCP sockets changing state, files being seen, bytes sent and received, file bytes attributed to a socket, and events it lost. `filetrace events` prints them in order, and the OpenTelemetry exporter can send them as log records. This page lists the twelve event types, when each is recorded and which fields it carries, and explains the bounded log that holds them.

## How events are recorded

Process and socket lifecycle events travel from the kernel to the agent through a ring buffer and are recorded as they happen.

Byte counts never become one event per system call. They accumulate in a kernel table keyed by socket, process and file, and the agent collects them every `[agent] flush_interval` (250 ms by default). A `network_send`, `network_receive` or `file_transfer` event therefore carries the bytes of one collection interval. A long transfer produces one `file_transfer` event per interval in which it moved bytes, and the bytes of those events add up to the transfer's `bytes_sent` in `filetrace files`.

Not recorded at all:

* file opens and closes, file writes, and individual system calls;
* the processes that `[filters] exclude_processes` matches, and the transfers of files that `[filters] exclude_paths` matches;
* sockets of a protocol or address family turned off in [`[network]`](https://filetrace.mintlify.site/reference/configuration#network).

## The event log

Past events come from a log in the agent's memory. It has a fixed size, `[agent] event_log_size` (1 MB by default, 256 KB in minimal mode), starts empty when the agent starts and holds only the most recent events. The log is divided into three shares, so that a flood of one kind of event does not push out the others:

| Share | Event types |
| - | - |
| One half | `file_seen`, `file_transfer`, `event_loss` |
| Three eighths | `socket_connect`, `socket_listen`, `socket_established`, `socket_close`, `network_send`, `network_receive` |
| One eighth | `process_exec`, `process_fork`, `process_exit` |

When a share is full, its oldest events are discarded to make room. `filetrace stats buffers` shows the log's size, how many events it holds and how many it has discarded, and the table output of `filetrace events` ends with how far back the log reaches:

```text theme={null}
4 events. The event log reaches back to 2026-11-11 20:07:55; it is kept in memory
and holds only the most recent events.
```

With `event_log_size = 0` the agent keeps no log; `filetrace events --follow` still prints new events as they happen.

## Summary

| Type | Recorded when | Groups |
| - | - | - |
| `process_exec` | A process runs a new program | `process` |
| `process_fork` | A new process is created (threads are not reported) | `process` |
| `process_exit` | A process exits, once its last thread is gone | `process` |
| `socket_connect` | A TCP socket starts an outgoing connection | `process`, `network` |
| `socket_listen` | A TCP socket starts listening | `process`, `network` |
| `socket_established` | A TCP connection is established, outgoing or accepted | `process`, `network` |
| `socket_close` | A TCP socket the agent knows of is closed | `process`, `network` |
| `file_seen` | A file is read or sent for the first time | `file` |
| `network_send` | A socket accepted bytes during a collection interval | `process`, `network` |
| `network_receive` | A socket delivered bytes during a collection interval | `process`, `network` |
| `file_transfer` | File bytes were attributed to a socket during a collection interval | `process`, `file`, `network`, `transfer` |
| `event_loss` | The agent could not record some events | `loss` |

`process` is left out when the event has no owning process. An accepted connection, for example, has no owning process until that process sends or receives on it.

## Common fields

Every event in JSON and JSON Lines starts with these fields. The groups that follow use the same keys as the [transfer records](https://filetrace.mintlify.site/reference/json-output.md#transfer-records) of `filetrace files`.

**event** `string`

The event type.

**timestamp** `string`

RFC 3339 time in UTC with milliseconds. For byte counts, it is when the last byte of the interval was counted.

**sequence** `integer`

Increases with every event the agent records. Gaps mean that a filter left events out or that the log discarded them.

## Process events

`process_exec`, `process_fork` and `process_exit` describe the life of a process. The `process` group carries:

**pid** `integer`

Process ID.

**ppid** `integer`

Parent process ID. Omitted when unknown.

**name** `string`

The kernel's name for the process. Omitted when unknown.

**executable** `string`

Path of the executable. Omitted when unknown, such as for a forked process whose parent's executable the agent never saw.

**exit\_status** `integer`

Only in `process_exit`: the exit status of a process that exited.

**signal** `integer`

Only in `process_exit`: the signal that ended the process, in place of `exit_status`.

```bash theme={null}
filetrace events --type process_exec,process_exit --limit 4 --json
```

```text theme={null}
[
 {"event":"process_exit","timestamp":"2026-11-11T20:07:58.190Z","sequence":140,"process":{"pid":1029,"ppid":1027,"name":"sed","executable":"/usr/bin/sed","exit_status":0}},
 {"event":"process_exit","timestamp":"2026-11-11T20:07:58.190Z","sequence":141,"process":{"pid":1027,"ppid":772,"name":"sh","exit_status":0}},
 {"event":"process_exec","timestamp":"2026-11-11T20:07:58.193Z","sequence":143,"process":{"pid":1030,"ppid":772,"name":"timeout","executable":"/usr/bin/timeout"}},
 {"event":"process_exec","timestamp":"2026-11-11T20:07:58.195Z","sequence":145,"process":{"pid":1031,"ppid":1030,"name":"filetrace","executable":"/usr/bin/filetrace"}}
]
```

## Socket events

`socket_connect`, `socket_listen`, `socket_established` and `socket_close` follow the state of TCP sockets, as the kernel's `inet_sock_set_state` tracepoint reports it. `socket_close` is recorded only for a socket the agent already knows. Each carries a `process` group with `pid`, `ppid` and `name` when the socket has an owner, and a `network` group:

**protocol** `string`

`tcp`.

**socket\_id** `integer`

The socket's ID, as in the `SOCKET` column of `filetrace connections`.

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

The local end. Each is omitted when unknown.

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

The remote end. Each is omitted when unknown, as for a listening socket.

## File events

`file_seen` is recorded when a file is read or sent for the first time. It describes the file only, with no process or socket. The `file` group carries:

**path** `string`

Path of the file. Omitted when it is not known.

**inode** `integer`

Inode number.

**device** `integer`

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

**size** `integer`

Size in bytes when the file was seen.

**deleted** `boolean`

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

## Network events

`network_send` and `network_receive` carry the bytes one socket accepted or delivered for one process and remote endpoint during one collection interval. An interval with no bytes in a direction produces no event for it. Byte counts are what the local socket accepted or delivered, not bytes on the wire. Each event carries a `process` group (`pid`, `ppid`, `name`) and a `network` group with `protocol` (`tcp` or `udp`), `socket_id`, the local and remote ends, and one of:

**bytes\_sent** `integer`

In `network_send`: bytes the socket accepted during the interval.

**bytes\_received** `integer`

In `network_receive`: bytes the socket delivered during the interval.

```text theme={null}
20:07:58.731 NETWORK_SEND
  pid=1024
  process=file-server
  socket=16
  protocol=tcp
  local=127.0.0.1:41814
  remote=127.0.0.1:51871
  bytes=1250000
```

## Transfer events

`file_transfer` carries the file bytes attributed to one socket during one collection interval. It has a `process` group (`pid`, `ppid`, `name`), the `file` group of `file_seen`, a `network` group with `protocol`, `socket_id` and the two ends, and a `transfer` group:

**method** `string`

`sendfile` or `read-write`.

**bytes\_sent** `integer`

File bytes the socket accepted during the interval.

**bytes\_read** `integer`

Only for `read-write`: bytes the thread read from the file during the interval.

**confidence** `string`

The confidence of the whole association so far, not of this interval alone: `exact` or `inferred`. Omitted while a read-write association is still below the reporting thresholds (`[correlation] inferred_min_bytes` and `inferred_min_percent`) or below `[correlation] confidence_threshold`. The text output shows `confidence=pending` in that case.

```bash theme={null}
filetrace events --jsonl --limit 12
```

```text theme={null}
{"event":"network_send","timestamp":"2026-11-11T20:07:58.731Z","sequence":152,"process":{"pid":1024,"ppid":772,"name":"file-server"},"network":{"protocol":"tcp","socket_id":16,"local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871,"bytes_sent":1250000}}
{"event":"network_receive","timestamp":"2026-11-11T20:07:58.732Z","sequence":153,"process":{"pid":1026,"ppid":1024,"name":"file-server"},"network":{"protocol":"tcp","socket_id":17,"local_ip":"127.0.0.1","local_port":51871,"remote_ip":"127.0.0.1","remote_port":41814,"bytes_received":1250000}}
{"event":"file_transfer","timestamp":"2026-11-11T20:07:58.732Z","sequence":154,"process":{"pid":1024,"ppid":772,"name":"file-server"},"file":{"path":"/srv/export/media/files/stream.bin","inode":626330,"device":63,"size":40000000,"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":1250000,"confidence":"exact"}}
```

```text theme={null}
20:07:58.732 FILE_TRANSFER
  pid=1024
  process=file-server
  file=/srv/export/media/files/stream.bin
  inode=626330
  socket=16
  remote=127.0.0.1:51871
  bytes=1250000
  method=sendfile
  confidence=exact
```

## Loss events

`event_loss` is recorded when the agent finds that events were lost since it last checked. Any listing whose time range includes the loss exits with code 9. The event carries a `loss` group:

**events** `integer`

How many events were lost.

**cause** `string`

Why they were lost.

| Cause | Meaning | Setting that bounds it |
| - | - | - |
| `event queue overflow` | The kernel-to-agent queue was full | `[agent] ring_buffer_size` |
| `counter table full` | The kernel table of byte counts was full | `[limits] kernel_counters` |
| `socket without identity` | A transfer's socket had no usable identity | |
| `this reader fell behind` | `filetrace events --follow` read too slowly and was not sent what it could not take | |

The last cause is sent only to the `--follow` reader concerned, in place of the events it missed. It is not stored in the log.

## Output formats

`filetrace events` prints each event as a block of `key=value` lines by default, headed by its time and type in upper case. `[output] timestamps = false` leaves the time out. `--format json` prints one array, `--format jsonl` one event per line.

`--raw` prints one line per event with every field unformatted, in a fixed order, with the text field (a path or an executable) last because it may hold spaces:

```bash theme={null}
filetrace events --raw --limit 6
```

```text theme={null}
seq=158 time_ns=1794427679254230336 type=network_send pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=0 inode=0 file_size=0 method=0 confidence=255 loss_kind=0 flags=0 text=
seq=160 time_ns=1794427679254613086 type=file_transfer pid=1024 ppid=772 uid=0 comm=file-server exit_status=0 socket=16 protocol=6 local_ip=127.0.0.1 local_port=41814 remote_ip=127.0.0.1 remote_port=51871 bytes=1250000 bytes_read=0 device=63 inode=626330 file_size=40000000 method=1 confidence=3 loss_kind=0 flags=2 text=/srv/export/media/files/stream.bin
```

| Raw field | Values |
| - | - |
| `time_ns` | Nanoseconds since the Unix epoch |
| `protocol` | IP protocol number: `6` TCP, `17` UDP |
| `exit_status` | The kernel's exit code of the process, as `wait(2)` reports it |
| `bytes` | Bytes sent or received; for `event_loss`, the number of lost events |
| `method` | `0` none, `1` sendfile, `2` read-write |
| `confidence` | `0` unknown, `1` inferred, `2` strong, `3` exact, `255` none yet |
| `loss_kind` | `0` event queue overflow, `1` counter table full, `2` socket without identity, `255` this reader fell behind |
| `flags` | Bit `1`: the file is deleted. Bit `2`: the event carries a confidence |
| `text` | The file path or the executable |

`--raw` cannot be combined with `--format`.

## Selecting events

`--type` takes a comma-separated list of the types above; an unknown name prints the list of types and exits with code 2. The other filters (`--pid`, `--process`, `--path`, `--remote`, `--port`, `--since`, `--limit` and more) are described on the [`events`](https://filetrace.mintlify.site/cli/events) page.

```bash theme={null}
filetrace events --type file_transfer,network_send --pid 1245 --since 5m
```

## Export over OTLP

The OTLP exporter sends events as log records, one per event, with the event name `filetrace.<type>`. By default it sends `file_transfer` and `event_loss`; `[otlp] events` names any other types from the list above. Within each `[otlp] flush_interval`, the bytes of one transfer, or of one socket and peer, are summed into a single record, so a long transfer produces one record per interval. [OpenTelemetry (OTLP)](https://filetrace.mintlify.site/integrations/opentelemetry.md) describes the records and [Metrics and attributes reference](https://filetrace.mintlify.site/integrations/telemetry-reference.md) their attributes.

```toml theme={null}
[otlp]
enabled = true
events = ["file_transfer", "event_loss", "process_exec", "socket_established"]
```


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