# Observability: the trace format and the profiler
## Trace format (v1)
A trace is a versioned, deterministic, append-only stream:
```text
[magic "KATRATRC"] [format_version u32] [header_len u32] [header bincode]
[record_len u32] [record bincode(TraceRecord)] ... (repeat)
```
Records: `Event`, `EpochMarker`, `Counter`, `SessionSummary`.
The header records: format version, schema hash (compile-time FNV of a
canonical schema string), tool version, capture options, start times,
process id, workload label, host info, and capture notes.
### Versioning discipline
* Enums serialize by variant index — **append new variants at the end** of
any enum in `katra-core`.
* Any layout change bumps `SCHEMA_HASH`; incompatible changes bump
`FORMAT_VERSION`. Readers reject mismatched versions/hashes loudly.
## The event
```text
seq · ts_mono_ns · ts_wall_ns · thread_id · process_id · scope · kind ·
phase · span_id · request_id · causes[] · resource (domain,id) · payload ·
cost_estimate_ns · confidence
```
Correlation comes from four mechanisms:
* `seq` — global monotonic order;
* `span_id` — pairs `Begin` with `End` (measured durations);
* `request_id` — groups events of one logical request (an asset load, a
frame, a scene transition);
* `causes[]` — explicit causal links to earlier seqs (the semantic graph).
Payloads are plain `Copy` scalar structs — no heap allocation on the hot
path.
## Scopes and kinds
Events are categorized by producing layer (`WindowsFacing`, `WineProton`,
`Linux`, `D3d12Vkd3d`, `Vulkan`, `Gpu`, `Katra`) and by kind covering §5:
`NtReadFile`, `ReadFile`, `FileOpen/Close`, mappings, sync waits, thread
create/wakeup, allocations, D3D12 calls (queue submit, signal, wait,
resource create/upload, barriers, descriptors, PSO, residency), presents,
Win→Unix transitions, server calls, path translations, syscalls, io_uring
submit/complete, page faults, context switches, scheduler wakeups, fs
latency, command-list creation, resource state tracking, shader
translation, cache hit/miss, fence wait/signal, Vulkan calls, GPU
timestamps/idle/utilization, and Katra-native events (subsystem states,
graph ops, counters, prefetch, decompress, staging, epochs, allocation,
I/O waits).
## The hot path
Per-thread preallocated buffers; `CompactEvent` is a plain `Copy` struct.
Emit = timestamp + seq + thread-id + push; buffers drain at a threshold and
on thread exit. `Vec::drain(..)` keeps the allocation, so steady-state
capture performs **no allocation per event**. The courts enforce the budget
(`profiler_overhead`).
## Verification
`katra-trace::verify` checks: magic/version/schema, strictly monotonic seqs,
no duplicate seqs, causal links only to earlier existing events, and
begin/end span balance (per thread+span). The `trace_verify` court runs it
on a captured trace; `katra-replay verify` exposes it on the CLI.
## Epochs
`EpochMarker` records segment the trace (session, loading, frame N, scene
change). Reports use them for per-epoch critical paths; replays reproduce
them.
## Determinism & replay
Monotonic timestamps are relative to profiler start; the wall clock is an
anchor only. The same deterministic workload (same seed) produces the same
trace structure — the `trace_determinism` court proves it and
`katra-replay compare` quantifies equivalence (structural hash + causal
graph hash).
## Privacy (§43)
File *identity hashes*, offsets, lengths, timing, and graph relationships —
never file contents, and never transmitted anywhere by default.