Struct LogRollerBuilder

pub struct LogRollerBuilder { /* private fields */ }

Provides a fluent interface for configuring LogRoller instances.

The builder pattern allows for flexible configuration of log rolling behavior, with sensible defaults that can be overridden as needed. Configuration options include:

• Time zone - Control when rotations occur
• Rotation strategy - Choose between size-based or time-based rotation
• Compression - Optionally compress rotated files to save space
• File retention - Limit the number of historical log files to keep
• File naming - Add custom suffixes to help identify different log types
• Permissions - Set specific file permissions (Unix systems only)

Default Configuration

If not explicitly configured, LogRoller uses these defaults:

• Daily rotation at midnight
• Local system time zone
• No compression
• Keep all historical files
• Standard file permissions

Examples

Basic configuration for daily log rotation:

use logroller::{LogRollerBuilder, Rotation, RotationAge};

let appender = LogRollerBuilder::new("./logs", "app.log")
    .rotation(Rotation::AgeBased(RotationAge::Daily))
    .build()
    .unwrap();

Advanced configuration with multiple options:

use logroller::{Compression, LogRollerBuilder, Rotation, RotationAge, TimeZone};

let appender = LogRollerBuilder::new("./logs", "app.log")
    .rotation(Rotation::AgeBased(RotationAge::Hourly))
    .time_zone(TimeZone::UTC)  // Use UTC for consistent timing
    .max_keep_files(24)        // Keep one day's worth of hourly logs
    .compression(Compression::Gzip)  // Compress old logs
    // .compression(Compression::XZ(6))  // Compress using XZ. Requires `xz` feature.
    .suffix("error".to_string())  // Name format: app.log.2025-04-01-19.error
    .build()
    .unwrap();

Size-based rotation for large log files:

use logroller::{LogRollerBuilder, Rotation, RotationSize};

let appender = LogRollerBuilder::new("./logs", "large_app.log")
    .rotation(Rotation::SizeBased(RotationSize::MB(100)))  // Rotate at 100MB
    .max_keep_files(5)  // Keep only the 5 most recent files
    .build()
    .unwrap();

Implementations

impl LogRollerBuilder

pub fn new<P: AsRef<Path>>(directory: P, filename: P) -> Self

Create a new log roller builder.

Arguments

• directory - The directory where the log files are stored.
• filename - The name of the log file.

pub fn time_zone(self, time_zone: TimeZone) -> Self

Set the time zone for the log files.

pub fn rotation(self, rotation: Rotation) -> Self

Set the rotation type for the log files.

pub fn compression(self, compression: Compression) -> Self

Set the compression type for the log files.

pub fn max_keep_files(self, max_keep_files: u64) -> Self

Set the maximum number of log files to keep.

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

Set the suffix for the log file.

pub fn file_mode(self, mode: u32) -> Self

Set the file permissions for log files (Unix-like systems only). This sets the file mode bits in octal notation like when using chmod. For example, 0o644 for rw-r–r– permissions.

pub fn graceful_shutdown(self, graceful_shutdown: bool) -> Self

Determines whether the application should attempt a graceful shutdown. When set to true, the application will perform cleanup operations and allow in-progress tasks (like file compression and old file cleanup) to complete before shutting down. If set to false, the application may terminate immediately without waiting for these ongoing tasks.

Compression Corruption Risk: If graceful_shutdown is false and the application exits while a compression thread is still writing a compressed file, the resulting file may be incomplete or corrupted. Setting this to true ensures that all compression operations finish, but may cause a slight delay during application shutdown.

By default, this is set to false.

pub fn build(self) -> Result<LogRoller, LogRollerError>

Build the log roller.