rs-zero 0.2.20

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
//! Logging configuration and helpers.

pub mod aggregation;
pub mod config;
pub mod fields;
pub(crate) mod format;
pub mod redaction;
pub(crate) mod rotation;
pub mod sampling;
pub mod writer;

use std::sync::{Mutex, OnceLock};

use tracing_appender::non_blocking::WorkerGuard;
use tracing_subscriber::{
    EnvFilter,
    fmt::{
        self,
        format::{DefaultFields, FmtSpan, Format},
        writer::BoxMakeWriter,
    },
    layer::SubscriberExt,
    util::SubscriberInitExt,
};

use crate::core::{CoreError, CoreResult};

pub use aggregation::{ErrorAggregationSnapshot, ErrorAggregator, ErrorGroup};
pub use config::{LogConfig, LogFormat, LogSpanEvents};
pub use fields::LogFields;
use format::{RedactingJsonFields, RedactingJsonFormat, RedactingTextFormat};
pub use redaction::{RedactionConfig, redact_text};
pub use sampling::{LogSampler, SamplingConfig};
pub use writer::{
    LogWriterConfig, PreparedLogWriter, RollingFileConfig, RotationPolicy,
    RuntimeRollingFileWriter, validate_writer,
};

static LOG_WORKER_GUARDS: OnceLock<Mutex<Vec<WorkerGuard>>> = OnceLock::new();

/// Guard that keeps non-blocking log workers alive until dropped.
#[derive(Default)]
pub struct TracingGuard {
    guards: Vec<WorkerGuard>,
}

/// Initializes a global tracing subscriber.
///
/// Calling this more than once returns `CoreError::SubscriberInit`; tests can
/// use `try_init` semantics by ignoring that specific error.
///
/// File-backed non-blocking logs should prefer [`init_tracing_with_guard`] so
/// the returned guard can flush buffered records during normal shutdown.
pub fn init_tracing(config: LogConfig) -> CoreResult<()> {
    let (subscriber, guard) = build_subscriber(config)?;
    subscriber
        .try_init()
        .map_err(|_| CoreError::SubscriberInit)?;
    retain_global_guard(guard)?;
    Ok(())
}

/// Initializes global tracing and returns a guard for non-blocking log workers.
pub fn init_tracing_with_guard(config: LogConfig) -> CoreResult<TracingGuard> {
    let (subscriber, guard) = build_subscriber(config)?;
    subscriber
        .try_init()
        .map_err(|_| CoreError::SubscriberInit)?;
    Ok(guard)
}

/// Runs a closure with a scoped tracing subscriber.
///
/// This is primarily useful for tests and embedded runtimes that need isolated
/// logging without installing a process-global subscriber.
pub fn with_scoped_tracing<T>(config: LogConfig, run: impl FnOnce() -> T) -> CoreResult<T> {
    let (subscriber, worker_guard) = build_subscriber(config)?;
    let guard = subscriber.set_default();
    let result = run();
    drop(guard);
    drop(worker_guard);
    Ok(result)
}

fn build_subscriber(config: LogConfig) -> CoreResult<(tracing::Dispatch, TracingGuard)> {
    let filter =
        EnvFilter::try_new(config.filter.clone()).unwrap_or_else(|_| EnvFilter::new("info"));
    let span_events = span_events(config.span_events);
    let (writer, guard) = build_writer(&config.writer)?;

    let dispatch = match config.format {
        LogFormat::Text => build_text_subscriber(config, filter, span_events, writer),
        LogFormat::Json => build_json_subscriber(config, filter, span_events, writer),
    }?;
    Ok((dispatch, guard))
}

fn build_text_subscriber(
    config: LogConfig,
    filter: EnvFilter,
    span_events: FmtSpan,
    writer: BoxMakeWriter,
) -> CoreResult<tracing::Dispatch> {
    let formatter = Format::default()
        .with_ansi(config.ansi)
        .with_target(config.with_target);
    let layer = fmt::layer()
        .event_format(RedactingTextFormat::new(
            formatter,
            config.redaction.clone(),
        ))
        .fmt_fields(DefaultFields::new())
        .with_writer(writer);
    let mut layer = layer;
    layer.set_span_events(span_events);
    Ok(tracing::Dispatch::new(
        tracing_subscriber::registry().with(layer).with(filter),
    ))
}

fn build_json_subscriber(
    config: LogConfig,
    filter: EnvFilter,
    span_events: FmtSpan,
    writer: BoxMakeWriter,
) -> CoreResult<tracing::Dispatch> {
    let formatter = Format::default()
        .json()
        .with_ansi(false)
        .with_target(config.with_target)
        .with_current_span(config.include_current_span)
        .with_span_list(config.include_span_list);

    let layer = fmt::layer()
        .fmt_fields(RedactingJsonFields::new(config.redaction.clone()))
        .event_format(RedactingJsonFormat::new(
            formatter,
            config.redaction.clone(),
        ))
        .with_writer(writer);
    let mut layer = layer;
    layer.set_span_events(span_events);
    Ok(tracing::Dispatch::new(
        tracing_subscriber::registry().with(layer).with(filter),
    ))
}

fn build_writer(config: &LogWriterConfig) -> CoreResult<(BoxMakeWriter, TracingGuard)> {
    validate_writer(config)?;
    match config {
        LogWriterConfig::Stdout => {
            Ok((BoxMakeWriter::new(std::io::stdout), TracingGuard::default()))
        }
        LogWriterConfig::Stderr => {
            Ok((BoxMakeWriter::new(std::io::stderr), TracingGuard::default()))
        }
        LogWriterConfig::File(path) => {
            let file = writer::open_append_file(path)?;
            Ok((
                BoxMakeWriter::new(move || file.try_clone().expect("clone log file")),
                TracingGuard::default(),
            ))
        }
        LogWriterConfig::RollingFile(rolling) => {
            let writer = RuntimeRollingFileWriter::new(rolling.clone())?;
            let (writer, guard) = tracing_appender::non_blocking(writer);
            Ok((
                BoxMakeWriter::new(move || writer.clone()),
                TracingGuard {
                    guards: vec![guard],
                },
            ))
        }
    }
}

fn retain_global_guard(mut guard: TracingGuard) -> CoreResult<()> {
    if guard.guards.is_empty() {
        return Ok(());
    }
    let mut guards = LOG_WORKER_GUARDS
        .get_or_init(|| Mutex::new(Vec::new()))
        .lock()
        .map_err(|_| CoreError::Logging("log worker guard mutex poisoned".to_string()))?;
    guards.append(&mut guard.guards);
    Ok(())
}

#[cfg(test)]
pub mod test_hooks {
    use std::{
        path::{Path, PathBuf},
        sync::{
            Arc, Condvar, Mutex,
            atomic::{AtomicI32, AtomicU64, Ordering},
        },
    };

    static CURRENT_DAY_OFFSET: AtomicI32 = AtomicI32::new(0);
    static NEXT_PAUSE_ID: AtomicU64 = AtomicU64::new(1);
    static COMPRESSION_PAUSE: Mutex<Option<Arc<CompressionPauseState>>> = Mutex::new(None);

    struct CompressionPauseState {
        id: u64,
        dir: PathBuf,
        released: Mutex<bool>,
        condvar: Condvar,
    }

    pub struct CompressionPause {
        state: Arc<CompressionPauseState>,
    }

    impl CompressionPause {
        pub fn resume(self) {
            self.state.resume();
        }
    }

    impl Drop for CompressionPause {
        fn drop(&mut self) {
            self.state.resume();
            clear_pause(self.state.id);
        }
    }

    impl CompressionPauseState {
        fn resume(&self) {
            let mut released = self.released.lock().expect("compression pause mutex");
            *released = true;
            self.condvar.notify_all();
        }
    }

    pub struct CurrentDayOffsetGuard {
        previous: i32,
    }

    impl CurrentDayOffsetGuard {
        pub fn set_offset_days(&self, days: i32) {
            CURRENT_DAY_OFFSET.store(days, Ordering::SeqCst);
        }
    }

    impl Drop for CurrentDayOffsetGuard {
        fn drop(&mut self) {
            CURRENT_DAY_OFFSET.store(self.previous, Ordering::SeqCst);
        }
    }

    pub fn pause_compression_for_dir(dir: &Path) -> CompressionPause {
        let state = Arc::new(CompressionPauseState {
            id: NEXT_PAUSE_ID.fetch_add(1, Ordering::SeqCst),
            dir: dir.to_path_buf(),
            released: Mutex::new(false),
            condvar: Condvar::new(),
        });
        *COMPRESSION_PAUSE.lock().expect("compression pause mutex") = Some(state.clone());
        CompressionPause { state }
    }

    pub fn set_current_day_offset(days: i32) -> CurrentDayOffsetGuard {
        let previous = CURRENT_DAY_OFFSET.swap(days, Ordering::SeqCst);
        CurrentDayOffsetGuard { previous }
    }

    pub(crate) fn current_day_offset() -> i32 {
        CURRENT_DAY_OFFSET.load(Ordering::SeqCst)
    }

    pub(crate) fn pause_if_configured(path: &Path) {
        let Some(state) = COMPRESSION_PAUSE
            .lock()
            .expect("compression pause mutex")
            .clone()
        else {
            return;
        };
        if path.parent() != Some(state.dir.as_path()) {
            return;
        }
        let mut released = state.released.lock().expect("compression pause mutex");
        while !*released {
            released = state
                .condvar
                .wait(released)
                .expect("compression pause condvar");
        }
    }

    fn clear_pause(id: u64) {
        let mut pause = COMPRESSION_PAUSE.lock().expect("compression pause mutex");
        if pause.as_ref().is_some_and(|state| state.id == id) {
            *pause = None;
        }
    }
}

fn span_events(events: LogSpanEvents) -> FmtSpan {
    match events {
        LogSpanEvents::None => FmtSpan::NONE,
        LogSpanEvents::Close => FmtSpan::CLOSE,
        LogSpanEvents::NewAndClose => FmtSpan::NEW | FmtSpan::CLOSE,
        LogSpanEvents::Full => FmtSpan::FULL,
    }
}

#[cfg(test)]
mod tests {
    use super::{LogConfig, init_tracing};

    #[test]
    fn init_tracing_is_callable() {
        let _ = init_tracing(LogConfig {
            filter: "debug".to_string(),
            ansi: false,
            ..LogConfig::default()
        });
    }
}