Struct flexi_logger::writers::FileLogWriterBuilder

pub struct FileLogWriterBuilder { /* fields omitted */ }

Builder for FileLogWriter.

Implementations

impl FileLogWriterBuilder

Simple methods for influencing the behavior of the FileLogWriter.

#[must_use]pub fn print_message(self) -> Self

Makes the FileLogWriter print an info message to stdout when a new file is used for log-output.

pub fn format(self, format: FormatFunction) -> Self

Makes the FileLogWriter use the provided format function for the log entries, rather than the default (formats::default_format).

pub fn directory<P: Into<PathBuf>>(self, directory: P) -> Self

Specifies a folder for the log files.

If the specified folder does not exist, the initialization will fail. By default, the log files are created in the folder where the program was started.

pub fn suffix<S: Into<String>>(self, suffix: S) -> Self

Specifies a suffix for the log files. The default is “log”.

#[must_use]pub fn suppress_timestamp(self) -> Self

Makes the logger not include a timestamp into the names of the log files

#[must_use]pub fn cleanup_in_background_thread(self, use_background_thread: bool) -> Self

When rotation is used with some Cleanup variant, then this option defines if the cleanup activities (finding files, deleting files, evtl compressing files) is done in the current thread (in the current log-call), or whether cleanup is delegated to a background thread.

As of flexi_logger version 0.14.7, the cleanup activities are done by default in a background thread. This minimizes the blocking impact to your application caused by IO operations.

In earlier versions of flexi_logger, or if you call this method with use_background_thread = false, the cleanup is done in the thread that is currently causing a file rotation.

#[must_use]pub fn rotate(
    self,
    criterion: Criterion,
    naming: Naming,
    cleanup: Cleanup
) -> Self

Use rotation to prevent indefinite growth of log files.

By default, the log file is fixed while your program is running and will grow indefinitely. With this option being used, when the log file reaches the specified criterion, the file will be closed and a new file will be opened.

Note that also the filename pattern changes:

• by default, no timestamp is added to the filename
• the logs are always written to a file with infix _rCURRENT
• when the rotation criterion is fulfilled, it is closed and renamed to a file with another infix (see Naming), and then the logging continues again to the (fresh) file with infix _rCURRENT.

Example:

After some logging with your program my_prog and rotation with Naming::Numbers, you will find files like

my_prog_r00000.log
my_prog_r00001.log
my_prog_r00002.log
my_prog_rCURRENT.log

The cleanup parameter allows defining the strategy for dealing with older files. See Cleanup for details.

#[must_use]pub fn append(self) -> Self

Makes the logger append to the given file, if it exists; by default, the file would be truncated.

pub fn discriminant<S: Into<String>>(self, discriminant: S) -> Self

The specified String is added to the log file name.

pub fn basename<S: Into<String>>(self, basename: S) -> Self

The specified String is used as the basename of the log file name, instead of the program name.

pub fn create_symlink<P: Into<PathBuf>>(self, symlink: P) -> Self

The specified String will be used on linux systems to create in the current folder a symbolic link to the current log file.

#[must_use]pub fn use_windows_line_ending(self) -> Self

Use Windows line endings, rather than just \n.

#[must_use]pub fn use_buffering(self, buffer: bool) -> Self

Define if buffering should be used.

By default, every log line is directly written to the output file, without buffering. This allows seeing new log lines in real time.

Using buffering reduces the program’s I/O overhead, and thus increases overall performance, which can be important if logging is used heavily. On the other hand, if logging is used with low frequency, the log lines can become visible in the output file with significant deferral. See Logger::buffer_and_flush for how to limit the maximum buffering time.

Note that with buffering you should use LogWriter::shutdown at the very end of your program to ensure that all buffered log lines are flushed before the program terminates.

#[must_use]pub fn buffer_with_capacity(self, capacity: usize) -> Self

Activates buffering, and uses a buffer with the specified capacity.

See Logger::use_buffering

pub fn try_build(self) -> Result<FileLogWriter, FlexiLoggerError>

Produces the FileLogWriter.

Errors

FlexiLoggerError::Io.

impl FileLogWriterBuilder

Alternative set of methods to control the behavior of the FileLogWriterBuilder. Use these methods when you want to control the settings flexibly, e.g. with commandline arguments via docopts or clap.

#[must_use]pub fn o_print_message(self, print_message: bool) -> Self

With true, makes the FileLogWriterBuilder print an info message to stdout, each time when a new file is used for log-output.

pub fn o_directory<P: Into<PathBuf>>(self, directory: Option<P>) -> Self

Specifies a folder for the log files.

If the specified folder does not exist, the initialization will fail. With None, the log files are created in the folder where the program was started.

#[must_use]pub fn o_timestamp(self, use_timestamp: bool) -> Self

With true, makes the FileLogWriterBuilder include a timestamp into the names of the log files.

#[must_use]pub fn o_rotate(
    self,
    rotate_config: Option<(Criterion, Naming, Cleanup)>
) -> Self

By default, and with None, the log file will grow indefinitely. If a rotate_config is set, when the log file reaches or exceeds the specified size, the file will be closed and a new file will be opened. Also the filename pattern changes: instead of the timestamp, a serial number is included into the filename.

The size is given in bytes, e.g. o_rotate_over_size(Some(1_000)) will rotate files once they reach a size of 1 kB.

The cleanup strategy allows delimiting the used space on disk.

#[must_use]pub fn o_append(self, append: bool) -> Self

If append is set to true, makes the logger append to the given file, if it exists. By default, or with false, the file would be truncated.

pub fn o_discriminant<S: Into<String>>(self, discriminant: Option<S>) -> Self

The specified String is added to the log file name.

pub fn o_basename<S: Into<String>>(self, basename: Option<S>) -> Self

The specified String is used as the basename of the log file, instead of the program name, which is used when None is given.

pub fn o_create_symlink<S: Into<PathBuf>>(self, symlink: Option<S>) -> Self

If a String is specified, it will be used on linux systems to create in the current folder a symbolic link with this name to the current log file.