Log Rotation

Manage log file sizes and retention

Automatically manage log file sizes, compression, and retention policies.

Basic Configuration

logixlysia({
  config: {
    logFilePath: './logs/app.log',
    logRotation: {
      maxSize: '10m',    // Rotate when file reaches 10MB
      maxFiles: '7d',    // Keep logs for 7 days
      compress: true     // Compress rotated logs
    }
  }
})

Rotation Options

Size-based Rotation

logRotation: {
  maxSize: '10m'    // 10 megabytes
}

Supported formats: '1k', '1m', '1g' or bytes (number)

Time-based Rotation

logRotation: {
  interval: '1d'    // Rotate when the live file is a day old
}

Supported formats: a number plus a unit — '1h' (hours), '1d' (days), '1w' (weeks). Minutes and bare numbers are not accepted.

[!NOTE] Interval rotation is evaluated when a log line is written, not on a wall-clock timer. If the process writes nothing for longer than interval, the file rotates on the next write — an idle process’s file can exceed interval in age until traffic resumes. The file’s age is read from filesystem creation time, so it survives restarts.

Retention Policy

logRotation: {
  maxFiles: '7d'    // Keep logs for 7 days
}

Or keep a specific number of files:

logRotation: {
  maxFiles: 10      // Keep last 10 files
}

Compression

logRotation: {
  compress: true    // Enable compression (gzip)
}

How Rotation Works

Rotation happens on write, when either configured trigger is crossed: the in-memory byte count exceeds maxSize, or the live file’s age (from filesystem creation time) has reached interval. Both are checked after every write batch — never on a timer. Empty files are not rotated.

When a log file is rotated, it’s renamed with a timestamp and a high-resolution counter to guarantee uniqueness:

app.log → app.log.2026-07-27-14-30-05-123-45678901234567

The suffix is <YYYY-MM-DD-HH-MM-SS-SSS>-<hrtime>. If compression is enabled, a .gz extension is appended after rotation:

app.log.2026-07-27-14-30-05-123-45678901234567 → app.log.2026-07-27-14-30-05-123-45678901234567.gz

Retention

maxFiles controls how many rotated files are kept:

• A number (e.g. 10) keeps that many most-recent rotated files, deleting older ones.
• A string (e.g. '7d') keeps rotated files younger than that age, deleting older ones.

Example Configurations

Production

logRotation: {
  maxSize: '100m',
  maxFiles: '30d',
  compress: true,
  interval: '1d'
}

Development

logRotation: {
  maxSize: '10m',
  maxFiles: '7d',
  compress: false
}

High-Volume

logRotation: {
  maxSize: '1g',
  maxFiles: '7d',
  compress: true,
  interval: '1h'
}

Important Notes

• Empty files are not rotated
• Rotation failures don’t crash the application
• Compression runs asynchronously
• Old files are automatically cleaned up based on maxFiles
• Interval rotation is checked on write only; an idle process rotates on its next write