Struct LogDispatcher 

pub struct LogDispatcher { /* private fields */ }

Thread-safe fan-out dispatcher; ordinary sinks receive only sanitized events.

Implementations

impl LogDispatcher

pub fn new(policy: LogPolicy, sinks: Vec<Arc<dyn LogSink>>) -> Self

Creates a dispatcher with explicit filtering and sinks.

Examples found in repository

examples/component_filter.rs (line 26)

fn main() {
    // All components start at V4, keeping normal output concise.
    let mut policy = LogPolicy::new(Verbosity::V4);

    // Synchronization may need temporary I/O and timing diagnostics.
    policy.set_component("sync", Verbosity::V8);

    let log = LogDispatcher::new(policy, vec![Arc::new(ConsoleSink::new())]);

    let event = log.event(0, "sync");

    // This V7 event is selected only because the sync override allows it.
    event.verbosity(7).debug("batch details");
}

examples/sensitive_diagnostics.rs (line 48)

fn main() -> Result<(), appcore_log::LogError> {
    let key_id = KeyId::new("example-log-key").map_err(|_| appcore_log::LogError::Encryption)?;

    let provider =
        StaticDntKeyProvider::new().with_key(key_id.clone(), SecretKey::new(demo_key()?));

    // The sink bounds the encrypted snapshot by both bytes and event count.
    let sink = SensitiveDntSink::new(
        SensitiveDntSinkConfig {
            path: std::env::temp_dir().join("appcore-sensitive-log.dnt"),
            application_id: ApplicationId::new("example-log")
                .map_err(|_| appcore_log::LogError::Encryption)?,
            key_id,
            max_bytes: 4096,
            max_events: 8,
            retention: 2,
        },
        provider,
    )?;

    // Sensitive mode must be explicit and has no console or JSONL fallback.
    let mut policy = LogPolicy::default();
    policy.sensitivity = Sensitivity::Sensitive;

    let log = LogDispatcher::new(policy, vec![Arc::new(sink)]);

    log.event(0, "security").verbosity(2).error("diagnostic");

    Ok(())
}

examples/async_file.rs (line 40)

fn main() -> Result<(), LogError> {
    let directory = std::path::PathBuf::from("target/appcore-log-example");
    std::fs::create_dir_all(&directory).map_err(|_| LogError::Io)?;

    let path = directory.join("async.jsonl");
    let file = Arc::new(FileSink::new(FileSinkConfig {
        path: path.clone(),
        max_bytes: LOG_SIZE_8_MIB,
        sync_each_write: true,
        retention: 2,
        archive: None,
    })?);

    // This queue retains at most 256 events and 1 MiB, including active I/O.
    let asynchronous = Arc::new(AsyncSink::new(
        AsyncSinkConfig {
            max_events: 256,
            max_bytes: 1024 * 1024,
        },
        file,
    )?);
    let dispatcher = LogDispatcher::new(LogPolicy::default(), vec![asynchronous.clone()]);
    let log = dispatcher.event(0, "application");

    log.info("application started");
    log.warn("storage response is slow");

    // The lifecycle owner drains durable writes before exiting.
    asynchronous.shutdown()?;
    let path = std::fs::canonicalize(path).map_err(|_| LogError::Io)?;
    println!("log written to {}", path.display());
    Ok(())
}

pub fn emit(&self, event: LogEvent)

Emits once. Critical failure accounting is retained even when a sink fails.

pub fn event<'a>( &'a self, timestamp_ms: u64, component: impl Into<Cow<'a, str>>, ) -> LogBuilder<'a>

Creates a fluent event builder for a stable component and clock value.

Examples found in repository

examples/component_filter.rs (line 28)

fn main() {
    // All components start at V4, keeping normal output concise.
    let mut policy = LogPolicy::new(Verbosity::V4);

    // Synchronization may need temporary I/O and timing diagnostics.
    policy.set_component("sync", Verbosity::V8);

    let log = LogDispatcher::new(policy, vec![Arc::new(ConsoleSink::new())]);

    let event = log.event(0, "sync");

    // This V7 event is selected only because the sync override allows it.
    event.verbosity(7).debug("batch details");
}

examples/basic.rs (line 27)

fn main() -> Result<(), appcore_log::LogConfigError> {
    // Safe V4 terminal logging is explicit and creates no global state.
    let logger = LoggerConfig {
        output: LogOutputMode::Terminal,
        ..LoggerConfig::default()
    }
    .build()?;

    // The builder defaults to V4 and can be kept for related events.
    let log = logger.dispatcher().event(0, "application");

    log.info("application started");
    log.warn("connection is slower than expected");
    log.error("document could not be saved");

    Ok(())
}

examples/output_modes.rs (line 34)

fn main() -> Result<(), appcore_log::LogConfigError> {
    // Replace this with Disabled, Terminal, File, TerminalAndFile or CrashOnly.
    let output = LogOutputMode::CrashOnly;

    let logger = LoggerConfig {
        output,
        file: Some(FileSinkConfig {
            path: std::env::temp_dir().join("my-application-crash.jsonl"),
            max_bytes: LOG_SIZE_2_MIB,
            sync_each_write: true,
            retention: 1,
            archive: None,
        }),
        crash_events: 128,
        crash_bytes: 512 * 1024,
        ..LoggerConfig::default()
    }
    .build()?;

    let log = logger.dispatcher().event(0, "application");

    log.info("kept only in the bounded crash ring");

    // Call this from the application's panic/crash boundary. In every other
    // mode it is a no-op and returns zero.
    let _written_events = logger.dump_crash()?;

    Ok(())
}

examples/sensitive_diagnostics.rs (line 50)

fn main() -> Result<(), appcore_log::LogError> {
    let key_id = KeyId::new("example-log-key").map_err(|_| appcore_log::LogError::Encryption)?;

    let provider =
        StaticDntKeyProvider::new().with_key(key_id.clone(), SecretKey::new(demo_key()?));

    // The sink bounds the encrypted snapshot by both bytes and event count.
    let sink = SensitiveDntSink::new(
        SensitiveDntSinkConfig {
            path: std::env::temp_dir().join("appcore-sensitive-log.dnt"),
            application_id: ApplicationId::new("example-log")
                .map_err(|_| appcore_log::LogError::Encryption)?,
            key_id,
            max_bytes: 4096,
            max_events: 8,
            retention: 2,
        },
        provider,
    )?;

    // Sensitive mode must be explicit and has no console or JSONL fallback.
    let mut policy = LogPolicy::default();
    policy.sensitivity = Sensitivity::Sensitive;

    let log = LogDispatcher::new(policy, vec![Arc::new(sink)]);

    log.event(0, "security").verbosity(2).error("diagnostic");

    Ok(())
}

examples/async_file.rs (line 41)

fn main() -> Result<(), LogError> {
    let directory = std::path::PathBuf::from("target/appcore-log-example");
    std::fs::create_dir_all(&directory).map_err(|_| LogError::Io)?;

    let path = directory.join("async.jsonl");
    let file = Arc::new(FileSink::new(FileSinkConfig {
        path: path.clone(),
        max_bytes: LOG_SIZE_8_MIB,
        sync_each_write: true,
        retention: 2,
        archive: None,
    })?);

    // This queue retains at most 256 events and 1 MiB, including active I/O.
    let asynchronous = Arc::new(AsyncSink::new(
        AsyncSinkConfig {
            max_events: 256,
            max_bytes: 1024 * 1024,
        },
        file,
    )?);
    let dispatcher = LogDispatcher::new(LogPolicy::default(), vec![asynchronous.clone()]);
    let log = dispatcher.event(0, "application");

    log.info("application started");
    log.warn("storage response is slow");

    // The lifecycle owner drains durable writes before exiting.
    asynchronous.shutdown()?;
    let path = std::fs::canonicalize(path).map_err(|_| LogError::Io)?;
    println!("log written to {}", path.display());
    Ok(())
}

examples/file_logging.rs (line 52)

fn main() -> Result<(), appcore_log::LogConfigError> {
    // Keep generated output predictable and inside Cargo's ignored target tree.
    let output_directory = PathBuf::from("target/appcore-log-example");
    std::fs::create_dir_all(&output_directory).map_err(|_| LogConfigError::Sink(LogError::Io))?;

    let active_file = output_directory.join("application.jsonl");

    // Two rotations stay beside the active file. Older rotations move into
    // archive/YYYY/MM and the complete archive never exceeds 120 files.
    let archive_directory = output_directory.join("archive");
    let mut policy = LogPolicy::new(Verbosity::V4);
    policy.set_component("sync", Verbosity::V8);

    let logger = LoggerConfig {
        policy,
        output: LogOutputMode::TerminalAndFile,
        file: Some(FileSinkConfig {
            path: active_file,
            max_bytes: LOG_SIZE_8_MIB,
            sync_each_write: false,
            retention: 2,
            archive: Some(FileArchiveConfig {
                directory: archive_directory,
                max_files: 120,
            }),
        }),
        ..LoggerConfig::default()
    }
    .build()?;

    let application = logger.dispatcher().event(0, "application");
    let sync = logger.dispatcher().event(1, "sync.transport");

    application.info("application ready; inspect target/appcore-log-example/application.jsonl");

    // The parent component policy makes this V7 diagnostic visible.
    sync.verbosity(7).debug("replication batch sent");

    sync.warn("peer response was delayed");

    let stats = logger.dispatcher().stats();
    assert_eq!(stats.sink_failures, 0);

    Ok(())
}

pub fn event_now<'a>( &'a self, clock: &dyn LogClock, component: impl Into<Cow<'a, str>>, ) -> LogBuilder<'a>

Creates a fluent event builder using an injected clock.

pub fn enabled(&self, component: &str, verbosity: Verbosity) -> bool

Reports whether a component and verbosity would reach at least one sink.

pub fn stats(&self) -> LogStats

Returns counters without taking global locks.

Examples found in repository

examples/file_logging.rs (line 62)

fn main() -> Result<(), appcore_log::LogConfigError> {
    // Keep generated output predictable and inside Cargo's ignored target tree.
    let output_directory = PathBuf::from("target/appcore-log-example");
    std::fs::create_dir_all(&output_directory).map_err(|_| LogConfigError::Sink(LogError::Io))?;

    let active_file = output_directory.join("application.jsonl");

    // Two rotations stay beside the active file. Older rotations move into
    // archive/YYYY/MM and the complete archive never exceeds 120 files.
    let archive_directory = output_directory.join("archive");
    let mut policy = LogPolicy::new(Verbosity::V4);
    policy.set_component("sync", Verbosity::V8);

    let logger = LoggerConfig {
        policy,
        output: LogOutputMode::TerminalAndFile,
        file: Some(FileSinkConfig {
            path: active_file,
            max_bytes: LOG_SIZE_8_MIB,
            sync_each_write: false,
            retention: 2,
            archive: Some(FileArchiveConfig {
                directory: archive_directory,
                max_files: 120,
            }),
        }),
        ..LoggerConfig::default()
    }
    .build()?;

    let application = logger.dispatcher().event(0, "application");
    let sync = logger.dispatcher().event(1, "sync.transport");

    application.info("application ready; inspect target/appcore-log-example/application.jsonl");

    // The parent component policy makes this V7 diagnostic visible.
    sync.verbosity(7).debug("replication batch sent");

    sync.warn("peer response was delayed");

    let stats = logger.dispatcher().stats();
    assert_eq!(stats.sink_failures, 0);

    Ok(())
}

pub fn sink_stats(&self) -> Vec<SinkStats>

Returns bounded failure counters for each configured sink.