katra_trace/
header.rs

1//! Trace header: magic, format version, schema hash, and capture metadata.
2
3use katra_core::{CaptureOptions, fnv1a};
4use serde::{Deserialize, Serialize};
5
6/// Magic bytes at the start of every trace file: `KATRATRC`.
7pub const TRACE_MAGIC: [u8; 8] = *b"KATRATRC";
8
9/// The trace format version. Bump on any backward-incompatible change.
10pub const FORMAT_VERSION: u32 = 1;
11
12/// A canonical description of the v1 schema. Changing this string must
13/// change [`SCHEMA_HASH`], which forces old readers to notice.
14pub const SCHEMA_STRING: &str = "\
15katra-trace-v1\n\
16header: magic[8] u32 version u32 header_len bincode(TraceHeader)\n\
17records: repeated u32 len + bincode(TraceRecord)\n\
18TraceHeader: format_version u32, schema_hash u64, tool_version string,\n\
19  capture_options CaptureOptions, start_wall_ns u64, start_mono_ns u64,\n\
20  process_id u64, workload string, host HostInfo, notes Vec<string>\n\
21TraceRecord: Event(TraceEvent) | EpochMarker{label, ts_mono_ns, ts_wall_ns}\n\
22  | Counter{name, value, ts_mono_ns} | SessionSummary(TraceSummary)\n\
23TraceEvent: seq, ts_mono_ns, ts_wall_ns, thread_id, process_id, scope, kind,\n\
24  phase, span_id, request_id, causes Vec<u64>, resource, payload,\n\
25  cost_estimate_ns, confidence\n\
26Enums serialized by variant index; append-only evolution.\n";
27
28/// Compile-time hash of the schema description.
29pub const SCHEMA_HASH: u64 = fnv1a(SCHEMA_STRING.as_bytes());
30
31/// Host information recorded in the header.
32#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
33pub struct HostInfo {
34    /// Kernel release, e.g. "6.8.0-45-generic".
35    pub kernel: Option<String>,
36    /// OS name, e.g. "linux".
37    pub os: Option<String>,
38    /// CPU model name.
39    pub cpu_model: Option<String>,
40    /// Number of logical cores.
41    pub cpu_cores: Option<u32>,
42    /// Physical RAM bytes.
43    pub ram_bytes: Option<u64>,
44}
45
46/// Trace session header.
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
48pub struct TraceHeader {
49    /// Format version ([`FORMAT_VERSION`]).
50    pub format_version: u32,
51    /// Schema hash ([`SCHEMA_HASH`]).
52    pub schema_hash: u64,
53    /// Tool version that produced the trace.
54    pub tool_version: String,
55    /// Capture options.
56    pub capture_options: CaptureOptions,
57    /// Wall-clock ns of session start (Unix epoch).
58    pub start_wall_ns: u64,
59    /// Monotonic ns of session start.
60    pub start_mono_ns: u64,
61    /// Process id of the captured process.
62    pub process_id: u64,
63    /// Workload label, e.g. `"demo"` or `"proton:appid=271590"`.
64    pub workload: String,
65    /// Host information.
66    pub host: HostInfo,
67    /// Free-form capture notes (command line, seed, ...).
68    pub notes: Vec<String>,
69}
katra_trace/header.rs

katra_trace/
header.rs
