Bootique Logback Documentation


Table of Contents

Chapter 1. Bootique Integration with Logback

As mentioned in Bootique general documentation on logging, standard modules rely on SLF4J loggers that can be easily bridged to various advanced logging frameworks. Same maximally neutral logging approach is reasonable to apply in the user modules as well.

bootique-logback is a "drag-and-drop" module integrating Bootique logging with Logback logging framework. Just like any other module, bootique-logback can be enabled by simply adding it to the pom.xml dependencies, assuming autoLoadModules() is in effect:

<dependency>
	<groupId>io.bootique.logback</groupId>
	<artifactId>bootique-logback</artifactId>
</dependency>

Without further configuration it would log everything to console using INFO level. Configuration can be provided via YAML, as shown in the following section. Configuration options include per class and package log levels configuration, a choice of appenders, etc.

Chapter 2. Configuration Reference

log

log:
  level: warn
  loggers:
    com.foo:
      level: debug
    com.example:
      level: debug
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: target/logback/testRun_Debug.log

"log" is a root element of the Logback configuration and is bound to a LogbackContextFactory object. It supports the following properties:

Table 2.1. "log" Element Property Reference
Property Default Description
appenders console appender A list of appenders to output logs to. See below.
level INFO A default logging level. Can be overridden per logger.
loggers none A map of logger factories by logger name. Logger name is a package name (applied recursively) or class name. See below.
useLogbackConfig false If true, all other logback settings areignored and the user is expected to provide its own config file per Logback documentation. This is only needed for a few advanced options not directly available via Bootique config.

log.appenders

log:
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: /var/log/myapp.log
    - type: console
      logFormat: '%c{20}: %m%n'

Lists appenders to sends the logs to. If the list is empty, console appender is used with default settings. Currently available appenders are "console" and "file":

Table 2.2. "console" Appender Property Reference
Property Default Description
logFormat %-5p [%d{ISO8601,UTC}] %thread %c{20}: %m%n%rEx A format of the log lines. See Logback PatternLayout for details.
target stdout Whether to log to standard output or standard error. Possible values are stdout and stderr
Table 2.3. "file" Appender Property Reference
Property Default Description
logFormat %-5p [%d{ISO8601,UTC}] %thread %c{20}: %m%n%rEx A format of the log lines. See Logback PatternLayout for details.
file none A name of a file to send the log to.
rollingPolicy none An object that defines a log rotation policy. Examples are given below.

There are a few ways log file rotation can be configured for the "file" appender, as defined by the rollingPolicy. Out of the box the following Logback policies are supported: fixedWindow, time, sizeAndTime.

"fixedWindow" Rolling Policy

log:
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: /var/log/myapp.log
      rollingPolicy:
        type: fixedWindow
        fileNamePattern: '/var/log/myapp-%i.log'
        historySize: 5
        fileSize: 20

"fixedWindow" policy rotates the main log file when it reaches a certain size, keeping one or more rotated files.

Table 2.4. "fixedWindow" rolling policy Property Reference
Property Default Description
fileNamePattern none A pattern of rotated file name. Must contain %i somewhere in the pattern (replaced by a number during rotation).
historySize none (unlimited) A max number of rotated files to keep.
fileSize none Max file size that causes rotation. Expressed in bytes, kilobytes, megabytes or gigabytes by suffixing a numeric value with KB, MB and respectively GB. For example: 5000000, 5000KB, 5MB and 2GB.

"time" Rolling Policy

log:
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: /var/log/myapp.log
      rollingPolicy:
        type: time
        fileNamePattern: '/var/log/myapp-%d{yyyyMMDDHHmmss}.log'

"time" policy rotates the main log file at a fixed time interval determined by the file name pattern.

Table 2.5. "time" rolling policy Property Reference
Property Default Description
fileNamePattern none A pattern of rotated file name. Its value should consist of the name of the file, plus a suitably placed %d conversion specifier. The %d conversion specifier may contain a date-and-time pattern as specified by the java.text.SimpleDateFormat class. If the date-and-time pattern is omitted, then the default pattern yyyy-MM-ddis assumed. The rollover interval is inferred from the value of the pattern.
historySize none (unlimited) A max number of rotated files to keep.
totalSize none Max size of all log files combined. Expressed in bytes, kilobytes, megabytes or gigabytes by suffixing a numeric value with KB, MB and respectively GB. For example: 5000000, 5000KB, 5MB and 2GB.

"sizeAndTime" Rolling Policy

log:
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: /var/log/myapp.log
      rollingPolicy:
        type: sizeAndTime
        fileNamePattern: '/var/log/myapp-%d{yyyyMMDDHHmmss}.%i.log'
        historySize: 5
        fileSize: 50
        totalSize: 150

"sizeAndTime" policy rotates the main log file either at a fixed time interval determined by the file name pattern or when the log file reaches a certain size.

Table 2.6. "sizeAndTime" rolling policy Property Reference
Property Default Description
fileNamePattern none A pattern of rotated file name. Its value should consist of the name of the file, plus a suitably placed %d conversion specifier. The %d conversion specifier may contain a date-and-time pattern as specified by the java.text.SimpleDateFormat class. If the date-and-time pattern is omitted, then the default pattern yyyy-MM-ddis assumed. The rollover interval is inferred from the value of the pattern.
historySize none (unlimited) A max number of rotated files to keep.
totalSize none Max size of all log files combined. Expressed in bytes, kilobytes, megabytes or gigabytes by suffixing a numeric value with KB, MB and respectively GB. For example: 5000000, 5000KB, 5MB and 2GB.
fileSize none Max file size that causes rotation. Expressed in bytes, kilobytes, megabytes or gigabytes by suffixing a numeric value with KB, MB and respectively GB. For example: 5000000, 5000KB, 5MB and 2GB.

log.loggers

log:
  loggers:
    com.foo:
      level: debug
    com.example:
      level: debug

This is a map of logger factories by logger name. Logger name is either a package name (applied recursively to subpackages and their classes) or a class name. Each LoggerFactory has the following properties:

Table 2.7. Logger Property Reference
Property Default Description
level INFO Log level for a particular logger. Can be OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL