Struct LogBuilder 

pub struct LogBuilder<'a> { /* private fields */ }

Fluent, component-scoped log emitter with an immutable per-event override.

Implementations

impl<'a> LogBuilder<'a>

pub fn component(&self, component: impl Into<Cow<'a, str>>) -> Self

Replaces the stable component used for filtering and rendering.

pub fn verbosity(&self, verbosity: u8) -> Self

Sets a V1–V9 threshold for this event; invalid values retain V4.

Use Self::try_verbosity when invalid configuration must be reported.

Examples found in repository

examples/component_filter.rs (line 31)

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 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/file_logging.rs (line 58)

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 try_verbosity(&self, verbosity: u8) -> Result<Self, VerbosityError>

Sets a V1–V9 threshold and returns invalid configuration explicitly.

pub fn trace(&self, message: impl Into<String>)

Emits a trace event.

pub fn debug(&self, message: impl Into<String>)

Emits a debug event.

Examples found in repository

examples/component_filter.rs (line 31)

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/file_logging.rs (line 58)

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 info(&self, message: impl Into<String>)

Emits an informational event.

Examples found in repository

examples/basic.rs (line 29)

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 36)

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/async_file.rs (line 43)

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 55)

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 warn(&self, message: impl Into<String>)

Emits a warning event.

Examples found in repository

examples/basic.rs (line 30)

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/async_file.rs (line 44)

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 60)

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 error(&self, message: impl Into<String>)

Emits an error event.

Examples found in repository

examples/basic.rs (line 31)

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/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(())
}

pub fn critical(&self, message: impl Into<String>)

Emits a critical event.

Trait Implementations

impl<'a> Clone for LogBuilder<'a>

fn clone(&self) -> LogBuilder<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.