Struct spdlog::sink::RotatingFileSink
source · pub struct RotatingFileSink { /* private fields */ }
Expand description
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§
source§impl RotatingFileSink
impl RotatingFileSink
sourcepub fn builder() -> RotatingFileSinkBuilder<(), ()>
pub fn builder() -> RotatingFileSinkBuilder<(), ()>
Constructs a builder of RotatingFileSink
.
sourcepub fn new<P>(
base_path: P,
rotation_policy: RotationPolicy,
max_files: usize,
rotate_on_open: bool
) -> Result<Self>
👎Deprecated since 0.3.0: it may be removed in the future, use RotatingFileSink::builder()
instead
pub fn new<P>( base_path: P, rotation_policy: RotationPolicy, max_files: usize, rotate_on_open: bool ) -> Result<Self>
RotatingFileSink::builder()
insteadConstructs 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.