Skip to content

4 Configuration

Anton Pryamostanov edited this page Aug 15, 2020 · 33 revisions

Table of contents generated with markdown-toc

Configuration

Bobbin is configured using only one file: Bobbin.yml

❗ Bobbin configuration is conceptually different from other Logging Frameworks. Please do not try to interpret Bobbin configuration within the traditional context. Let's start with a fresh thinking.

While the documentation is quite lengthy, Bobbin configuration is very intuitive - and is simple in practice.

We recommend that you jump straight to examples - it will help to visualize the concepts and quickly grab the overall idea.

Below information is used primarily as a reference data.

Bobbin.yml

Bobbin.yml should be located in application working directory.

Bobbin.yml is de-serialized using Jackson Databind into BobbinConfig class, which represents the Root Logger.

Root Logger contains a list of Destinations which identify to where the logs are actually saved.

Each Destination is deserialized into AbstractDestinationConfig - or more precisely into its subtypes identified using name field.

Both BobbinConfig and AbstractDestinationConfig extend AbstractBobbinConfig class, which means they both support same configuration parameters.

In practice this helps to redefine Root Logger configuration on each specific Destination.

Common Settings
Parameter Root logger Destinations Script support Description YAML data type Sample value (Bobbin.yml) Default value (BobbinConfig class)
destinations List of destinations.
Each destination can override Root Logger parameters.
List
name Full class name of Destination configuration holder
(e.g.io.infinite.bobbin.config.ConsoleDestinationConfig,
io.infinite.bobbin.config.FileDestinationConfig).
Identifies actual destination class implementation.
String io.infinite.bobbin.config.ConsoleDestinationConfig null
levels Allowed levels (trace, debug, warning, error, info).
Destinations can narrow down root levels (but can't exceed it).
null means all, empty array means none.
List [warn, error, info] null (means "all")
packages Allowed packages - by prefix (io., com.google., org.spring.abcd.foo.).
Destinations can narrow down root packages (but can't exceed it).
null means all, empty array means none.
List [conf.plugins.output, [conf.plugins.input] null (means "all")
classes Allowed classes - by full name.
Destinations can narrow down root classes (but can't exceed it).
null means all, empty array means none.
List [io.infinite.bobbin.Test02, io.infinite.bobbin.Test03] null (means "all")
filter Boolean expression.
Optional filter - true means the message is filtered-out (excluded) from log.
String "className.contains('io.infinite')" "false"
dateFormat FastDateFormat syntax to format date placeholder in logs. String "yyyyMMdd" "yyyy-MM-dd"
dateTimeFormat FastDateFormat syntax to format dateTime placeholder in logs. String "yyyy-MM-dd'T'HH:mm:ss:SSSZ" "yyyy-MM-dd HH:mm:ss:SSS"
delimiter Field separator. String "," pipe character
lineBreak Line separator. String "\r\n" as per System.lineSeparator()
format %format% placeholder inheritable in format<...> parameters below. String "dateTime + delimiter + level + delimiter + className + delimiter + message" "dateTime + delimiter + level + delimiter + threadName + delimiter + className + delimiter + message"
formatMessage String expression - format of Slf4j log(message).
Can inherit from format parameter as %format% placeholder.
String "%format%"
formatThrowable String expression - format of Slf4j log(message, throwable).
Can inherit from format parameter as %format% placeholder.
String "%format% + delimiter + throwable" "%format% + delimiter + exceptionUtils.stacktrace(throwable)"
formatArg String expression - format of Slf4j log(message, arg).
Can inherit from format parameter as %format% placeholder.
String "%format% + delimiter + arg.toString()"
formatArgs String expression - format of Slf4j log(message, args...).
Can inherit from format parameter as %format% placeholder.
String "%format% + delimiter + args.toString()"
formatArg1Arg2 String expression - format of Slf4j log(message, arg1, arg2).
Can inherit from format parameter as %format% placeholder.
String "%format% + delimiter + arg1.toString() + delimiter + arg2.toString()"
fileName File name mask in a form of a String expression.
Recalculated for each log message (each line).
Supported only for FileDestinationConfig.
String ("./LOGS/THREADS/${threadGroupName}/${threadName}_${date}.log") null

As can be seen, most of the settings have default values. This means you don't need to specify them in Bobbin.yml unless you need to redefine their values.

Root Logger redefines the default values, and its Destination redefine either Root Logger settings (if present) or default values directly.

Let's take an example when we want just to change the line-break to be always CRLF. The default value is System.lineSeparator() which is platform-dependent.

To redefine it we need to specify new value in Bobbin.yml:

lineBreak: "\r\n"

If you have only above line in Bobbin.yml, other parameters will keep their default values.

Example config with comments

dateFormat: yyyyMMdd <--- Root Logger setting redefines default value
destinations: <--- Root Logger Destinations
  - name: io.infinite.bobbin.config.ConsoleDestinationConfig
    levels: [warn, error, info]
  - name: io.infinite.bobbin.config.FileDestinationConfig
    packages: [io.infinite]
    dateFormat: yyyyMMdd <--- Root Logger setting is redefined on this specific Destination
    fileName: ("./LOGS/INFINITE/${className}/${level}/${className}_${level}_${date}.log")
  - name: io.infinite.bobbin.config.FileDestinationConfig
    fileName: ("./LOGS/PACKAGES/${className}/${level}/${className}_${level}_${date}.log")
    format: dateTime + '|' + level + '|' + threadName + '|' + className + '|' + message

Destinations

Destination configuration represents serialized instance of a class extending io.infinite.bobbin.config.AbstractDestinationConfig.

At the moment Bobbin supports 2 Destinations out of the box:

Custom Destinations can be added by Bobbin users by extending io.infinite.bobbin.config.AbstractDestinationConfig class.

Destination configuration class is specified using name field, i.e.:

destinations:
  - name: my.own.DestinationImplementationConfig
...

Refer to Common Settings above to see configuration supported by Destinations.

ConsoleDestinationConfig

This destination sends output to console - STD OUT. (STD ERR is not used at the moment).

It does not have any additional configuration.

FileDestinationConfig

This destination sends output to files.

It has additional setting: fileName.

fileName is a file name mask in a form of a Groovy expression, recalculated for each log message (each line).

It allows to efficiently split the log files using minimal configuration using the following Binding:

  • level
  • className
  • date
  • dateTime
  • thread
  • threadGroup
  • MDC variables

Scripting

Bobbin provides extensive scripting capabilities sufficient to effectively handle most of the scenarios.

Scripts are written in a form of Java or Groovy expressions and are compiled into a class during application start.

There is no run-time interpreting done, which improves the performance.

Each script is executed with its specific binding providing relevant data.

Default binding

In addition to static runtime context, Bobbin provides default binding that is accessible in all scripts:

  • MDC
  • String threadName
  • String threadGroupName
  • String dateTime
filter binding
  • String level,
  • String className
  • MDC MDC
  • String threadName
  • String threadGroupName
  • String dateTime
format binding
  • String level
  • String className
  • String date
  • String message
formatMessage binding
  • String level
  • String className
  • String date
  • String message
formatArg binding
  • String level
  • String className
  • String date
  • String message
  • Object arg
formatArgs binding
  • String level
  • String className
  • String date
  • String message
  • Object[] args
formatArg1Arg2 binding
  • String level
  • String className
  • String date
  • String message
  • Object arg1
  • Object arg2
formatThrowable binding
  • String level
  • String className
  • String date
  • String message
  • Throwable throwable

Zero conf

When there is no Bobbin.yml defined, Bobbin will automatically use its default configuration suitable for many scenarios:

  • info, warn, error are sent to Console (only Exception message is saved; call stack is not printed)
  • error level is additionally written to ./error.log (including Exception call stack)

Next: Bobbin.yml examples

Clone this wiki locally