Rotation API

The Rotation module provides enterprise-grade log rotation capabilities, including time-based and size-based rotation, retention policies, compression, and flexible naming strategies.

Quick Reference: Method Aliases

Full Method	Alias(es)	Description
init()	create()	Initialize rotation
deinit()	destroy()	Deinitialize rotation

Rotation Struct

The core struct managing rotation logic.

const Rotation = @import("logly").Rotation;

Initialization

pub fn init(
    allocator: std.mem.Allocator,
    path: []const u8,
    interval_str: ?[]const u8, // "daily", "hourly", etc.
    size_limit: ?u64,          // Bytes
    retention: ?usize          // Max files to keep
) !Rotation

Configuration Methods

withCompression

Enables automatic compression of rotated files.

pub fn withCompression(self: *Rotation, config: CompressionConfig) !void

Example:

try rot.withCompression(.{ .algorithm = .deflate });

withNaming

Sets the naming strategy for rotated files.

pub fn withNaming(self: *Rotation, strategy: NamingStrategy) void

Example:

rot.withNaming(.iso_datetime);

withNamingFormat

Sets a custom format string for rotated files. Automatically sets strategy to .custom.

pub fn withNamingFormat(self: *Rotation, format: []const u8) !void

Example:

try rot.withNamingFormat("{base}-{date}{ext}");

withMaxAge

Sets a maximum age (in seconds) for retaining log files.

pub fn withMaxAge(self: *Rotation, seconds: i64) void

Example:

rot.withMaxAge(86400 * 7); // 7 days

withArchiveDir

Sets a specific directory to move rotated files into.

pub fn withArchiveDir(self: *Rotation, dir: []const u8) !void

Example:

try rot.withArchiveDir("logs/archive");

withKeepOriginal

Set whether to keep original files after compression.

pub fn withKeepOriginal(self: *Rotation, keep: bool) void

Example:

rot.withKeepOriginal(true); // Keep both original and compressed files

withCompressOnRetention

Enable compression during retention cleanup instead of deletion.

pub fn withCompressOnRetention(self: *Rotation, enable: bool) void

Example:

rot.withCompressOnRetention(true); // Compress old files instead of deleting

withDeleteAfterRetentionCompress

Set whether to delete original files after retention compression.

pub fn withDeleteAfterRetentionCompress(self: *Rotation, delete: bool) void

Example:

rot.withDeleteAfterRetentionCompress(false); // Keep originals after compression

applyConfig

Applies global configuration settings to the rotation instance.

pub fn applyConfig(self: *Rotation, config: RotationConfig) !void

Example:

try rot.applyConfig(global_config.rotation);

Configuration Structs

RotationConfig

Global configuration struct for rotation defaults.

pub const RotationConfig = struct {
    enabled: bool = false,
    interval: ?[]const u8 = null,
    size_limit: ?u64 = null,
    size_limit_str: ?[]const u8 = null,
    retention_count: ?usize = null,
    max_age_seconds: ?i64 = null,
    naming_strategy: NamingStrategy = .timestamp,
    naming_format: ?[]const u8 = null,
    archive_dir: ?[]const u8 = null,
    clean_empty_dirs: bool = false,
    async_cleanup: bool = false,
    keep_original: bool = false,                    // Keep original after compression
    compress_on_retention: bool = false,            // Compress instead of delete during retention
    delete_after_retention_compress: bool = true,   // Delete originals after retention compression
    archive_root_dir: ?[]const u8 = null,           // Root directory for all archives
    create_date_subdirs: bool = false,              // Create YYYY/MM/DD subdirectories
    file_prefix: ?[]const u8 = null,                // Custom prefix for rotated files
    file_suffix: ?[]const u8 = null,                // Custom suffix for rotated files
    compression_algorithm: CompressionAlgorithm = .gzip,
    compression_level: CompressionLevel = .default,
};

RotationConfig Field Reference

Field	Type	Default	Description
enabled	bool	false	Enable rotation
interval	?[]const u8	null	Time-based interval (e.g., "daily")
size_limit	?u64	null	Size-based rotation threshold (bytes)
retention_count	?usize	null	Max files to retain
max_age_seconds	?i64	null	Max age for rotated files
naming_strategy	NamingStrategy	.timestamp	File naming strategy
archive_dir	?[]const u8	null	Directory for rotated files
archive_root_dir	?[]const u8	null	Centralized archive root
create_date_subdirs	bool	false	Create YYYY/MM/DD subdirs
file_prefix	?[]const u8	null	Prefix for rotated file names
file_suffix	?[]const u8	null	Suffix for rotated file names
compression_algorithm	CompressionAlgorithm	.gzip	Algorithm for compression
compression_level	CompressionLevel	.default	Compression level
keep_original	bool	false	Keep original after compression
compress_on_retention	bool	false	Compress instead of delete
delete_after_retention_compress	bool	true	Delete after retention compression
clean_empty_dirs	bool	false	Remove empty directories

Enums

RotationInterval

Defines the time interval for rotation.

Value	Description
.minutely	Rotate every minute.
.hourly	Rotate every hour.
.daily	Rotate every day (24 hours).
.weekly	Rotate every week.
.monthly	Rotate every 30 days.
.yearly	Rotate every 365 days.

NamingStrategy

Defines how rotated files are named.

Value	Example (app.log)	Notes
.timestamp	app.log.167882233	Default for size/hourly rotation.
.date	app.log.2023-01-01	Default for daily/weekly/monthly.
.iso_datetime	app.log.2023-01-01T12-00-00	High precision.
.index	app.log.1, app.log.2	Rolling log style.
.custom	app-2023-01-01.log	Uses naming_format.

Custom Format Placeholders

When using .custom (or setting naming_format), you can use:

Placeholder	Description
{base}	Filename without extension
{ext}	Extension (including dot)
{date}	YYYY-MM-DD
{time}	HH-mm-ss
{timestamp}	Unix timestamp
{iso}	ISO 8601 Datetime

Flexible Date/Time Placeholders: You can also use {YYYY}, {YY}, {MM}, {M}, {DD}, {D}, {HH}, {H}, {mm}, {m}, {ss}, {s} and any separators. Example: app-{YYYY}/{M}/{D}.log -> app-2023/10/5.log

Statistics

The RotationStats struct provides insights into the rotation process.

Field	Type	Description
total_rotations	AtomicUnsigned	Total number of rotations performed.
files_archived	AtomicUnsigned	Number of files successfully compressed.
files_deleted	AtomicUnsigned	Number of files deleted due to retention policy.
last_rotation_time_ms	AtomicUnsigned	Duration of the last rotation operation.
rotation_errors	AtomicUnsigned	Count of rotation failures.
compression_errors	AtomicUnsigned	Count of compression failures.

Presets

The RotationPresets struct offers common configurations.

// Daily rotation, keep 7 days
const rot = try RotationPresets.daily7Days(allocator, path);

// Size based (10MB), keep 5 files
const rot = try RotationPresets.size10MB(allocator, path);

Example Usage

var rotation = try Rotation.init(allocator, "app.log", "daily", null, 30);

// Enable compression
try rotation.withCompression(.{ .algorithm = .deflate });

// Logic ensures checks are fast
try rotation.checkAndRotate(&file);