Merge apache-brooklyn/master as at commit c0b4ab4

guide/dev/env/maven-build.md

@@ -30,7 +30,7 @@ By default, only tarball and zip packages for `brooklyn-dist` will be built. You
 Alternatively, you can build everything by using the `release` profile:
 
 {% highlight bash %}
-mvn clean install -Dno-go-client -Dno-rpm`
+mvn clean install -Prelease
 {% endhighlight %}
 
 Other tips:
@@ -44,7 +44,7 @@ Other tips:
 * Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
   ([tests described here](../code/tests.html))
 
-* You may need to install ``rpm`` package to build RPM packages: ``brew install rpm`` for Mac OS, ``apt-get install rpm`` for Ubuntu, ``yum install rpm`` for Centos/RHEL.
+* If building the `rpm` package, you can install rpm tools with: `brew install rpm` for Mac OS, `apt-get install rpm` for Ubuntu, `yum install rpm` for Centos/RHEL.
   On Mac OS you may also need to set `%_tmppath /tmp` in `~/.rpmmacros`.
 
 * If building the `deb` package, you can install deb tools with: `brew install dpkg` for Mac OS, `apt-get install deb` for Ubuntu, `yum install deb` for Centos/RHEL.

guide/dev/tips/logging.md

@@ -44,11 +44,56 @@ log:get/set                                 - Show / set the currently configure
 log:tail                                    - As display but will show continuously
 
 log:exception-display                       - Display the last exception
-
+ 
 #### Bundles
 
 You can capture logs from a specific bundle or set of bundles and e.g. write that to a different file.
 
+    log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
+    log4j.appender.sift.key=myBundle
+    log4j.appender.sift.default=karaf
+    log4j.appender.sift.appender=org.apache.log4j.FileAppender
+    log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
+    log4j.appender.sift.appender.layout.ConversionPattern=%d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %m%n
+    log4j.appender.sift.appender.file=${karaf.data}/log/mybundle.debug.log
+    log4j.appender.sift.appender.append=true
+
+For a detailed reference to the sift appender see [Karaf Advanced configuration](https://karaf.apache.org/manual/latest/#_advanced_configuration)
+
+### Classic - non-OSGI based Apache Brooklyn
+
+To use:
+
+* **Users**:
+If using a brooklyn binary installation, simply edit the ``logback.xml``
+or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
+directory.
+
+* **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:  
+
 {% highlight xml %}
 <included>
     <!-- filename to log to -->           
@@ -103,7 +148,6 @@ With this mechanism, you can include ``logback-custom.xml`` and/or other files u
 ``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
 

guide/ops/logging.md

@@ -16,6 +16,12 @@ some other problem has occurred which the user is expected to attend to
 
 Loggers follow the ``package.ClassName`` naming standard.  
 
+The default logging is to write INFO+ messages to `brooklyn.info.log`, 
+and DEBUG+ to `brooklyn.debug.log`. Each is a rolling log file, 
+where the past 10 files will be kept. INFO level, and above, messages
+will be logged to the karaf console. Use the `log:` commands in the 
+karaf client, e.g. `log:tail`, to read these messages.
+
 
 ## Using Logback through OSGi Pax Logging
 
@@ -24,7 +30,6 @@ In the OSGi based Apache Brooklyn logging is configured from ops4j pax logging.
 See: [Logging - OSGi based Apache Brooklyn](../dev/tips/logging.html#osgi-based-apache-brooklyn) <br/>
 [https://ops4j1.jira.com/wiki/display/paxlogging/Configuration](https://ops4j1.jira.com/wiki/display/paxlogging/Configuration)
 
-
 ## Standard Configuration
 
 A `org.ops4j.pax.logging.cfg` file is included in the `etc/` directly of the Brooklyn distro;
@@ -45,6 +50,8 @@ and create a file `logback-debug.xml` based on the
 [brooklyn/logback-debug.xml]({{ site.brooklyn.url.git }}/logging/logback-includes/src/main/resources/brooklyn/logback-debug.xml)
 from that project.
 
+A full explanation of logging in karaf is available [here](https://karaf.apache.org/manual/latest/#_log).
+
 
 ## Log File Backup
 
@@ -78,3 +85,5 @@ The following resources may be useful when configuring logging:
 * The [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project
 * [Brooklyn Developer Guide]({{ site.path.guide }}/dev/tips/logging.html) logging tips
 * The [Logback Project](http://logback.qos.ch/) home page
+* [Brooklyn Developer Guide]({{book.path.docs}}/dev/tips/logging.md) logging tips
+* [OPS4J Pax Logging](https://ops4j1.jira.com/wiki/display/paxlogging/Configuration)