---
title: Log Rotation
description: Manage log file sizes and retention
---

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

## Basic Configuration

```ts
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

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

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

### Time-based Rotation

```ts
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

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

Or keep a specific number of files:

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

### Compression

```ts
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

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

### Development

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

### High-Volume

```ts
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