Bootique - v2 Logback Module Documentation

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:

Maven

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

Gradle

{
  implementation: 'io.bootique.logback:bootique-logback'
}

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

2. Configuration Reference

2.1. log

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

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

Table 1. "log" Element Property Reference
Property	Default	Description
`appenders`	console appender	A list of appenders to output logs to. See below.
`appenderRefs`	none	A list of references to appenders. If it’s added to child logger only, then the child logger will write logs with this named appender. If the appender added to the root logger, or to both root and child loggers, or none, the appender will be attached to root logger only.
`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 are ignored 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.

2.2. log.appenders

log:
  appenders:
    - type: file
      name: test
      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. "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`
`filters`	none	A collection of filters to use with this appender

Table 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.
`name`	none	The name of the appender. If it has a name it could be added to the loggers by that name. If it has no name it will be automatically added to the root logger.
`file`	none	A name of a file to send the log to.
`append`	true	If true, events are appended at the end of an existing file. Otherwise, if append is false, any existing file is truncated. The append option is set to true by default.
`rollingPolicy`	none	An object that defines a log rotation policy. Examples are given below.
`filters`	none	A collection of filters to use with this appender. See filters section.

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.

2.3. log.appenders.rollingPolicy

2.3.1. "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 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.

2.3.2. "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 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-dd` is 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.

2.3.3. "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 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-dd` is 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.

2.4. log.appenders.filters

2.4.1. "level" Filter

log:
  level: debug
  appenders:
    - type: file
      logFormat: '%c{20}: %m%n'
      file: target/logs/info-only.log
      filters:
        - type: level
          level: info
          onMatch: accept
          onMismatch: deny

level filter filters events based on exact level matching.

Property Default Description

Property	Default	Description
`level`	none	logging event level to filter
`onMatch`	neutral	action to take on event level match (`accept`, `deny`, `neutral`)
`onMismatch`	neutral	action to take on event level mismatch (`accept`, `deny`, `neutral`)

level

none

logging event level to filter

onMatch

neutral

action to take on event level match (accept, deny, neutral)

onMismatch

neutral

action to take on event level mismatch (accept, deny, neutral)

2.4.2. "threshold" Filter

log:
  level: debug
  appenders:
    - type: console
      logFormat: '%c{20}: %m%n'
      filters:
        - type: threshold
          level: warn

threshold filter filters events below the specified level threshold. Events with a level below the threshold will be denied.

Property Default Description

Property	Default	Description
`level`	none	logging event level to filter

level

none

logging event level to filter

2.5. 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 7. Logger Property Reference
Property	Default	Description
`level`	`info`	Log level for a particular logger. Can be `off`, `error`, `warn`, `info`, `debug`, `trace`, `all`

3. Logback In Unit Tests

Configuring Logback via Bootique works well for applications, as configuration loading happens in the main method before any of the loggers are started. Unit tests is a different environment though. When testing you’d create, start and stop multiple BQRuntimes, each with its own Logback configuration. To provide consistent logging in this situation, it would be wise to disable per-app configuration all together. This can be done by setting useLogbackConfig property to true for each test BQRuntime (thus disabling Bootique configuration). E.g.:

@BQApp
static final BQRuntime app = Bootique.app()
        .autoLoadModules()
        .module(b -> BQCoreModule.extend(b)
                // "useLogbackConfig=true" turns off Bootique config
                .setProperty("bq.log.useLogbackConfig", "true"))
        .createRuntime();

If you need to tweak test logs further, you can use the standard Logback approach - create logback-test.xml file placing it on the test classpath (e.g. under src/test/resources). Here is an example logback-test.xml:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%d{"dd/MMM/yyyy:HH:mm:ss"}] %t %p %c{1}: %m%n%ex</pattern>
        </encoder>
    </appender>
    <root level="info">
        <appender-ref ref="STDOUT"/>
    </root>
    <logger name="io.bootique.metrics.health.sink.Slf4JReportSink" level="warn"/>
</configuration>

4. Logback Sentry Module

Provides Sentry integration with Bootique-Logback.

4.1. Setup

Get DSN (Data Source Name) from sentry.io or from your own instance of Sentry.

4.2. Add bootique-logback-sentry to your build tool: