oxidelm 0.2.0

Bare-metal pure-Rust Transformer engine with reverse-mode autograd, BPE tokenization, and wgpu acceleration
Documentation
//! Structured logging with quiet, human-readable, and JSON output modes.
//!
//! Library code should emit events through this module instead of calling
//! `println!` directly. The CLI selects a mode with `--log`.

use serde_json::{json, Map, Value};
use std::fmt::Write as _;
use std::io::{self, Write};
use std::sync::atomic::{AtomicU8, Ordering};

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[repr(u8)]
pub enum LogMode {
    Quiet = 0,
    #[default]
    Human = 1,
    Json = 2,
}

static LOG_MODE: AtomicU8 = AtomicU8::new(LogMode::Human as u8);

/// A typed field value for structured log events.
#[derive(Clone, Copy, Debug)]
pub enum LogValue<'a> {
    Str(&'a str),
    Usize(usize),
    Bool(bool),
    /// Floating-point value with human-mode decimal digits.
    Float(f64, usize),
    /// Byte count: compact units in human mode, raw integer in JSON.
    Bytes(usize),
}

impl<'a> LogValue<'a> {
    pub fn f32(value: f32, precision: usize) -> Self {
        Self::Float(value as f64, precision)
    }

    pub fn f64(value: f64, precision: usize) -> Self {
        Self::Float(value, precision)
    }
}

pub fn set_log_mode(mode: LogMode) {
    LOG_MODE.store(mode as u8, Ordering::Relaxed);
}

pub fn log_mode() -> LogMode {
    match LOG_MODE.load(Ordering::Relaxed) {
        0 => LogMode::Quiet,
        2 => LogMode::Json,
        _ => LogMode::Human,
    }
}

pub fn parse_log_mode(value: &str) -> Result<LogMode, String> {
    match value.trim().to_ascii_lowercase().as_str() {
        "quiet" | "off" | "none" => Ok(LogMode::Quiet),
        "human" | "text" | "plain" => Ok(LogMode::Human),
        "json" => Ok(LogMode::Json),
        other => Err(format!(
            "unknown log mode '{other}'; expected quiet, human, or json"
        )),
    }
}

/// Emit a structured event. Quiet mode discards it; human and JSON write one line.
pub fn emit(event: &str, fields: &[(&str, LogValue<'_>)]) {
    let Some(line) = format_event(log_mode(), event, fields) else {
        return;
    };
    let mut stdout = io::stdout().lock();
    let _ = writeln!(stdout, "{line}");
}

/// Emit a free-form message under an event name.
///
/// Human mode prints the message unchanged (multi-line friendly). JSON mode
/// wraps it as `{"event":...,"message":...}`.
pub fn emit_message(event: &str, message: &str) {
    match log_mode() {
        LogMode::Quiet => {}
        LogMode::Human => {
            let mut stdout = io::stdout().lock();
            let _ = writeln!(stdout, "{message}");
        }
        LogMode::Json => {
            emit(event, &[("message", LogValue::Str(message))]);
        }
    }
}

/// Format an event without writing. Returns `None` for quiet mode.
pub fn format_event(mode: LogMode, event: &str, fields: &[(&str, LogValue<'_>)]) -> Option<String> {
    match mode {
        LogMode::Quiet => None,
        LogMode::Human => Some(format_human(event, fields)),
        LogMode::Json => Some(format_json(event, fields)),
    }
}

fn format_human(event: &str, fields: &[(&str, LogValue<'_>)]) -> String {
    let mut line = String::new();
    let _ = write!(&mut line, "{event}");
    for (key, value) in fields {
        let _ = write!(&mut line, " {key}=");
        match value {
            LogValue::Str(text) => line.push_str(text),
            LogValue::Usize(number) => {
                let _ = write!(&mut line, "{number}");
            }
            LogValue::Bool(flag) => {
                let _ = write!(&mut line, "{flag}");
            }
            LogValue::Float(number, precision) => {
                let _ = write!(&mut line, "{number:.precision$}");
            }
            LogValue::Bytes(bytes) => {
                line.push_str(&crate::memory::format_bytes_compact(*bytes));
            }
        }
    }
    line
}

fn format_json(event: &str, fields: &[(&str, LogValue<'_>)]) -> String {
    let mut object = Map::new();
    object.insert("event".into(), Value::String(event.to_string()));
    for (key, value) in fields {
        let json_value = match value {
            LogValue::Str(text) => Value::String((*text).to_string()),
            LogValue::Usize(number) => json!(number),
            LogValue::Bool(flag) => Value::Bool(*flag),
            LogValue::Float(number, _) => {
                if number.is_finite() {
                    json!(number)
                } else {
                    Value::String(number.to_string())
                }
            }
            LogValue::Bytes(bytes) => json!(bytes),
        };
        object.insert((*key).to_string(), json_value);
    }
    Value::Object(object).to_string()
}

#[cfg(test)]
mod tests {
    use super::{format_event, parse_log_mode, LogMode, LogValue};

    #[test]
    fn parse_accepts_aliases() {
        assert_eq!(parse_log_mode("quiet").unwrap(), LogMode::Quiet);
        assert_eq!(parse_log_mode("HUMAN").unwrap(), LogMode::Human);
        assert_eq!(parse_log_mode("json").unwrap(), LogMode::Json);
        assert_eq!(parse_log_mode("off").unwrap(), LogMode::Quiet);
        assert!(parse_log_mode("yaml").is_err());
    }

    #[test]
    fn quiet_formats_to_nothing() {
        assert_eq!(
            format_event(LogMode::Quiet, "train", &[("step", LogValue::Usize(1))]),
            None
        );
    }

    #[test]
    fn human_matches_key_value_style() {
        let line = format_event(
            LogMode::Human,
            "train",
            &[
                ("step", LogValue::Usize(3)),
                ("loss", LogValue::f32(1.23456, 5)),
                ("ppl", LogValue::f32(3.437, 3)),
                ("lr", LogValue::f32(0.0003, 7)),
                ("grad", LogValue::f32(1.25, 4)),
                ("tok/s", LogValue::f64(120.46, 1)),
            ],
        )
        .unwrap();
        assert_eq!(
            line,
            "train step=3 loss=1.23456 ppl=3.437 lr=0.0003000 grad=1.2500 tok/s=120.5"
        );
    }

    #[test]
    fn human_formats_bytes_compactly() {
        let line = format_event(
            LogMode::Human,
            "train",
            &[("peak_rss", LogValue::Bytes(12 * 1024 * 1024))],
        )
        .unwrap();
        assert_eq!(line, "train peak_rss=12.00MiB");
    }

    #[test]
    fn json_emits_bytes_as_integer() {
        let line = format_event(
            LogMode::Json,
            "train",
            &[("peak_rss", LogValue::Bytes(4096))],
        )
        .unwrap();
        let value: serde_json::Value = serde_json::from_str(&line).unwrap();
        assert_eq!(value["peak_rss"], 4096);
    }

    #[test]
    fn json_emits_event_object() {
        let line = format_event(
            LogMode::Json,
            "eval",
            &[
                ("step", LogValue::Usize(10)),
                ("val_loss", LogValue::f32(2.5, 5)),
                ("improved", LogValue::Bool(true)),
            ],
        )
        .unwrap();
        let value: serde_json::Value = serde_json::from_str(&line).unwrap();
        assert_eq!(value["event"], "eval");
        assert_eq!(value["step"], 10);
        assert_eq!(value["val_loss"], 2.5);
        assert_eq!(value["improved"], true);
    }
}