Struct Logger 

pub struct Logger { /* private fields */ }

Manages, controls and manipulates multiple sinks.

Logger is an entry point for a log to be processed, the Logger::log method will be called by logging macros.

---

A Logger:

• contains one or more sinks, each log will be passed into sinks in sequence;

• has a level filter of its own, which is not shared with the level filter of sinks;

• has automatic flushing policies that can be optionally enabled:

  • Flush level filter: Flush once when the filter returns true for a log.
  • Flush period: Flush periodically.

  These two automatic flushing policies can work at the same time.

---

spdlog-rs has a global default_logger, you can modify it, or configure a new logger to suit your needs and then replace it. Basically for a lightweight program, such a global singleton logger is enough. For a complex program, for example if you have a number of different components, you can also configure multiple loggers and store them independently inside the component struct, which allows different components to have different approaches for logging.

Examples

• Logging to the global default logger.

use spdlog::prelude::*;

info!("logging to the default logger");

spdlog::default_logger().set_level_filter(LevelFilter::All);
trace!("logging to the default logger at trace level");

• Logging to a separated logger.

let separated_logger = /* ... */

info!(logger: separated_logger, "logging to a separated logger");
error!(logger: separated_logger, "logging to a separated logger at error level");

• Fork, configure and replace the default logger.

let new_logger = spdlog::default_logger().fork_with(|new_logger| {
    // Configure the new logger...
    Ok(())
})?;
spdlog::set_default_logger(new_logger);
info!("logging to the default logger, but it's reconfigured");

• For more examples, see ./examples directory.

Implementations

impl Logger

pub fn builder() -> LoggerBuilder

Gets a LoggerBuilder with default parameters:

Parameter	Default Value
name	None
sinks	[]
level_filter	MoreSevereEqual(Info)
flush_level_filter	LevelFilter::Off
flush_period	None
error_handler	ErrorHandler::default()

Examples found in repository

examples/02-file.rs (line 22)

fn configure_file_logger() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("file.log");

    let file_sink = FileSink::builder().path(path).build_arc()?;
    let new_logger = Logger::builder().sink(file_sink).build_arc()?;
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `all.log`");

    Ok(())
}

fn configure_rotating_daily_file_logger() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("rotating_daily.log");

    let file_sink = RotatingFileSink::builder()
        .base_path(path)
        .rotation_policy(RotationPolicy::Daily { hour: 0, minute: 0 })
        .build_arc()?;
    let new_logger = Logger::builder().sink(file_sink).build_arc()?;
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `rotating_daily.log`, and the file will be rotated daily at 00:00");

    Ok(())
}

fn configure_rotating_size_file_logger() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("rotating_size.log");

    let file_sink = RotatingFileSink::builder()
        .base_path(path)
        .rotation_policy(RotationPolicy::FileSize(1024))
        .build_arc()?;
    let new_logger = Logger::builder().sink(file_sink).build_arc()?;
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `rotating_size.log`, and the file will be rotated when its size reaches 1024 bytes");

    Ok(())
}

fn configure_rotating_hourly_file_logger() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("rotating_hourly.log");

    let file_sink = RotatingFileSink::builder()
        .base_path(path)
        .rotation_policy(RotationPolicy::Hourly)
        .build_arc()?;
    let new_logger = Logger::builder().sink(file_sink).build_arc()?;
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `rotating_hourly.log`, and the file will be rotated every hour");

    Ok(())
}

fn configure_rotating_period_file_logger() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("rotating_period.log");

    let file_sink = RotatingFileSink::builder()
        .base_path(path)
        .rotation_policy(RotationPolicy::Period(Duration::from_secs(
            60 * 90, // 90 minutes
        )))
        .build_arc()?;
    let new_logger = Logger::builder().sink(file_sink).build_arc()?;
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `rotating_period.log`, and the file will be rotated every 1.5 hours");

    Ok(())
}

examples/07-async.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = env::current_exe()?.with_file_name("async.log");
    let file_sink = FileSink::builder().path(path).build_arc()?;

    // AsyncPoolSink is a combined sink which wraps other sinks
    let async_pool_sink = AsyncPoolSink::builder().sink(file_sink).build_arc()?;

    let async_logger = Logger::builder()
        .sink(async_pool_sink)
        .flush_level_filter(LevelFilter::All)
        .build_arc()?;

    info!(logger: async_logger, "Hello, async!");

    Ok(())
}

examples/05-sink.rs (line 52)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let my_sink = Arc::new(CollectVecSink::new());
    let example = Logger::builder().sink(my_sink.clone()).build()?;

    info!(logger: example, "Hello, world!");
    warn!(logger: example, "Meow~");

    let collected = my_sink.collected();
    println!("collected:\n{collected:#?}");

    assert_eq!(collected.len(), 2);
    assert!(collected[0].contains("[info]") && collected[0].contains("Hello, world!"));
    assert!(collected[1].contains("[warn]") && collected[1].contains("Meow~"));

    Ok(())
}

examples/03-logger.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // `spdlog-rs` has a global default logger and logs will be processed by it
    // by default, You can configure it.
    let default_logger = spdlog::default_logger();
    default_logger.set_level_filter(LevelFilter::All);

    // Or completely replace it with a new one.
    let path = env::current_exe()?.with_file_name("all.log");
    let file_sink = FileSink::builder().path(path).build_arc()?;

    let new_logger = Logger::builder()
        .level_filter(LevelFilter::All)
        .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
        .sink(file_sink.clone())
        .build_arc()?;
    new_logger.set_flush_period(Some(Duration::from_secs(3)));
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `all.log`");

    // In addition to having the global default logger, more loggers are allowed to
    // be configured, stored and used independently.
    let db = AppDatabase::new(file_sink)?;
    db.write_i32(114514);

    Ok(())
}

struct AppDatabase {
    logger: Logger,
}

impl AppDatabase {
    fn new(all_log_sink: Arc<dyn Sink>) -> Result<Self, Box<dyn std::error::Error>> {
        let path = env::current_exe()?.with_file_name("db.log");
        let db_file_sink = FileSink::builder().path(path).build_arc()?;

        let logger = Logger::builder()
            .name("database")
            .level_filter(LevelFilter::All)
            .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
            .sinks([all_log_sink, db_file_sink])
            .build()?;
        Ok(Self { logger })
    }

pub fn name(&self) -> Option<&str>

Gets the logger name.

Returns None if the logger does not have a name.

pub fn set_name<S>( &mut self, name: Option<S>, ) -> StdResult<(), SetLoggerNameError>

where S: Into<String>,

Sets the logger name.

Examples found in repository

examples/native/linux.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use spdlog::{prelude::*, sink::JournaldSink};

    let sink = JournaldSink::builder().build_arc()?;
    let logger = spdlog::default_logger().fork_with(|logger| {
        logger.set_name(Some("demo")).unwrap();
        logger.sinks_mut().push(sink);
        Ok(())
    })?;
    spdlog::set_default_logger(logger);

    info!("info message from spdlog-rs's JournaldSink");
    error!("error message from spdlog-rs's JournaldSink", kv: { error_code = 114514 });
    Ok(())
}

pub fn should_log(&self, level: Level) -> bool

Determines if a log with the specified level would be logged.

This allows callers to avoid expensive computation of log arguments if the would be discarded anyway.

Examples

use spdlog::prelude::*;

logger.set_level_filter(LevelFilter::MoreSevere(Level::Info));
assert_eq!(logger.should_log(Level::Debug), false);
assert_eq!(logger.should_log(Level::Info), false);
assert_eq!(logger.should_log(Level::Warn), true);
assert_eq!(logger.should_log(Level::Error), true);

logger.set_level_filter(LevelFilter::All);
assert_eq!(logger.should_log(Level::Debug), true);
assert_eq!(logger.should_log(Level::Info), true);
assert_eq!(logger.should_log(Level::Warn), true);
assert_eq!(logger.should_log(Level::Error), true);

pub fn log(&self, record: &Record<'_>)

Passes a log into sinks in sequence.

It calls Sink::log method internally for each sink in sequence.

Note

Users usually do not use this function directly, use logging macros instead.

pub fn flush(&self)

Flushes sinks explicitly.

It calls Sink::flush method internally for each sink in sequence.

Users can call this function to flush explicitly and/or use automatic flushing policies. See also Logger::flush_level_filter and Logger::set_flush_period.

Be aware that the method can be expensive, calling it frequently may affect performance.

pub fn flush_level_filter(&self) -> LevelFilter

Gets the flush level filter.

pub fn set_flush_level_filter(&self, level_filter: LevelFilter)

Sets a flush level filter.

When logging a new record, flush the buffer if this filter condition returns true.

This automatic flushing policy can work with Logger::set_flush_period at the same time.

Examples

use spdlog::prelude::*;

logger.set_flush_level_filter(LevelFilter::Off);
trace!(logger: logger, "hello");
trace!(logger: logger, "world");
// Until here the buffer may not have been flushed (depending on sinks implementation)

logger.set_flush_level_filter(LevelFilter::All);
trace!(logger: logger, "hello"); // Logs and flushes the buffer once
trace!(logger: logger, "world"); // Logs and flushes the buffer once

pub fn level_filter(&self) -> LevelFilter

Gets the log level filter.

pub fn set_level_filter(&self, level_filter: LevelFilter)

Sets the log level filter.

Examples

See Logger::should_log.

Examples found in repository

examples/01-macro.rs (line 18)

fn main() {
    // Writes a log at "info" level, and this log will be processed by the global
    // default logger - It will be output to `stdout`.
    info!("program started");

    // They will be output to `stderr`.
    let file = "config.json";
    error!("failed to open file: {}", file);
    warn!("undetermined locale, defaults to `en_US.UTF-8`");

    // Level "trace" and "debug" will be ignored by default, you can modify the
    // level filter of the global default logger to enable all levels.
    let verbose = true;
    if verbose {
        spdlog::default_logger().set_level_filter(LevelFilter::All);
    }

    trace!("position x: {}, y: {}", 11.4, -5.14);
    // Or if you prefer structured logging.
    trace!("position", kv: { x = 11.4, y = -5.14 });
}

examples/03-logger.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // `spdlog-rs` has a global default logger and logs will be processed by it
    // by default, You can configure it.
    let default_logger = spdlog::default_logger();
    default_logger.set_level_filter(LevelFilter::All);

    // Or completely replace it with a new one.
    let path = env::current_exe()?.with_file_name("all.log");
    let file_sink = FileSink::builder().path(path).build_arc()?;

    let new_logger = Logger::builder()
        .level_filter(LevelFilter::All)
        .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
        .sink(file_sink.clone())
        .build_arc()?;
    new_logger.set_flush_period(Some(Duration::from_secs(3)));
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `all.log`");

    // In addition to having the global default logger, more loggers are allowed to
    // be configured, stored and used independently.
    let db = AppDatabase::new(file_sink)?;
    db.write_i32(114514);

    Ok(())
}

pub fn set_flush_period(self: &Arc<Self>, interval: Option<Duration>)

Sets automatic periodic flushing.

This function receives a &Arc<Self>. Calling it will spawn a new thread internally.

This automatic flushing policy can work with Logger::set_flush_level_filter at the same time.

Panics

• Panics if interval is zero.

• Panics if this function is called with Some value and then clones the Logger instead of the Arc<Logger>.

Examples

use std::time::Duration;

// From now on, the `logger` will automatically call `flush` method the every 10 seconds.
logger.set_flush_period(Some(Duration::from_secs(10)));

// Disable automatic periodic flushing.
logger.set_flush_period(None);

Examples found in repository

examples/03-logger.rs (line 23)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // `spdlog-rs` has a global default logger and logs will be processed by it
    // by default, You can configure it.
    let default_logger = spdlog::default_logger();
    default_logger.set_level_filter(LevelFilter::All);

    // Or completely replace it with a new one.
    let path = env::current_exe()?.with_file_name("all.log");
    let file_sink = FileSink::builder().path(path).build_arc()?;

    let new_logger = Logger::builder()
        .level_filter(LevelFilter::All)
        .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
        .sink(file_sink.clone())
        .build_arc()?;
    new_logger.set_flush_period(Some(Duration::from_secs(3)));
    spdlog::set_default_logger(new_logger);

    info!("this log will be written to the file `all.log`");

    // In addition to having the global default logger, more loggers are allowed to
    // be configured, stored and used independently.
    let db = AppDatabase::new(file_sink)?;
    db.write_i32(114514);

    Ok(())
}

pub fn sinks(&self) -> &[Arc<dyn Sink>]

Gets a reference to sinks in the logger.

Examples found in repository

examples/04-format.rs (line 26)

fn use_pattern_formatter() {
    use spdlog::{
        formatter::{pattern, PatternFormatter},
        prelude::*,
    };

    // Building a pattern formatter with a pattern.
    // The `pattern!` macro will parse the template string at compile-time.
    let new_formatter = Box::new(PatternFormatter::new(pattern!(
        "{datetime} - {^{level}} - {payload}{eol}"
    )));

    // Setting the new formatter for each sink of the default logger.
    for sink in spdlog::default_logger().sinks() {
        sink.set_formatter(new_formatter.clone())
    }

    info!("format by `PatternFormatter`");
}

fn impl_manually() {
    use std::fmt::Write;

    use spdlog::{
        formatter::{Formatter, FormatterContext},
        prelude::*,
        Record, StringBuf,
    };

    #[derive(Clone, Default)]
    struct MyFormatter;

    impl Formatter for MyFormatter {
        fn format(
            &self,
            record: &Record,
            dest: &mut StringBuf,
            ctx: &mut FormatterContext,
        ) -> spdlog::Result<()> {
            let style_range_begin = dest.len();

            dest.write_str(&record.level().as_str().to_ascii_uppercase())
                .map_err(spdlog::Error::FormatRecord)?;

            let style_range_end = dest.len();

            writeln!(dest, " {}", record.payload()).map_err(spdlog::Error::FormatRecord)?;

            ctx.set_style_range(Some(style_range_begin..style_range_end));
            Ok(())
        }
    }

    // Building a custom formatter.
    let new_formatter = Box::new(MyFormatter);

    // Setting the new formatter for each sink of the default logger.
    for sink in spdlog::default_logger().sinks() {
        sink.set_formatter(new_formatter.clone())
    }

    info!("format by `MyFormatter` (impl manually)");
}

pub fn sinks_mut(&mut self) -> &mut Sinks

Gets a mutable reference to sinks in the logger.

Examples found in repository

examples/native/linux.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use spdlog::{prelude::*, sink::JournaldSink};

    let sink = JournaldSink::builder().build_arc()?;
    let logger = spdlog::default_logger().fork_with(|logger| {
        logger.set_name(Some("demo")).unwrap();
        logger.sinks_mut().push(sink);
        Ok(())
    })?;
    spdlog::set_default_logger(logger);

    info!("info message from spdlog-rs's JournaldSink");
    error!("error message from spdlog-rs's JournaldSink", kv: { error_code = 114514 });
    Ok(())
}

pub fn set_error_handler<F: Into<ErrorHandler>>(&self, handler: F)

Sets a error handler.

If an error occurs while logging or flushing, this handler will be called. If no handler is set, the error will be print to stderr and then ignored.

Examples

use spdlog::prelude::*;

spdlog::default_logger().set_error_handler(|err| {
    panic!("An error occurred in the default logger: {}", err)
});

pub fn fork_with<F>(self: &Arc<Self>, modifier: F) -> Result<Arc<Self>>

where F: FnOnce(&mut Logger) -> Result<()>,

Forks and configures a separate new logger.

This function creates a new logger object that inherits logger properties from Arc<Self>. Then this function calls the given modifier function which configures the properties on the new logger object. The created new logger object will be a separate object from Arc<Self>. (No ownership sharing)

Examples

let old: Arc<Logger> = /* ... */
// Fork from an existing logger and add a new sink.
let new = old.fork_with(|new| {
    new.sinks_mut().push(new_sink);
    Ok(())
})?;

info!(logger: new, "this record will be written to `new_sink`");
info!(logger: old, "this record will not be written to `new_sink`");

Examples found in repository

examples/native/linux.rs (lines 6-10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use spdlog::{prelude::*, sink::JournaldSink};

    let sink = JournaldSink::builder().build_arc()?;
    let logger = spdlog::default_logger().fork_with(|logger| {
        logger.set_name(Some("demo")).unwrap();
        logger.sinks_mut().push(sink);
        Ok(())
    })?;
    spdlog::set_default_logger(logger);

    info!("info message from spdlog-rs's JournaldSink");
    error!("error message from spdlog-rs's JournaldSink", kv: { error_code = 114514 });
    Ok(())
}

pub fn fork_with_name<S>( self: &Arc<Self>, new_name: Option<S>, ) -> Result<Arc<Self>>

where S: Into<String>,

Forks a separates new logger with a new name.

This function creates a new logger object that inherits logger properties from Arc<Self> and rename the new logger object to the given name. The created new logger object will be a separate object from Arc<Self>. (No ownership sharing)

This is a shorthand wrapper for Logger::fork_with.

Examples

let old = Logger::builder().name("dog").build_arc()?;
let new = old.fork_with_name(Some("cat"))?;

assert_eq!(old.name(), Some("dog"));
assert_eq!(new.name(), Some("cat"));

Examples found in repository

examples/06-log-crate.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    spdlog::init_log_crate_proxy()
        .expect("users should only call `init_log_crate_proxy` function once");

    // Setup filter as needed.
    let filter = env_filter::Builder::new().try_parse("RUST_LOG")?.build();
    spdlog::log_crate_proxy().set_filter(Some(filter));

    log::set_max_level(log::LevelFilter::Trace);
    log::trace!("this log will be processed by the global default logger in spdlog-rs");

    let custom_logger = spdlog::default_logger().fork_with_name(Some("another_logger"))?;
    spdlog::log_crate_proxy().set_logger(Some(custom_logger));
    log::info!("this log will be processed by custom_logger in spdlog-rs");

    spdlog::log_crate_proxy().set_logger(None);
    log::trace!("this log will be processed by the global default logger in spdlog-rs");

    Ok(())
}

Trait Implementations

impl Clone for Logger

fn clone(&self) -> Self

Clones the Logger.

Panics

Panics if Logger::set_flush_period is called with Some value and then clones the Logger instead of the Arc<Logger>.

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

Performs copy-assignment from source.

impl Debug for Logger

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.