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)
}

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