Struct flexi_logger::LoggerHandle

pub struct LoggerHandle { /* fields omitted */ }

Shuts down the logger when dropped, and allows reconfiguring the logger programmatically.

A LoggerHandle is returned from Logger::start() and from Logger::start_with_specfile(). When the logger handle is dropped, then it shuts down the Logger! This matters if you use one of Logger::log_to_file, Logger::log_to_writer, or Logger::log_to_file_and_writer. It is then important to keep the logger handle alive until the very end of your program!

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

Examples

Since dropping the LoggerHandle has no effect if you use Logger::log_to_stderr (which is the default) or Logger::log_to_stdout. you can then safely ignore the return value of Logger::start():

    Logger::try_with_str("info")?
        .start()?;
    // ...

When logging to a file or another writer, keep the LoggerHandle alive until the program ends:

use flexi_logger::{FileSpec, Logger};
fn main() -> Result<(), Box<dyn std::error::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 mut logger = flexi_logger::Logger::try_with_str("info")?
        .start()
        .unwrap();
    // ...
    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:

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(&mut self, new_spec: LogSpecification)

Replaces the active LogSpecification.

pub fn parse_new_spec(&mut 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.

Errors

FlexiLoggerError::Reset if no file log writer is configured, or 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 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.

Trait Implementations

impl Clone for LoggerHandle

fn clone(&self) -> LoggerHandle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Drop for LoggerHandle

fn drop(&mut self)

Executes the destructor for this type.