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.Header
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 atsyscalls/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 atsyscalls/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
ppidorold_pid. - Oversized fork command fields.
SQLite schema version 5
Versions 2 through 5 are additive:
Existing sessions remain readable; historical rows are not rewritten.
sessions
events
Indexes:
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_VERSIONupdate, tests, and a documentation update.