Struct spdlog::sink::RotatingFileSink

pub struct RotatingFileSink { /* private fields */ }

A sink with a collection of files as the target, rotating according to the rotation policy.

A service program that runs for a long time in an environment with limited hard disk space may continue to write messages to the log file and eventually run out of hard disk space. RotatingFileSink is designed for such a usage scenario. It splits log messages into one or more log files and may be configured to delete old log files automatically to save disk space. The operation that splits log messages into multiple log files and optionally creates and deletes log files is called a rotation. The rotation policy determines when and how log files are created or deleted, and how log messages are written to different log files.

Parameters

A rotating file sink can be created with 3 parameters: the base path, the maximum number of log files, and the rotation policy.

The Base Path

Each rotating file sink requires a base path which serves as a template to form log file paths. You can set the base path with RotatingFileSinkBuilder::base_path when building a rotating file sink. Different rotation policy may use different file name patterns based on the base path. For more information about the base path, see the documentation of RotatingFileSinkBuilder::base_path.

Maximum Number of Log Files

This parameter defines the maximum number of log files allowed on the disk. You can set this parameter with RotatingFileSinkBuilder::max_files when building a rotating file sink. During a rotation, the sink won’t delete old log files unless the number of log files on the disk exceeds this limit. Furthermore, setting this parameter to 0 indicates that no limits are applied and effectively prevents the sink from deleting any old log files.

Rotation Policy

RotationPolicy defines the different available rotation policies. You can set the rotation policy with RotatingFileSinkBuilder::rotation_policy when building a rotating file sink. For more information about different rotation policies, please refer to the documentation of RotationPolicy.

Examples

See ./examples directory.

Implementations

impl RotatingFileSink

pub fn builder() -> RotatingFileSinkBuilder<(), ()>

Constructs a builder of RotatingFileSink.

pub fn new<P>(
    base_path: P,
    rotation_policy: RotationPolicy,
    max_files: usize,
    rotate_on_open: bool
) -> Result<Self>where
    P: Into<PathBuf>,

👎Deprecated since 0.3.0: it may be removed in the future, use RotatingFileSink::builder() instead

Constructs a RotatingFileSink.

The parameter max_files specifies the maximum number of files. If the number of existing files reaches this parameter, the oldest file will be deleted on the next rotation. Pass 0 for no limit.

The parameter rotate_on_open specifies whether to rotate files once when constructing RotatingFileSink. For the RotationPolicy::Daily and RotationPolicy::Hourly rotation policies, it may truncate the contents of the existing file if the parameter is true, since the file name is a time point and not an index.

Errors

If an error occurs opening the file, Error::CreateDirectory or Error::OpenFile will be returned.

Panics

Panics if the parameter rotation_policy is invalid. See the documentation of RotationPolicy for requirements.

Trait Implementations

impl Drop for RotatingFileSink

fn drop(&mut self)

Executes the destructor for this type.

impl Sink for RotatingFileSink

fn log(&self, record: &Record<'_>) -> Result<()>

Logs a record.

fn flush(&self) -> Result<()>

Flushes any buffered records.

fn level_filter(&self) -> LevelFilter

Gets the log level filter.

fn set_level_filter(&self, level_filter: LevelFilter)

Sets the log level filter.

fn set_formatter(&self, formatter: Box<dyn Formatter>)

Sets the formatter.

fn set_error_handler(&self, handler: Option<ErrorHandler>)

Sets a error handler.

fn should_log(&self, level: Level) -> bool

Determines if a log message with the specified level would be logged.