Logging: A Quick Overview
For logging, we use logback which implements the slf4j API.
This means you can use any slf4j compliant logging framework,
with a default configuration which just works out of the box
and bindings to the other common libraries (
if you prefer one of those.
Users: If using a brooklyn binary installation, simply edit the
logback-custom.xmlsupplied in the archive, sometimes in a
Developers: When setting up a new project, if you want logging it is recommended to include the
brooklyn-logback-xmlproject as an optional and provided maven dependency, and then to put custom logging configuration in either
logback-main.xml, as described below.
Customizing Your Logging
brooklyn-logback-xml supplies a
with a mechanism which allows it to be easily customized, consumed, and overridden.
You may wish to include this as an optional dependency so that it is not forced
upon downstream projects. This
logback.xml file supplied contains just one instruction,
logback-main.xml, and that file in turn includes:
For the most common customizations, simply create a
logback-custom.xml on your classpath
(ensuring it is loaded before brooklyn classes in classpath ordering in the pom)
and supply your customizations there:
<included> <!-- filename to log to --> <property name="logging.basename" scope="context" value="acme-app" /> <!-- additional loggers --> <logger name="com.acme.app" level="DEBUG"/> </included>
For other configuration, you can override individual files listed above. For example:
- To remove debug logging, create a trivial
brooklyn/logback-debug.xml, containing simply
- To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
brooklyn/logback-appender-stdout.xmlwhich defines an appender STDOUT.
- To discard all brooklyn’s default logging, create a
logback-main.xmlwhich contains your configuration. This should look like a standard logback configuration file, except it should be wrapped in
<included>XML tags rather than
<configuration>XML tags (because it is included from the
logback.xmlwhich comes with
- To redirect all jclouds logging to a separate file include
brooklyn/logback-logger-debug-jclouds.xml. This redirects all logging from
jcloudsto one of two files: anything logged from Brooklyn’s persistence thread will end up in a
persistence.log, everything else will end up in
You should not supply your own
logback.xml if you are using
If you do, logback will detect multiple files with that name and will scream at you.
If you wish to supply your own
logback.xml, do not include
(Alternatively you can include a
logback.groovy which causes logback to ignore
You can set a specific logback config file to use with:
When building an assembly, it is recommended to create a
logback-main.xml (which comes from the classpath). Users of the assembly
can then edit the
logback.xml file in the usual way, or they can plug in to the configuration
mechanisms described above, by creating files such as
brooklyn-logback-xml as an optional and provided dependency means everything
should work correctly in IDE’s but it will not include the extra
logback.xml file in the assembly.
(Alternatively if you include the
conf/ dir in your IDE build, you should exclude this dependency.)
With this mechanism, you can include
logback-custom.xml and/or other files underneath
src/main/resources/ of a project, as described above (for instance to include custom
logging categories and define the log file name) and it should get picked up,
both in the IDE and in the assembly.
test scope includes the
which supplies a
logback-test.xml. logback uses this file in preference to
when available (ie when running tests). However the
logback-test.xml Brooklyn uses
includes the same
logback-main.xml call path above, so your configurations should still work.
The only differences of the
logback-test.xml configuration is that:
- Debug logging is included for all Brooklyn packages
- The log file is called
logback uses SLF4J version 1.6 which is not compatible with 1.5.x. If you have dependent projects using 1.5.x (such as older Grails) things may break.
If you’re not getting the logging you expect in the IDE, make sure
src/main/resourcesis included in the classpath. (In eclipse, right-click the project, the Build Path -> Configure, then make sure all dirs are included (All) and excluded (None) –
mvn clean installshould do this for you.)
You may find that your IDE logs to a file
brooklyn-tests.logif it doesn’t distinguish between test build classpaths and normal classpaths.
Logging configuration using file overrides such as this is very sensitive to classpath order. To get a separate
brooklyn-tests.logfile during testing, for example, the
brooklyn-test-supportproject with scope
testmust be declared as a dependency before
brooklyn-logback-includes, due to the way both files declare
Similarly note that the
logback-custom.xmlfile is included after logging categories and levels are declared, but before appenders are declared, so that logging levels declared in that file dominate, and that properties from that file apply to appenders.
Finally remember this is open to improvement. It’s the best system we’ve found so far but we welcome advice. In particular if it could be possible to include files from the classpath with wildcards in alphabetical order, we’d be able to remove some of the quirks listed above (though at a cost of some complexity!).