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

When writing fails

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

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.

See also