Struct LoggerHandle

pub struct LoggerHandle
where
    Self: Send + Sync,
{ /* private fields */ }

Allows reconfiguring the logger while the program is running, and shuts down the logger when it is dropped.

A LoggerHandle is returned from Logger::start() and from Logger::start_with_specfile().

Keep it alive until the very end of your program, because it shuts down the logger when its dropped! (This is only relevant if you use one of Logger::log_to_file, Logger::log_to_writer, or Logger::log_to_file_and_writer, or a buffering or asynchronous WriteMode).

LoggerHandle offers methods to modify the log specification programmatically, to flush the logger explicitly, and to reconfigure the used FileLogWriter – if one is used.

Examples

In more trivial configurations, dropping the LoggerHandle has no effect and then you can safely ignore the return value of Logger::start():

use flexi_logger::Logger;
use std::error::Error;
fn main() -> Result<(), Box<dyn Error>> {
    Logger::try_with_str("info")?.start()?;
    // do work
    Ok(())
}

When logging to a file or another writer, and/or if you use a buffering or asynchronous WriteMode, keep the LoggerHandle alive until the program ends:

use flexi_logger::{FileSpec, Logger};
use std::error::Error;
fn main() -> Result<(), Box<dyn Error>> {
    let _logger = Logger::try_with_str("info")?
        .log_to_file(FileSpec::default())
        .start()?;
    // do work
    Ok(())
}

You can use the logger handle to permanently exchange the log specification programmatically, anywhere in your code:

    let logger = Logger::try_with_str("info")?.start()?;
    // ...
    logger.parse_new_spec("warn");
    // ...

However, when debugging, you often want to modify the log spec only temporarily, for
one or few method calls only; this is easier done with the following method, because it allows switching back to the previous spec:

    let mut logger = Logger::try_with_str("info")?.start()?;
    logger.parse_and_push_temp_spec("trace");
    // ...
    // critical calls
    // ...
    logger.pop_temp_spec();
    // Continue with the log spec you had before.
    // ...

Implementations

impl LoggerHandle

pub fn set_new_spec(&self, new_spec: LogSpecification)

Replaces the active LogSpecification.

pub fn parse_new_spec(&self, spec: &str) -> Result<(), FlexiLoggerError>

Tries to replace the active LogSpecification with the result from parsing the given String.

Errors

FlexiLoggerError::Parse if the input is malformed.

pub fn push_temp_spec(&mut self, new_spec: LogSpecification)

Replaces the active LogSpecification and pushes the previous one to a stack.

pub fn parse_and_push_temp_spec<S: AsRef<str>>( &mut self, new_spec: S, ) -> Result<(), FlexiLoggerError>

Tries to replace the active LogSpecification with the result from parsing the given String and pushes the previous one to a Stack.

Errors

FlexiLoggerError::Parse if the input is malformed.

pub fn pop_temp_spec(&mut self)

Reverts to the previous LogSpecification, if any.

pub fn flush(&self)

Flush all writers.

pub fn reset_flw( &self, flwb: &FileLogWriterBuilder, ) -> Result<(), FlexiLoggerError>

Replaces parts of the configuration of the file log writer.

Note that neither the write mode nor the format function can be reset and that the provided FileLogWriterBuilder must have the same values for these as the currently used FileLogWriter.

Example

See code_examples.

Errors

FlexiLoggerError::NoFileLogger if no file log writer is configured.

FlexiLoggerError::Reset if a reset was tried with a different write mode.

FlexiLoggerError::Io if the specified path doesn’t work.

FlexiLoggerError::Poison if some mutex is poisoned.

pub fn flw_config(&self) -> Result<FileLogWriterConfig, FlexiLoggerError>

Returns the current configuration of the file log writer.

Errors

FlexiLoggerError::NoFileLogger if no file log writer is configured.

FlexiLoggerError::Poison if some mutex is poisoned.

pub fn reopen_output(&self) -> Result<(), FlexiLoggerError>

Makes the logger re-open the current log file.

If the log is written to a file, flexi_logger expects that nobody else modifies the file, and offers capabilities to rotate, compress, and clean up log files.

However, if you use tools like linux’ logrotate to rename or delete the current output file, you need to inform flexi_logger about such actions by calling this method. Otherwise flexi_logger will not stop writing to the renamed or even deleted file!

In more complex configurations, i.e. when more than one output stream is written to, all of them will be attempted to be re-opened; only the first error will be reported.

Example

logrotate e.g. can be configured to send a SIGHUP signal to your program. You need to handle SIGHUP in your program explicitly, e.g. using a crate like ctrlc, and call this function from the registered signal handler.

Errors

FlexiLoggerError::Poison if some mutex is poisoned.

Other variants of FlexiLoggerError, depending on the used writers.

pub fn trigger_rotation(&self) -> Result<(), FlexiLoggerError>

Trigger an extra log file rotation.

Does nothing if rotation is not configured.

Errors

FlexiLoggerError::Poison if some mutex is poisoned.

IO errors.

pub fn shutdown(&self)

Shutdown all participating writers.

This method is supposed to be called at the very end of your program, if

• you use some Cleanup strategy with compression: then you want to ensure that a termination of your program does not interrput the cleanup-thread when it is compressing a log file, which could leave unexpected files in the filesystem
• you use your own writer(s), and they need to clean up resources

See also writers::LogWriter::shutdown.

pub fn existing_log_files( &self, selector: &LogfileSelector, ) -> Result<Vec<PathBuf>, FlexiLoggerError>

Returns the list of existing log files according to the current FileSpec.

Depending on the given selector, the list may include the CURRENT log file and the compressed files, if they exist. The list is empty if the logger is not configured for writing to files.

Errors

FlexiLoggerError::Poison if some mutex is poisoned.

pub fn adapt_duplication_to_stderr( &mut self, dup: Duplicate, ) -> Result<(), FlexiLoggerError>

Allows re-configuring duplication to stderr.

Errors

FlexiLoggerError::NoDuplication if FlexiLogger was initialized without duplication support

pub fn adapt_duplication_to_stdout( &mut self, dup: Duplicate, ) -> Result<(), FlexiLoggerError>

Allows re-configuring duplication to stdout.

Errors

FlexiLoggerError::NoDuplication if FlexiLogger was initialized without duplication support

Trait Implementations

impl Clone for LoggerHandle

where Self: Send + Sync,

fn clone(&self) -> LoggerHandle

Returns a copy of the value.

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

Performs copy-assignment from source.