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
# 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
# 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
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:
%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 toshop.log.1and a new one is started; older files shift to.2,.3, and so on. Onlymax-historyof them are kept, and the oldest are deleted while together they exceedtotal-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.isFailingtells 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:
// 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.