#![deny(missing_docs)]
#![warn(clippy::missing_docs_in_private_items)]
use std::fs::File;
use std::io::{BufWriter, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Mutex, MutexGuard, PoisonError};
struct Sink {
writer: BufWriter<File>,
path: PathBuf,
}
static ENABLED: AtomicBool = AtomicBool::new(false);
static SINK: Mutex<Option<Sink>> = Mutex::new(None);
fn lock_sink() -> MutexGuard<'static, Option<Sink>> {
SINK.lock().unwrap_or_else(PoisonError::into_inner)
}
pub fn is_enabled() -> bool {
ENABLED.load(Ordering::Relaxed)
}
pub fn enable(path: &Path) -> std::io::Result<()> {
let mut sink = lock_sink();
if let Some(open) = sink.as_ref() {
return Err(std::io::Error::new(
std::io::ErrorKind::AlreadyExists,
format!(
"cannot record to {}: a data log is already being written to {}; disable it first",
path.display(),
open.path.display()
),
));
}
let file = File::create(path)?;
*sink = Some(Sink {
writer: BufWriter::new(file),
path: path.to_path_buf(),
});
ENABLED.store(true, Ordering::Relaxed);
Ok(())
}
pub fn disable() {
ENABLED.store(false, Ordering::Relaxed);
if let Some(mut open) = lock_sink().take()
&& let Err(e) = open.writer.flush()
{
log::warn!("failed to flush the data log {}: {e}", open.path.display());
}
}
#[cfg_attr(
not(feature = "learning"),
allow(dead_code, unused_macros, unused_imports)
)]
pub(crate) fn record(value: serde_json::Value) {
let mut sink = lock_sink();
let Some(open) = sink.as_mut() else {
return;
};
let line = value.to_string();
let result = writeln!(open.writer, "{line}").and_then(|()| open.writer.flush());
if let Err(e) = result {
log::warn!(
"writing the data log {} failed ({e}); recording stops",
open.path.display()
);
ENABLED.store(false, Ordering::Relaxed);
*sink = None;
}
}
#[cfg_attr(
not(feature = "learning"),
allow(dead_code, unused_macros, unused_imports)
)]
macro_rules! data_log {
($event:expr, $($key:ident = $value:expr),+ $(,)?) => {
if $crate::diagnostics::is_enabled() {
let mut map = serde_json::Map::new();
map.insert("event".to_string(), serde_json::Value::from($event));
$(
let previous = map.insert(
stringify!($key).to_string(),
serde_json::to_value(&$value).unwrap_or(serde_json::Value::Null),
);
assert!(
previous.is_none(),
"data_log!(\"{}\"): the field `{}` is given twice or clashes with the reserved field `event`",
$event,
stringify!($key),
);
)+
$crate::diagnostics::record(serde_json::Value::Object(map));
}
};
}
#[cfg_attr(
not(feature = "learning"),
allow(dead_code, unused_macros, unused_imports)
)]
pub(crate) use data_log;
#[cfg(test)]
mod tests {
use super::*;
static SERIAL: Mutex<()> = Mutex::new(());
struct Scenario {
_lock: MutexGuard<'static, ()>,
path: PathBuf,
}
impl Scenario {
fn new(name: &str) -> Self {
let lock = SERIAL.lock().unwrap_or_else(PoisonError::into_inner);
disable();
let path = std::env::temp_dir()
.join(format!("aicad_diag_{}_{name}.jsonl", std::process::id()));
Scenario { _lock: lock, path }
}
fn lines(&self) -> Vec<serde_json::Value> {
std::fs::read_to_string(&self.path)
.unwrap()
.lines()
.map(|l| serde_json::from_str::<serde_json::Value>(l).unwrap())
.filter(|event| {
event["event"]
.as_str()
.is_some_and(|e| e.starts_with("test_"))
})
.collect()
}
}
impl Drop for Scenario {
fn drop(&mut self) {
disable();
let _ = std::fs::remove_file(&self.path);
}
}
#[test]
fn events_are_written_one_per_line_with_their_fields() {
let s = Scenario::new("round_trip");
enable(&s.path).unwrap();
data_log!("test_first", epoch = 3usize, loss = 0.5f64, split = "train");
data_log!("test_second", values = vec![1, 2, 3]);
disable();
let lines = s.lines();
assert_eq!(lines.len(), 2);
assert_eq!(lines[0]["event"], "test_first");
assert_eq!(lines[0]["epoch"], 3);
assert_eq!(lines[0]["loss"], 0.5);
assert_eq!(lines[0]["split"], "train");
assert_eq!(lines[1]["values"], serde_json::json!([1, 2, 3]));
}
#[test]
fn non_finite_floats_are_recorded_as_null() {
let s = Scenario::new("non_finite");
enable(&s.path).unwrap();
data_log!("test_loss", value = f64::NAN);
disable();
assert!(s.lines()[0]["value"].is_null());
}
#[test]
fn a_disabled_log_does_not_evaluate_its_arguments() {
let _s = Scenario::new("disabled");
let mut evaluated = false;
data_log!(
"test_never",
flag = {
evaluated = true;
1
}
);
assert!(!evaluated);
}
#[test]
fn enabling_twice_fails_and_leaves_the_first_log_intact() {
let s = Scenario::new("twice");
let other = s.path.with_extension("other");
enable(&s.path).unwrap();
let err = enable(&other).unwrap_err();
assert_eq!(err.kind(), std::io::ErrorKind::AlreadyExists);
assert!(err.to_string().contains("already being written"), "{err}");
assert!(!other.exists(), "the refused log must not be created");
data_log!("test_still_first", n = 1);
disable();
assert_eq!(s.lines().len(), 1);
enable(&other).unwrap();
disable();
let _ = std::fs::remove_file(&other);
}
#[test]
fn enabling_an_unwritable_path_fails_and_stays_disabled() {
let s = Scenario::new("unwritable");
let missing_dir = s.path.join("no").join("such").join("dir.jsonl");
assert!(enable(&missing_dir).is_err());
assert!(!is_enabled());
}
#[test]
#[should_panic(expected = "clashes with the reserved field `event`")]
fn a_field_named_event_is_refused() {
let s = Scenario::new("reserved");
enable(&s.path).unwrap();
data_log!("kind", event = 1);
}
#[test]
#[should_panic(expected = "is given twice")]
fn a_repeated_field_is_refused() {
let s = Scenario::new("repeated");
enable(&s.path).unwrap();
data_log!("kind", n = 1, n = 2);
}
#[cfg(target_os = "linux")]
#[test]
fn a_write_error_closes_the_sink_instead_of_failing_the_run() {
let _s = Scenario::new("full");
enable(Path::new("/dev/full")).unwrap();
data_log!("test_lost", n = 1);
assert!(!is_enabled(), "the first failed write must close the sink");
data_log!("test_also_lost", n = 2);
}
}