katra-trace 0.1.0

//! Trace header: magic, format version, schema hash, and capture metadata.

use katra_core::{CaptureOptions, fnv1a};
use serde::{Deserialize, Serialize};

/// Magic bytes at the start of every trace file: `KATRATRC`.
pub const TRACE_MAGIC: [u8; 8] = *b"KATRATRC";

/// The trace format version. Bump on any backward-incompatible change.
pub const FORMAT_VERSION: u32 = 1;

/// A canonical description of the v1 schema. Changing this string must
/// change [`SCHEMA_HASH`], which forces old readers to notice.
pub const SCHEMA_STRING: &str = "\
katra-trace-v1\n\
header: magic[8] u32 version u32 header_len bincode(TraceHeader)\n\
records: repeated u32 len + bincode(TraceRecord)\n\
TraceHeader: format_version u32, schema_hash u64, tool_version string,\n\
  capture_options CaptureOptions, start_wall_ns u64, start_mono_ns u64,\n\
  process_id u64, workload string, host HostInfo, notes Vec<string>\n\
TraceRecord: Event(TraceEvent) | EpochMarker{label, ts_mono_ns, ts_wall_ns}\n\
  | Counter{name, value, ts_mono_ns} | SessionSummary(TraceSummary)\n\
TraceEvent: seq, ts_mono_ns, ts_wall_ns, thread_id, process_id, scope, kind,\n\
  phase, span_id, request_id, causes Vec<u64>, resource, payload,\n\
  cost_estimate_ns, confidence\n\
Enums serialized by variant index; append-only evolution.\n";

/// Compile-time hash of the schema description.
pub const SCHEMA_HASH: u64 = fnv1a(SCHEMA_STRING.as_bytes());

/// Host information recorded in the header.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct HostInfo {
    /// Kernel release, e.g. "6.8.0-45-generic".
    pub kernel: Option<String>,
    /// OS name, e.g. "linux".
    pub os: Option<String>,
    /// CPU model name.
    pub cpu_model: Option<String>,
    /// Number of logical cores.
    pub cpu_cores: Option<u32>,
    /// Physical RAM bytes.
    pub ram_bytes: Option<u64>,
}

/// Trace session header.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct TraceHeader {
    /// Format version ([`FORMAT_VERSION`]).
    pub format_version: u32,
    /// Schema hash ([`SCHEMA_HASH`]).
    pub schema_hash: u64,
    /// Tool version that produced the trace.
    pub tool_version: String,
    /// Capture options.
    pub capture_options: CaptureOptions,
    /// Wall-clock ns of session start (Unix epoch).
    pub start_wall_ns: u64,
    /// Monotonic ns of session start.
    pub start_mono_ns: u64,
    /// Process id of the captured process.
    pub process_id: u64,
    /// Workload label, e.g. `"demo"` or `"proton:appid=271590"`.
    pub workload: String,
    /// Host information.
    pub host: HostInfo,
    /// Free-form capture notes (command line, seed, ...).
    pub notes: Vec<String>,
}