
# Log files

`logging.file.name` (a file) or `logging.file.path` (a directory, with `spring.log` in it) turns on a `FileAppender`. A server keeps its logs this way; an app may keep a file to attach to bug reports.

## Why

The console is gone when the process ends. A file keeps the history for later, and rolling it over by size keeps the disk from filling up.

## Example

```yaml
# lib/resources/application.yml
logging:
  file:
    name: logs/shop.log
    rolling-policy:
      max-file-size: 10MB
      max-history: 7
      total-size-cap: 100MB
      clean-history-on-start: false
  threshold:
    file: info
  charset:
    file: UTF-8
```

```properties
# lib/resources/application.properties: the same
logging.file.name=logs/shop.log
logging.file.rolling-policy.max-file-size=10MB
logging.file.rolling-policy.max-history=7
logging.file.rolling-policy.total-size-cap=100MB
logging.file.rolling-policy.clean-history-on-start=false
logging.threshold.file=info
logging.charset.file=UTF-8
```

```text
logs/
  shop.log       the current file
  shop.log.1     the previous one
  shop.log.2
  ...            at most 7 rolled files, at most 100 MB together
```

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `logging.file.name` | path | none | The log file. A relative path is resolved against `LoggingSystem.fileDirectory`, else the working directory. `${LOG_FILE}` in patterns |
| `logging.file.path` | directory | none | Writes `<dir>/spring.log` when no name is set. `${LOG_PATH}` in patterns |
| `logging.pattern.file` | pattern | Spring Boot's file pattern | The line format; an empty pattern means no file |
| `logging.threshold.file` | level | `trace` | The lowest level the file keeps |
| `logging.charset.file` | charset | UTF-8 | UTF-8, ISO-8859-1 or US-ASCII, by IANA or Java names (`utf8`); characters it cannot encode are written as `?` |
| `logging.file.rolling-policy.max-file-size` | `DataSize` | `10MB` | The size at which the file rolls over |
| `logging.file.rolling-policy.max-history` | `int` | `7` | How many rolled files are kept; `0` keeps all, as in Logback |
| `logging.file.rolling-policy.total-size-cap` | `DataSize` | `0B`: no limit | The largest total size of the rolled files; the oldest are deleted beyond it |
| `logging.file.rolling-policy.clean-history-on-start` | `bool` | `false` | Deletes the rolled files when the application starts |

The default file pattern is Spring Boot's, without colours:

```text
%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd'T'HH:mm:ss.SSSXXX}} ${LOG_LEVEL_PATTERN:-%5p} ${PID:-} --- %esb(){APPLICATION_NAME}%esb{APPLICATION_GROUP}[%t] ${LOG_CORRELATION_PATTERN:-}%-40.40logger{39} : %m%X%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}
```

## How the file is written

- Lines logged in one synchronous burst are written together, in one write at the end of the microtask. Lines still waiting are written when the context closes.
- When the file would grow past `max-file-size`, it is renamed to `shop.log.1` and a new one is started; older files shift to `.2`, `.3`, and so on. Only `max-history` of them are kept, and the oldest are deleted while together they exceed `total-size-cap`.
- Rolling is by size only, into numbered files. Archives are not compressed.

## When writing fails

A file that cannot be written stops nothing else, as in Logback:

- A file that cannot be opened at the start (a read-only directory) is reported on the console, and the application starts without it.
- When writing fails later (a full disk), the error is reported once, the lines are dropped, and writing is tried again after a pause: 20 ms, growing to about 5 minutes with each failed try. Once a line is written again, one line says how many were lost. `FileAppender.isFailing` tells meanwhile.
- A roll-over that fails is reported once, and the lines go on into the current file until a roll-over works, tried again a minute later.

## In a Flutter app

A Flutter app's writable directory is only known at run time, so set it before starting the application:

```dart
// The app's documents directory, from path_provider.
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  LoggingSystem.instance.fileDirectory =
      (await getApplicationDocumentsDirectory()).path;
  await runApplicationAsync(const []);
}
```

On the web there is no file system: `logging.file.*` is ignored with a warning, and `FileAppender.isSupported` is `false`.

## Old and unsupported keys

| Key | What happens |
|---|---|
| `logging.logback.rollingpolicy.*` (Spring Boot's) | Stops the start and names `logging.file.rolling-policy.*` |
| `logging.file.max-size`, `logging.file.max-history`, `logging.file.total-size-cap`, `logging.file.clean-history-on-start` (before Spring Boot 2.4) | Ignored with a warning naming the current key |
| `logging.file.rolling-policy.file-name-pattern` | Ignored with a warning: no dates, `%i` or `.gz` |

## In Spring (Java)

The same `logging.file.name` and `logging.file.path`. Logback's rolling policy names are `logging.logback.rollingpolicy.*` there. Logback rolls by date and size into a file name pattern, and `max-history` counts days; here rolling is by size into numbered files, and `max-history` counts files.

## See also

- [Patterns](patterns.md)
- [All properties](properties.md)
- [Differences from Spring](differences.md)
