katra_trace/lib.rs
1//! katra-trace — the Katra trace format.
2//!
3//! A trace is a **versioned, deterministic, append-only stream** of records:
4//!
5//! ```text
6//! [magic: 8 bytes] [format_version: u32] [header_len: u32] [header: bincode]
7//! [record_len: u32] [record: bincode(TraceRecord)] ... (repeat)
8//! ```
9//!
10//! Records are `Event`, `EpochMarker`, `Counter`, or `SessionSummary`.
11//!
12//! # Determinism
13//!
14//! * `seq` is monotonic; events are written in `seq` order.
15//! * Timestamps are ns since profiler start (plus a wall-clock anchor in the
16//! header and in epoch markers).
17//! * Replay can therefore re-emit a trace at exact relative timing.
18//!
19//! # Versioning discipline
20//!
21//! * Enum layouts are serialized by variant index: **append new variants at
22//! the end** of any enum in `katra-core`.
23//! * Any layout-affecting change bumps [`header::SCHEMA_HASH`] (computed from
24//! [`header::SCHEMA_STRING`] at compile time).
25//! * Backward-incompatible changes bump [`header::FORMAT_VERSION`].
26
27#![forbid(unsafe_code)]
28#![warn(missing_docs)]
29
30pub mod header;
31pub mod reader;
32pub mod record;
33pub mod verify;
34pub mod writer;
35
36pub use header::{FORMAT_VERSION, SCHEMA_HASH, SCHEMA_STRING, TRACE_MAGIC, TraceHeader};
37pub use reader::{TraceReader, TraceReaderError};
38pub use record::{TraceRecord, TraceSummary};
39pub use verify::{VerifyIssue, VerifyReport};
40pub use writer::{TraceWriter, default_header};