File Rotation

File Rotation & Retention

This page explains how logme keeps file logs manageable in long-running applications.

There are two related but separate mechanisms:

• FileBackend rotation and part cleanup
• home directory size monitoring through DirectorySizeWatchdog

They solve different problems and can be used together.

---

FileBackend rotation

FileBackend writes log records to disk using an internal queue and a file-manager thread.
It supports file naming, append mode, size control, daily rotation, and cleanup of old parts.

A typical file backend entry looks like this:

{
  "type": "FileBackend",
  "file": "logs/app.log",
  "append": true,
  "rotation": "daily",
  "max-parts": 14
}

The file value is processed through logme path/template handling.
If the resulting path is relative, it is resolved relative to the logger home directory.

See File Backend and Configuration JSON.

---

Size control

max-size limits the physical size of the log file:

{
  "type": "FileBackend",
  "file": "logs/app.log",
  "max-size": "100MB"
}

This is a file backend setting. It is not the same thing as limiting the total size of a log directory.

max-size accepts either a plain byte count or the common byte-size suffixes documented in Utility Helpers, for example 512Kb, 64Mb, or 1Gb.

---

Daily rotation

Daily rotation creates a new part when the day changes:

{
  "type": "FileBackend",
  "file": "logs/app.log",
  "rotation": "daily"
}

When daily rotation is enabled, the backend forces append mode internally.
This avoids overwriting existing log content when a new process starts during the same day.

---

Part retention with max-parts

max-parts limits how many matching rotated parts are kept:

{
  "type": "FileBackend",
  "file": "logs/app.log",
  "rotation": "daily",
  "max-parts": 7
}

Cleanup is applied after a part change or rotation.
The backend matches files produced from the same file-name template and removes older parts beyond the configured limit.

Use this when you want to keep a fixed number of rotated log files.

---

Directory size watchdog

DirectorySizeWatchdog works at the logger home directory level.

It is configured through the home-directory section:

{
  "home-directory": {
    "path": "logs",
    "watch-dog": {
      "enable": true,
      "max-size": "10GB",
      "check-periodicity": "30s",
      "file-extension": [".log"]
    }
  }
}

The watchdog monitors total directory size and removes old files when the configured limit is exceeded.

This is different from max-parts:

• max-parts keeps only a fixed number of parts for one file backend pattern
• the watchdog controls total disk usage in the logging directory

The watchdog consults the file manager before deleting files, so active files used by registered file backends are not removed.

---

Choosing the right mechanism

Use daily rotation when log files should naturally split by date.

Use max-parts when each backend should retain only a fixed number of generated files.

Use the directory watchdog when total disk usage matters more than the number of files.

In production, it is common to combine them:

{
  "home-directory": {
    "path": "logs",
    "watch-dog": {
      "enable": true,
      "max-size": "20GB",
      "check-periodicity": "1m",
      "file-extension": [".log"]
    }
  },
  "channels": [
    {
      "name": "app",
      "backends": [
        {
          "type": "FileBackend",
          "file": "app.log",
          "rotation": "daily",
          "max-parts": 14
        }
      ]
    }
  ]
}

This keeps per-backend history under control and also protects the whole log directory from growing without limit.

---

Related pages

• File Backend
• Configuration JSON
• Threading Model