grafos_profile/

recording.rs

//! Profile recording — ordered sequence of [`ResourceSpan`] records from a program run.

use alloc::string::String;
use alloc::vec::Vec;

use grafos_observe::span::ResourceSpan;

use crate::span_json::SpanJson;

/// Header metadata for a profile recording file.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
pub struct RecordingHeader {
    /// Format identifier.
    pub format: String,
    /// Program name (if known).
    pub program: Option<String>,
    /// Total recording duration in microseconds.
    pub duration_us: Option<u64>,
    /// Timestamp when recording started (Unix microseconds).
    pub recorded_at: Option<u64>,
}

impl Default for RecordingHeader {
    fn default() -> Self {
        RecordingHeader {
            format: String::from("grafos-profile-v1"),
            program: None,
            duration_us: None,
            recorded_at: None,
        }
    }
}

/// An ordered sequence of [`ResourceSpan`] records from a program run.
///
/// Recordings can be created from in-memory spans or loaded from
/// newline-delimited JSON files (when the `std` feature is enabled).
#[derive(Debug, Clone)]
pub struct ProfileRecording {
    /// Header metadata.
    pub header: RecordingHeader,
    /// Ordered span records.
    pub spans: Vec<ResourceSpan>,
}

impl ProfileRecording {
    /// Create a recording from an in-memory span vector.
    pub fn from_spans(spans: Vec<ResourceSpan>) -> Self {
        let duration_us = if spans.is_empty() {
            None
        } else {
            let min_start = spans
                .iter()
                .map(|s| s.start_time_unix_us)
                .min()
                .unwrap_or(0);
            let max_end = spans.iter().map(|s| s.end_time_unix_us).max().unwrap_or(0);
            Some(max_end.saturating_sub(min_start))
        };

        ProfileRecording {
            header: RecordingHeader {
                duration_us,
                recorded_at: spans.first().map(|s| s.start_time_unix_us),
                ..RecordingHeader::default()
            },
            spans,
        }
    }

    /// Save the recording to a file as newline-delimited JSON.
    ///
    /// First line is the header; subsequent lines are serialized [`SpanJson`] objects.
    #[cfg(feature = "std")]
    pub fn save(&self, path: &str) -> Result<(), String> {
        use std::io::Write;

        let file = std::fs::File::create(path).map_err(|e| alloc::format!("create: {e}"))?;
        let mut writer = std::io::BufWriter::new(file);

        let header_json =
            serde_json::to_string(&self.header).map_err(|e| alloc::format!("header: {e}"))?;
        writeln!(writer, "{}", header_json).map_err(|e| alloc::format!("write header: {e}"))?;

        for span in &self.spans {
            let span_json = SpanJson::from_span(span);
            let line =
                serde_json::to_string(&span_json).map_err(|e| alloc::format!("span: {e}"))?;
            writeln!(writer, "{}", line).map_err(|e| alloc::format!("write span: {e}"))?;
        }

        writer.flush().map_err(|e| alloc::format!("flush: {e}"))?;
        Ok(())
    }

    /// Load a recording from a newline-delimited JSON file.
    ///
    /// First line is parsed as header; subsequent lines as [`SpanJson`] objects.
    #[cfg(feature = "std")]
    pub fn load(path: &str) -> Result<Self, String> {
        use std::io::BufRead;

        let file = std::fs::File::open(path).map_err(|e| alloc::format!("open: {e}"))?;
        let reader = std::io::BufReader::new(file);
        let mut lines = reader.lines();

        let header_line = lines
            .next()
            .ok_or_else(|| String::from("empty file"))?
            .map_err(|e| alloc::format!("read header: {e}"))?;

        let header: RecordingHeader =
            serde_json::from_str(&header_line).map_err(|e| alloc::format!("parse header: {e}"))?;

        let mut spans = Vec::new();
        for line_result in lines {
            let line = line_result.map_err(|e| alloc::format!("read: {e}"))?;
            if line.trim().is_empty() {
                continue;
            }
            let span_json: SpanJson =
                serde_json::from_str(&line).map_err(|e| alloc::format!("parse span: {e}"))?;
            spans.push(span_json.to_span());
        }

        Ok(ProfileRecording { header, spans })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use grafos_observe::trace::TraceContext;

    fn test_ctx() -> TraceContext {
        let mut bytes = [0u8; 24];
        for (i, b) in bytes.iter_mut().enumerate() {
            *b = (i as u8).wrapping_add(0x42);
        }
        TraceContext::new_root(&bytes)
    }

    #[test]
    fn from_spans_empty() {
        let rec = ProfileRecording::from_spans(Vec::new());
        assert!(rec.spans.is_empty());
        assert_eq!(rec.header.format, "grafos-profile-v1");
        assert!(rec.header.duration_us.is_none());
    }

    #[test]
    fn from_spans_computes_duration() {
        let ctx = test_ctx();
        let mut s1 = ResourceSpan::new("a", ctx);
        s1.start_time_unix_us = 1000;
        s1.end_time_unix_us = 2000;

        let child_ctx = ctx.child(&[0xAA; 8]);
        let mut s2 = ResourceSpan::new("b", child_ctx);
        s2.start_time_unix_us = 1500;
        s2.end_time_unix_us = 3000;

        let rec = ProfileRecording::from_spans(vec![s1, s2]);
        assert_eq!(rec.header.duration_us, Some(2000)); // 3000 - 1000
        assert_eq!(rec.header.recorded_at, Some(1000));
    }

    #[cfg(feature = "std")]
    #[test]
    fn save_load_roundtrip() {
        let ctx = test_ctx();
        let mut span = ResourceSpan::new("roundtrip", ctx);
        span.start_time_unix_us = 100;
        span.end_time_unix_us = 200;
        span.bytes_read = 4096;
        span.add_lease_id(42);

        let rec = ProfileRecording::from_spans(vec![span]);

        let dir = std::env::temp_dir();
        let path = dir.join("grafos_profile_test.ndjson");
        let path_str = path.to_str().unwrap();

        rec.save(path_str).unwrap();
        let loaded = ProfileRecording::load(path_str).unwrap();

        assert_eq!(loaded.header.format, "grafos-profile-v1");
        assert_eq!(loaded.spans.len(), 1);
        assert_eq!(loaded.spans[0].name, "roundtrip");
        assert_eq!(loaded.spans[0].bytes_read, 4096);
        assert_eq!(loaded.spans[0].lease_ids, vec![42u128]);

        let _ = std::fs::remove_file(path_str);
    }
}