Timberjack

Timberjack supports several rotation triggers. Depending on your configuration, rotation can be triggered by file size, time intervals, specific clock times, or manual calls.

Rotation Triggers

1. Size-Based: Triggered when a write operation would cause the file to exceed MaxSize. The backup filename includes -size.
2. Time-Based (Interval): Triggered on the next write after RotationInterval has elapsed since the last rotation. The backup filename includes -time.
3. Scheduled (Clock-Aligned): Triggered by a background goroutine at specific minutes (RotateAtMinutes) or specific times (RotateAt). These use -time as the reason.
4. Manual:
   • Logger.Rotate(): Forces immediate rotation.
   • Logger.RotateWithReason(reason): Forces rotation and tags the file with a sanitized custom reason.

Filename Patterns

By default, rotated files follow the pattern: <name>-<timestamp>-<reason>.log.

If you set AppendTimeAfterExt: true, the pattern changes to: <name>.log-<timestamp>-<reason> (useful for shell TAB completion).

Example of custom reason: If you call logger.RotateWithReason("reload-now v2"), the file might be named foo-2025-05-01T10-30-00.000-reload-now-v2.log.

// Manual rotation with a custom reason
_ = logger.RotateWithReason("reload-now v2")

The Logger struct is used to define how logs are written and rotated.

Warning: Timberjack assumes one process writes to a given file. Reusing the same configuration from multiple processes on the same machine may lead to unexpected behavior.

type Logger struct {
    Filename          string        // File to write logs to
    MaxSize           int           // Max size (MB) before rotation (default: 100)
    MaxAge            int           // Max age (days) to retain old logs
    MaxBackups        int           // Max number of backups to keep
    LocalTime         bool          // Use local time in rotated filenames

    // Compression controls post-rotation compression:
    //   "none" | "gzip" | "zstd"
    // Unknown/empty default to "none", unless the legacy Compress is true (see below).
    Compression       string

    // Deprecated: prefer Compression.
    // If Compression is empty and Compress is true = gzip compression.
    // Back-compat shim for old configs; will be removed in v2.
    Compress          bool


    RotationInterval  time.Duration // Rotate after this duration (if > 0)
    RotateAtMinutes   []int         // Specific minutes within an hour (0–59) to trigger rotation
    RotateAt          []string      // Specific daily times (HH:MM, 24-hour) to trigger rotation
    BackupTimeFormat  string        // Optional. If unset or invalid, defaults to 2006-01-02T15-04-05.000 (with fallback warning)
    AppendTimeAfterExt    bool      // if true, name backups like foo.log-<timestamp>-<reason> defaults to foo-<timestamp>-<reason>.log
    FileMode          os.FileMode   // Use custom permissions for newly created files. If zero (unset or 0), defaults to 640.
}

Timberjack uses a background goroutine (the mill process) to handle post-rotation tasks. When a log file rotates, the mill process is signaled to perform compression and remove stale log files based on your retention settings. This ensures that the heavy lifting of compression and file deletion doesn't block your application's main logging path.

Key behaviors:

• Compression: Files are compressed using gzip or zstd (depending on your configuration) and written to a .tmp file first to ensure atomic publishing.
• Cleanup: The logger identifies old log files by parsing the timestamp embedded in their filenames. It supports both uncompressed and compressed (.gz, .zst) backup files.
• Filename Pattern: Backup files follow a specific pattern: prefix-timestamp-reason.ext or prefix.ext-timestamp-reason.ext. The reason is a sanitized string used to describe why the rotation occurred (e.g., size or time).

Common Issues and Warnings

• Logger Must Be Closed: Always call logger.Close() when finished. This shuts down background goroutines for scheduled rotation and cleanup. Failing to do so causes memory leaks and orphaned processes.
• Invalid BackupTimeFormat: This must follow standard Go time layout rules (e.g., 2006-01-02). If invalid, Timberjack logs a warning to os.Stderr and falls back to 2006-01-02T15-04-05.000.
• Invalid Schedule Values: If RotateAtMinutes contains values outside 0-59 or RotateAt contains invalid HH:MM strings, they are ignored with a warning to os.Stderr.
• Size-Based Rotation is Always Active: Even if you only configure time-based rotation, MaxSize is always enforced. A single write larger than MaxSize will return an error.
• Interaction between Interval and Scheduled Rotation: If both RotationInterval and RotateAt/RotateAtMinutes are set, the scheduled rotation will reset the lastRotationTime, which may delay or prevent the RotationInterval from triggering as expected.