-
Notifications
You must be signed in to change notification settings - Fork 2
4 Configuration
Table of contents generated with markdown-toc
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
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
.
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.
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
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
.
This destination sends output to console - STD OUT. (STD ERR is not used at the moment).
It does not have any additional configuration.
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
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.
In addition to static runtime context, Bobbin
provides default binding
that is accessible in all scripts:
MDC
String threadName
String threadGroupName
String dateTime
-
String level
, String className
MDC MDC
String threadName
String threadGroupName
String dateTime
String level
String className
String date
String message
String level
String className
String date
String message
String level
String className
String date
String message
Object arg
String level
String className
String date
String message
Object[] args
String level
String className
String date
String message
Object arg1
Object arg2
String level
String className
String date
String message
Throwable throwable
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)