Skip to main content
Three contracts are versioned independently. A newer value is rejected explicitly rather than interpreted optimistically. The wire decoder accepts versions 1 and 2 for process lifecycle samples. File-open and network-connect samples require wire version 3.

Ring-buffer wire format

All multi-byte fields are native-endian because producer and consumer are on the same host. Structures are 8-byte aligned. 56 bytes: Wire v1 treated ns_tgid as reserved and zero.

Exec sample

320 bytes: data_len is the filename length excluding NUL. The decoder requires data_len <= 256, a NUL at 60 + data_len when non-empty, and a sample of at least 320 bytes.

Fork sample

96 bytes: The header PID and TGID are both the child PID. Userspace checks /proc/<child>/status to reject thread-creation events when the child is not a process leader.

Exit sample

64 bytes:

File-open sample

336 bytes, emitted at syscalls/sys_exit_openat after a matching enter: result is a non-negative file descriptor on success or a negative errno on failure. dirfd == -100 is AT_FDCWD. The path is the raw string passed to openat, not a resolved path.

Network-connect sample

104 bytes, emitted at syscalls/sys_exit_connect after a matching enter, only for AF_INET and AF_INET6: IPv4 addresses occupy the first four bytes and are zero-padded. The decoder validates family, address length, padding, and port conversion. source_available == 0 stores source address and port as null, not a guess.

Domain event

id is assigned by SQLite and is null before persistence. For schema v2, tid preserves the observed thread ID for file_open and network_connect. Lifecycle events keep the process TGID. Schema v1 rows used the process TGID for every event, so consumers must check schema_version when reading historical data.

Payload variants

file_open.success is result >= 0. network_connect.success is result == 0. For failures, errno is -result when representable, otherwise null. network_connect.established is always false; the hook proves an attempt, not an established connection, and cannot distinguish TCP from UDP. Exec and exit payloads include flattened ppid and start_time_ticks from process metadata.

Validation

Event::validate rejects:
  • Unknown domain schema versions.
  • Empty or oversized session, process-instance, comm, or filename values.
  • Control characters in IDs.
  • NUL bytes or non-positive PIDs/TIDs.
  • Non-positive timestamps, non-positive wall clock, or zero monotonic time.
  • Event type and payload mismatch.
  • File paths longer than 256 bytes or containing NUL.
  • Invalid address family, address length, or address bytes.
  • Activity success or errno inconsistent with the raw result.
  • A network event claiming established = true.
  • Negative ppid or old_pid.
  • Oversized fork command fields.
Storage validates the complete batch before opening a transaction and checks every event’s session ID against the batch.

SQLite schema version 5

Versions 2 through 5 are additive: Existing sessions remain readable; historical rows are not rewritten.

sessions

events

Indexes:
The last two were added in v4. Activity queries use json_valid and json_extract for payload fields and order by timestamp_ns ASC, monotonic_ns ASC, id ASC.

Migration policy

  • Migrations are ordered by PRAGMA user_version.
  • A writable open applies pending migrations in a transaction and bumps the version.
  • A read-only open never migrates.
  • A missing schema or a newer version is rejected.
  • A schema bump requires a new migration file, a LATEST_SCHEMA_VERSION update, tests, and a documentation update.
See Development for the change procedure.