Struct LogFileInitializer

pub struct LogFileInitializer<'a, P>
where
    P: AsRef<Path>,
{
    pub directory: P,
    pub filename: &'a str,
    pub max_n_old_files: usize,
    pub preferred_max_file_size_mib: u64,
}

The initializer of the log file. See Self::init.

Fields

directory: P

The directory where the log files will be placed in.

The directory and its parent directories will be recursively created if they don’t already exist while calling init (equivalent to mkdir -p).

The directory should be used exclusively for the log files. Other files in the directory will slow down the process of counting existing old files and finding the oldest one to delete if max_n_old_files is exceeded.

filename: &'a str

The file name of the uncompressed log file that will be opened and returned (directory/filename).

max_n_old_files: usize

The maximum number of old (compressed) log files.

The value 0 leads to directly returning the file in append mode. The value of preferred_max_file_size_mib will be ignored in that case.

You shouldn’t manually set max_n_old_files to 0. If you don’t want rolling, just create the directory and the file manually and open the file in append mode instead of having this library as a dependency. The value 0 is just supported as a fallback in case the user of your program wants to deactivate rolling.

preferred_max_file_size_mib: u64

The preferred maximum size of the uncompressed log file directory/filename in MiB.

It is called the preferred maximum file size because this file size can be exceeded before the next initialization. If the file size exceeds the preferred maximum, rolling will only happen if it was not already done on the same day (in UTC).

Implementations

impl<'a, P> LogFileInitializer<'a, P>

where P: AsRef<Path>,

pub fn init(self) -> Result<File>

Return a file at directory/filename for appending new logs.

Rolling will be applied to the file directory/file if all the following conditions are true:

• The file already exists.
• The file has a size >= preferred_max_file_size_mib (in MiB).
• No rolling was already done today.

In the case of rolling, the file will be compressed with GZIP to directory/filename-YYYYMMDD.gz with today’s date (in UTC).

If rolling was applied and the number of old files exceeds max_n_old_files, the oldest file will be deleted.

Example

let log_file = LogFileInitializer {
  directory: "logs",
  filename: "test",
  max_n_old_files: 2,
  preferred_max_file_size_mib: 1,
}.init()?;

Compatibility

Only UTF8 paths are supported.