Struct Builder

pub struct Builder { /* private fields */ }

Ftlog builder

let logger = ftlog::builder()
    // use our own format
    .format(ftlog::FtLogFormatter)
    // global max log level
    .max_log_level(LevelFilter::Info)
    // define root appender, pass anything that is Write and Send
    // omit `Builder::root` to write to stderr
    .root(FileAppender::rotate_with_expire(
        "./current.log",
        Period::Day,
        Duration::days(7),
    ))
    // ---------- configure additional filter ----------
    // write to "ftlog-appender" appender, with different level filter
    .filter("ftlog::appender", "ftlog-appender", LevelFilter::Error)
    // write to root appender, but with different level filter
    .filter("ftlog", None, LevelFilter::Trace)
    // write to "ftlog" appender, with default level filter
    .filter("ftlog::appender::file", "ftlog", None)
    // ----------  configure additional appender ----------
    // new appender
    .appender("ftlog-appender", FileAppender::new("ftlog-appender.log"))
    // new appender, rotate to new file every Day
    .appender("ftlog", FileAppender::rotate("ftlog.log", Period::Day))
    .build()
    .expect("logger build failed");

Local timezone

For performance reason, ftlog only retrieves timezone info once and use this local timezone offset forever. Thus timestamp in log does not aware of timezone change by OS.

Implementations

impl Builder

pub fn new() -> Builder

Create a ftlog builder with default settings:

• global log level: INFO
• root log level: INFO
• default formatter: FtLogFormatter
• output to stderr
• bounded channel between worker thread and log thread, with a size limit of 100_000
• discard excessive log messages
• log with timestamp of local timezone

pub fn format<F: FtLogFormat + 'static>(self, format: F) -> Builder

Set custom formatter

pub fn bounded(self, size: usize, block_when_full: bool) -> Builder

bound channel between worker thread and log thread

When block_when_full is true, it will block current thread where log macro (e.g. log::info) is called until log thread is able to handle new message. Otherwises, excessive log messages will be discarded.

By default, excessive log messages is discarded silently. To show how many log messages have been dropped, see Builder::print_omitted_count().

pub fn print_omitted_count(self, print: bool) -> Builder

whether to print the number of omitted logs if channel to log thread is bounded, and set to discard excessive log messages

pub fn unbounded(self) -> Builder

set channel size to unbound

ATTENTION: too much log message will lead to huge memory consumption, as log messages are queued to be handled by log thread. When log message exceed the current channel size, it will double the size by default, Since channel expansion asks for memory allocation, log calls can be slow down.

pub fn appender( self, name: &'static str, appender: impl Write + Send + 'static, ) -> Builder

Add an additional appender with a name

Combine with Builder::filter(), ftlog can output log in different module path to different output target.

pub fn filter<A: Into<Option<&'static str>>, L: Into<Option<LevelFilter>>>( self, module_path: &'static str, appender: A, level: L, ) -> Builder

Add a filter to redirect log to different output target (e.g. stderr, stdout, different files).

ATTENTION: level more verbose than Builder::max_log_level will be ignored. Say we configure max_log_level to INFO, and even if filter’s level is set to DEBUG, ftlog will still log up to INFO.

pub fn max_log_level(self, level: LevelFilter) -> Builder

Set max log level

Logs with level more verbose than this will not be sent to log thread.

pub fn root_log_level(self, level: LevelFilter) -> Builder

Set max log level

Logs with level more verbose than this will not be sent to log thread.

pub fn build(self) -> Result<Logger, IoError>

Finish building ftlog logger

The call spawns a log thread to formatting log message into string, and write to output target.

pub fn try_init(self) -> Result<LoggerGuard, Box<dyn Error>>

try building and setting as global logger

Trait Implementations

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.