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 <[email protected]> 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)
