brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [02/50] brooklyn-docs git commit: make clearer and simpler how logging should be set up, in a way friendly to downstream projects
Date Mon, 01 Feb 2016 17:44:02 GMT
make clearer and simpler how logging should be set up, in a way friendly to downstream projects


Branch: refs/heads/0.6.0
Commit: fe2ebf743ff97ceea720891aa1387848ccb102ea
Parents: d27d8e7
Author: Alex Heneveld <>
Authored: Thu Sep 19 13:15:02 2013 +0100
Committer: Alex Heneveld <>
Committed: Thu Sep 19 13:15:54 2013 +0100

 docs/dev/tips/ | 101 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 91 insertions(+), 10 deletions(-)
diff --git a/docs/dev/tips/ b/docs/dev/tips/
index 7ee42e0..595f919 100644
--- a/docs/dev/tips/
+++ b/docs/dev/tips/
@@ -8,22 +8,102 @@ toc: /toc.json
 For logging, we use **logback** which implements the slf4j API.
 This means you can use any slf4j compliant logging framework,
-or if you just want something that works logback will work out of the box.
+with a default configuration which just works out of the box
+and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...)
+if you prefer one of those.
-The CLI launcher includes a ``logback.xml`` which logs at DEBUG level 
-to a file ``./brooklyn.log`` and INFO to the console,
-with a few exceptions.  Exceptions --- and the inverse, favourites which
-you might want to enable even if the root logger level is bumped to INFO ---
-are in files in ``core/src/main/resources/brooklyn/`` which can easily
-be included in your own ``logback.xml`` (one of the nicest features of logback).
+To use:
-Tests have debug logging across the board, included by default from 
+* **Users**:
+If using a brooklyn binary installation, simply edit the ``logback.xml``
+or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
+* **Developers**:
+When setting up a new project, if you want logging it is recommended to include 
+the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency, 
+and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``,

+as described below.
+## Customizing Your Logging
+The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration,
+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,
+to include ``logback-main.xml``, and that file in turn includes:
+* ``logback-custom.xml``
+* ``brooklyn/logback-appender-file.xml``
+* ``brooklyn/logback-appender-stdout.xml``
+* ``brooklyn/logback-logger-excludes.xml``
+* ``brooklyn/logback-debug.xml``
+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="" 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 ``<included/>``.
+* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
+  create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT.
+* To discard all brooklyn's default logging, create a ``logback-main.xml`` which 
+  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.xml``
+  which comes with ``brooklyn-logback-xml``.)
+You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
+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 ``brooklyn-logback-xml``.
+(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.)
 You can set a specific logback config file to use with:
+## Assemblies
+When building an assembly, it is recommended to create a ``conf/logback.xml`` which 
+simply includes ``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 ``logback-custom.xml`` under ``conf/``.
+Including ``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
+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.   
+## Tests
+Brooklyn projects ``test`` scope includes the ``brooklyn--utils-test-support`` project
+which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml``
+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
+The only differences of the ``logback-test.xml`` configuration is that:
+* Debug logging is included for all Brooklyn packages
+* The log file is called ``brooklyn-tests.log`` 
 ## Caveats
 * logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x. 
@@ -34,6 +114,7 @@ You can set a specific logback config file to use with:
   (In eclipse, right-click the project, the Build Path -> Configure,
   then make sure all dirs are included (All) and excluded (None) -- 
   ``mvn clean install`` should do this for you.)
-  You may find that your IDE logs to a file ``brooklyn-tests.log`` 
+* You may find that your IDE logs to a file ``brooklyn-tests.log`` 
   if it doesn't distinguish between test build classpaths and normal classpaths.

View raw message