You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by du...@apache.org on 2021/05/20 16:09:55 UTC
[brooklyn-docs] 23/34: Merge apache-brooklyn/master as at commit
c0b4ab45
This is an automated email from the ASF dual-hosted git repository.
duncangrant pushed a commit to branch ruby-3
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit c08d9b8ec5b534bdd61f2c02374cc5c81ff428e7
Merge: a7dbdc2 c0b4ab4
Author: Richard Downer <ri...@cloudsoft.io>
AuthorDate: Thu Feb 25 11:15:19 2021 +0000
Merge apache-brooklyn/master as at commit c0b4ab45
guide/blueprints/catalog/bundle.md | 2 +-
guide/blueprints/test/test-entities.md | 5 +
guide/dev/env/maven-build.md | 211 ++++++++++++++++++---------------
guide/dev/tips/logging.md | 48 +++++---
guide/ops/logging.md | 27 +++--
5 files changed, 171 insertions(+), 122 deletions(-)
diff --cc guide/dev/env/maven-build.md
index bc5a79b,19c9c4a..fb538f3
--- a/guide/dev/env/maven-build.md
+++ b/guide/dev/env/maven-build.md
@@@ -15,15 -15,21 +17,21 @@@ The full build requires the following s
With these in place, you should be able to build everything with a:
-```bash
-mvn clean install
-```
+{% highlight bash %}
+% mvn clean install
+{% endhighlight %}
- Alternatively you can build most things with just Java and Maven installed using:
+ By default, only tarball and zip packages for `brooklyn-dist` will be built. You can enable each dist artifact with the following arguments:
+ - for CLI client: `-Dcli` (requires `Go`)
+ - for RPM package: `-Drpm` (requires `rpm tools`)
+ - for DEB package: `-Ddeb` (requires `deb tools`)
+ - for docker image: `-Ddocker` (requires `docker`)
+
+ Alternatively, you can build everything by using the `release` profile:
-```bash
+{% highlight bash %}
- mvn clean install -Dno-go-client -Dno-rpm`
+ mvn clean install -Prelease
-```
+{% endhighlight %}
Other tips:
@@@ -31,17 -37,19 +39,19 @@@
* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
- `export MAVEN_OPTS="-Xmx1024m -Xms512m"`
+ ``export MAVEN_OPTS="-Xmx1024m -Xms512m"``
-* Run `-PIntegration` to run integration tests, or `-PLive` to run live tests
- ([tests described here]({{book.path.docs}}/dev/code/tests.md))
+* 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.
+
* If you're looking at the maven internals, note that many of the settings are inherited from parent projects (see for instance `brooklyn-server/parent/pom.xml`)
-* For tips on building within various IDEs, look [here]({{book.path.docs}}/dev/env/ide/index.md).
+* For tips on building within various IDEs, look [here](ide/).
## When the RAT Bites
@@@ -73,15 -81,12 +83,12 @@@ If there is a good reason that a file,
## Other Handy Hints
- * On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories.
- Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3).
-
* The **mvnf** script
([get the gist here](https://gist.github.com/2241800))
- simplifies building selected projects, so if you just change something in `software-webapp`
+ simplifies building selected projects, so if you just change something in ``software-webapp``
and then want to re-run the examples you can do:
- `examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`
+ ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}``
## Appendix: Sample Output
@@@ -90,26 -95,8 +97,8 @@@ including a few warnings (which we hav
understand to be benign and hard to get rid of them,
although we'd love to if anyone can help!):
-```bash
+{% highlight bash %}
% mvn clean install
- [INFO] Scanning for projects...
- [INFO] ------------------------------------------------------------------------
- [INFO] Reactor Build Order:
- [INFO]
- [INFO] Brooklyn REST JavaScript Web GUI
- [INFO] Brooklyn Server Root
- [INFO] Brooklyn Parent Project
- [INFO] Brooklyn Test Support Utilities
- [INFO] Brooklyn Logback Includable Configuration
- [INFO] Brooklyn Common Utilities
-
- ...
-
- [WARNING] Ignoring project type war - supportedProjectTypes = [jar]
-
- ...
-
- [WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in ~/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar
...
@@@ -183,9 -199,7 +201,8 @@@
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
- [INFO] Total time: 8:33.983s
- [INFO] Finished at: Mon Jul 21 14:56:46 BST 2014
- [INFO] Final Memory: 66M/554M
+ [INFO] Total time: 08:21 min
+ [INFO] Finished at: 2019-04-08T15:52:28+01:00
[INFO] ------------------------------------------------------------------------
-```
+
+{% endhighlight %}
diff --cc guide/dev/tips/logging.md
index a6e9a71,3e96bed..9d66db2
--- a/guide/dev/tips/logging.md
+++ b/guide/dev/tips/logging.md
@@@ -30,109 -29,41 +30,130 @@@ then you can modify the config file `et
For more information check
[https://ops4j1.jira.com/wiki/display/paxlogging/Configuration](https://ops4j1.jira.com/wiki/display/paxlogging/Configuration).
+ #### Karaf Log commands
+
+ Logging commands are available through the karaf console. These let you interact with the logs and dynamically change
+ logging configuration in a running application.
+
+ Some useful log: commands are:
+
+ log:display mylogger -p "%d - %c - %m%n" - Show the log entries for a specific logger with a different pattern.
+
+ log:get/set - Show / set the currently configured log levels
+
+ 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 -->
+ <property name="logging.basename" scope="context" value="acme-app" />
+
+ <!-- additional loggers -->
+ <logger name="com.acme.app" level="DEBUG"/>
+</included>
+{% endhighlight %}
+
+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``.)
+* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``.
+ This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything
+ logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else
+ will end up in ``jclouds.log``.
+
+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:
+
+{% highlight bash %}
+-Dlogback.configurationFile=/path/to/config.xml
+{% endhighlight %}
+
+
+#### 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 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.
-
+
#### Tests
- Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project
+ For unit testing, where no karaf context exits, Brooklyn uses logback. Brooklyn project's ``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 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 ``brooklyn-tests.log``
-
+ when available (ie when running tests).
#### Caveats
diff --cc guide/ops/logging.md
index 41b6e4b,a768266..6e83b47
--- a/guide/ops/logging.md
+++ b/guide/ops/logging.md
@@@ -16,34 -15,23 +16,42 @@@ some other problem has occurred which t
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
+
+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 `logback.xml` file is included in the `conf/` directly of the Brooklyn distro;
- this is read by `brooklyn` at launch time. Changes to the logging configuration,
- such as new appenders or different log levels, can be made directly in this file
- or in a new file included from this.
+ A `org.ops4j.pax.logging.cfg` file is included in the `etc/` directly of the Brooklyn distro;
+ this is read by `brooklyn` at launch time. Changes to the logging configuration,
+ such as new appenders or different log levels, can be made directly in this file.
+ Karaf logging is highly configurable. For example enable the sift appender to log to separate log files for
+ each bundle as described here: [Advanced configuration](https://karaf.apache.org/manual/latest/#_advanced_configuration)
+## Advanced Configuration
+
+The default `logback.xml` file references a collection of other log configuration files
+included in the Brooklyn jars. It is necessary to understand the source structure
+in the [logback-includes]({{ site.brooklyn.url.git }}/logging/logback-includes) project.
+
+For example, to change the debug log inclusions, create a folder `brooklyn` under `conf`
+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
@@@ -75,6 -62,5 +82,8 @@@ which can then [feed its logs to Logsta
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)