Struct flexi_logger::LoggerHandle

pub struct LoggerHandle { /* private fields */ }

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.

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_outputfile(&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!

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::NoFileLogger if no file log writer is configured.

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.

impl LogSpecSubscriber for LoggerHandle

fn set_new_spec(
    &mut self,
    new_spec: LogSpecification
) -> Result<(), FlexiLoggerError>

Apply a new LogSpecification.

fn initial_spec(&self) -> Result<LogSpecification, FlexiLoggerError>

Provide the current log spec.