katra-trace 0.1.0

Katra3D trace format: versioned, deterministic, correlated event capture.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Trace writer: appends length-prefixed bincode records to a file.

use std::fs::{File, OpenOptions};
use std::io::{BufWriter, Write};
use std::path::Path;

use katra_core::{KatraError, Result};
use serde::Serialize;

use crate::header::{FORMAT_VERSION, SCHEMA_HASH, TRACE_MAGIC, TraceHeader};
use crate::record::{TraceRecord, TraceSummary};

/// Appends records to a trace file. Not `Sync`; a profiler must serialize
/// writes (the profiler's sink mutex does this).
pub struct TraceWriter {
    inner: BufWriter<File>,
    count: u64,
}

impl TraceWriter {
    /// Create (truncate) a trace file and write the header.
    pub fn create(path: &Path, header: &TraceHeader) -> Result<Self> {
        let file = OpenOptions::new()
            .create(true)
            .truncate(true)
            .write(true)
            .open(path)
            .map_err(KatraError::from)?;
        let mut w = TraceWriter { inner: BufWriter::new(file), count: 0 };
        w.write_header(header)?;
        Ok(w)
    }

    fn write_raw<T: Serialize>(&mut self, value: &T) -> Result<()> {
        let bytes =
            bincode::serialize(value).map_err(|e| KatraError::Protocol(format!("bincode: {e}")))?;
        let len = bytes.len() as u32;
        self.inner
            .write_all(&len.to_le_bytes())
            .and_then(|_| self.inner.write_all(&bytes))
            .map_err(KatraError::from)?;
        Ok(())
    }

    fn write_header(&mut self, header: &TraceHeader) -> Result<()> {
        debug_assert_eq!(header.format_version, FORMAT_VERSION);
        debug_assert_eq!(header.schema_hash, SCHEMA_HASH);
        let bytes = bincode::serialize(header)
            .map_err(|e| KatraError::Protocol(format!("bincode header: {e}")))?;
        self.inner
            .write_all(&TRACE_MAGIC)
            .and_then(|_| self.inner.write_all(&FORMAT_VERSION.to_le_bytes()))
            .and_then(|_| self.inner.write_all(&(bytes.len() as u32).to_le_bytes()))
            .and_then(|_| self.inner.write_all(&bytes))
            .map_err(KatraError::from)?;
        Ok(())
    }

    /// Append one record.
    pub fn write(&mut self, record: &TraceRecord) -> Result<()> {
        self.write_raw(record)?;
        self.count += 1;
        Ok(())
    }

    /// Append one event.
    pub fn write_event(&mut self, event: &katra_core::TraceEvent) -> Result<()> {
        self.write(&TraceRecord::Event(event.clone()))
    }

    /// Number of records written.
    pub fn count(&self) -> u64 {
        self.count
    }

    /// Flush buffered bytes to the file without finishing the session.
    pub fn flush_buffered(&mut self) -> Result<()> {
        self.inner.flush().map_err(KatraError::from)
    }

    /// Write the session summary and flush. The file is left open for
    /// inspection; call `close` to release it.
    pub fn finish(&mut self, summary: &TraceSummary) -> Result<()> {
        self.write(&TraceRecord::SessionSummary(summary.clone()))?;
        self.inner.flush().map_err(KatraError::from)
    }

    /// Close the file (flush and drop).
    pub fn close(self) -> Result<()> {
        let mut w = self;
        w.inner.flush().map_err(KatraError::from)?;
        drop(w.inner);
        Ok(())
    }
}

/// Helper to assemble a header with sensible defaults for a given workload.
pub fn default_header(
    workload: &str,
    capture: &katra_core::CaptureOptions,
    notes: Vec<String>,
) -> TraceHeader {
    let now_wall = katra_core::wall_now_ns();
    let now_mono = katra_core::monotonic_now_ns();
    TraceHeader {
        format_version: FORMAT_VERSION,
        schema_hash: SCHEMA_HASH,
        tool_version: format!("katra3d {}", katra_core::KATRA_VERSION),
        capture_options: capture.clone(),
        start_wall_ns: now_wall,
        start_mono_ns: now_mono,
        process_id: std::process::id() as u64,
        workload: workload.to_string(),
        host: crate::reader::host_info(),
        notes,
    }
}