pub struct LoggerHandle { /* private fields */ }
Expand description

Shuts down the logger when its last instance is dropped (in case you use LoggerHandle::clone() you can have multiple instances), and allows reconfiguring the logger programmatically.

A LoggerHandle is returned from Logger::start() and from Logger::start_with_specfile(). Keep it alive until the very end of your program if you use one of Logger::log_to_file, Logger::log_to_writer, or Logger::log_to_file_and_writer.

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§

source§

impl LoggerHandle

source

pub fn set_new_spec(&self, new_spec: LogSpecification)

Replaces the active LogSpecification.

source

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.

source

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

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

source

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.

source

pub fn pop_temp_spec(&mut self)

Reverts to the previous LogSpecification, if any.

source

pub fn flush(&self)

Flush all writers.

source

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.

source

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.

source

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.

source

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§

source§

impl Clone for LoggerHandle

source§

fn clone(&self) -> LoggerHandle

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.