From c066b32fb34a771085eb3dd69088649c79daecbe Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Fri, 30 Sep 2016 17:11:12 -0400 Subject: [PATCH] Work for new logging documentation Signed-off-by: WalkerWatch --- .../administration/logging/chapter.adoc | 12 +- .../logging/configuring-jetty-logging.adoc | 4 +- .../configuring-jetty-request-logs.adoc | 1 - .../logging/configuring-logging-modules.adoc | 425 ++++++++++++++++++ .../default-logging-with-stderrlog.adoc | 57 ++- .../logging/example-apache-log4j.adoc | 3 +- .../example-java-util-logging-native.adoc | 5 +- .../logging/example-java-util-logging.adoc | 3 +- .../logging/example-logback.adoc | 3 +- 9 files changed, 464 insertions(+), 49 deletions(-) create mode 100644 jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc index cfa8510f709..15d6528cd1c 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc @@ -22,10 +22,12 @@ This chapter discusses various options for configuring logging. include::configuring-jetty-logging.adoc[] include::default-logging-with-stderrlog.adoc[] include::configuring-jetty-request-logs.adoc[] -include::example-apache-log4j.adoc[] -include::example-java-util-logging.adoc[] -include::example-java-util-logging-native.adoc[] -include::example-logback.adoc[] -include::example-slf4j-multiple-loggers.adoc[] +include::configuring-logging-modules.adoc[] +// TODO - Remove following +// include::example-apache-log4j.adoc[] +// include::example-java-util-logging.adoc[] +// include::example-java-util-logging-native.adoc[] +// include::example-logback.adoc[] +// include::example-slf4j-multiple-loggers.adoc[] include::example-logback-centralized-logging.adoc[] include::dump-tool.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc index 4caddb3d035..7d405a20492 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc @@ -51,7 +51,7 @@ Configure the Jetty logging layer via the `org.eclipse.jetty.util.log.Log` class * If no logger implementation is specified, default to `org.eclipse.jetty.util.log.StdErrLog`. ____ [NOTE] -You can create your own custom logging by providing an implementation of the link:{JDURL}org/eclipse/jetty/util/log/Logger.html[Jetty Logger API]. +You can create your own custom logging by providing an implementation of the link:{JDURL}org/eclipse/jetty/util/log/Logger.html[Jetty Logger API]. For an example of a custom logger, see link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java[JavaUtilLog.java]. ____ @@ -60,7 +60,7 @@ ____ By default, the internal Jetty Logging discovery mechanism will load logging specific properties from a classpath resource called `jetty-logging.properties` and then initialize the Logging from a combination of properties found in that file, along with any System Properties. A typical jetty-logging.properties file will include at least the declaration of which logging implementation you want to use by defining a value for the `org.eclipse.jetty.util.log.class` property. - + Examples for various logging frameworks can be found later in this documentation. * Default Logging with link:#default-logging-with-stderrlog[Jetty's StdErrLog] diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc index 119d735292f..d2fc4721e8e 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc @@ -57,7 +57,6 @@ INFO: Base directory was modified ---- The above command will add a new `requestlog.ini` file to your link:#start-vs-startd[`{$jetty.base}/start.d` directory]. -If you used `--add-to-start` it will append the configuration options for the module to the `start.ini` file located in your `{$jetty.base}` directory. The equivalent code for embedded usages of Jetty is: diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc new file mode 100644 index 00000000000..39db1c792d1 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc @@ -0,0 +1,425 @@ +// ======================================================================== +// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd. +// ======================================================================== +// All rights reserved. This program and the accompanying materials +// are made available under the terms of the Eclipse Public License v1.0 +// and Apache License v2.0 which accompanies this distribution. +// +// The Eclipse Public License is available at +// http://www.eclipse.org/legal/epl-v10.html +// +// The Apache License v2.0 is available at +// http://www.opensource.org/licenses/apache2.0.php +// +// You may elect to redistribute this code under either of these licenses. +// ======================================================================== + +[[configuring-logging-modules]] +=== Jetty Logging Integrations (Slf4j, Log4j, Logback, JCL, JUL) + +Jetty provides support for several logging frameworks including SLF4J, Java Commons Logging (jcl), Java Util Logging (jul), Log4j (including version 2), and Logback. +This page includes examples of how to enable the associated modules for these different frameworks. +Enabling these frameworks in the Jetty distribution is as easy as activating any other module, by adding `--add-to-start=` to the start command for your server, such as: + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-jetty +INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini +INFO : resources transitive +INFO : Base directory was modified +.... + +As noted above, Jetty supports a wide array of logging technologies. +The release of Jetty 9.4 made the implementation of these frameworks easier by providing logging modules that contain all the dependencies needed to implement a specific technology. +If a particular logging framework requires additional jar files, Jetty will automatically download these as part of enabling the associated module. +You can view a list of all the Jetty modules by running `java -jar /start.jar --list-modules`. + +[[example-logging-slf4j]] +==== Logging with SLF4J + +===== jetty-slf4j + +Jetty uses the Slf4j api as a bridge to provide logging information to additional frameworks such as Log4j or Logback. +It can also be used itself to provide logging in conjunction with standard Jetty logging. +To enable the Slf4j framework, you need to activate the `logging-slf4j` module. + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-slf4j + +ALERT: There are enabled module(s) with licenses. +The following 1 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : logging-slf4j initialized in ${jetty.base}/start.d/logging-slf4j.ini +INFO : slf4j-impl transitive +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-simple/1.7.21/slf4j-simple-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-simple-1.7.21.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   └── slf4j +│   ├── slf4j-api-1.7.21.jar +│   └── slf4j-simple-1.7.21.jar +└── start.d + ├── logging-slf4j.ini +.... + + +[[example-logging-log4j]] +==== Logging with Log4j and log4j2 + +It is possible to have the Jetty Server logging configured so that Log4j or Log4j2 controls the output of logging events produced by Jetty. +This is accomplished by configuring Jetty for logging to http://logging.apache.org/log4j/[Apache Log4j] via http://slf4j.org/manual.html[Slf4j] and the http://slf4j.org/manual.html#swapping[Slf4j binding layer for Log4j]. +Implementation of Log4j can be done by enabling the `logging-log4j` module. + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-log4j + +ALERT: There are enabled module(s) with licenses. +The following 2 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: log4j-impl + + Log4j is released under the Apache 2.0 license. + + http://www.apache.org/licenses/LICENSE-2.0.html + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : log4j-impl transitive, ini template available with --add-to-start=log4j-impl +INFO : resources transitive +INFO : slf4j-log4j transitive +INFO : logging-log4j initialized in ${jetty.base}/start.d/logging-log4j.ini +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/log4j/log4j/1.2.17/log4j-1.2.17.jar to ${jetty.base}/lib/log4j/log4j-1.2.17.jar +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-log4j12/1.7.21/slf4j-log4j12-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-log4j12-1.7.21.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   ├── log4j +│   │   └── log4j-1.2.17.jar +│   └── slf4j +│   ├── slf4j-api-1.7.21.jar +│   └── slf4j-log4j12-1.7.21.jar +├── resources +│   └── log4j.properties +└── start.d + ├── logging-log4j.ini +.... + +Or, to enable Log4j2, simply enable the `logging-log4j2` module. + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-log4j2 + +ALERT: There are enabled module(s) with licenses. +The following 2 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: log4j2-api + + Log4j is released under the Apache 2.0 license. + + http://www.apache.org/licenses/LICENSE-2.0.html + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : logging-log4j2 initialized in ${jetty.base}/start.d/logging-log4j2.ini +INFO : log4j2-api transitive, ini template available with --add-to-start=log4j2-api +INFO : resources transitive +INFO : slf4j-log4j2 transitive +INFO : log4j2-impl transitive +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/org/apache/logging/log4j/log4j-api/2.6.1/log4j-api-2.6.1.jar to ${jetty.base}/lib/log4j/log4j-api-2.6.1.jar +MKDIR: ${jetty.base}/resources +DOWNLOAD: http://central.maven.org/maven2/org/apache/logging/log4j/log4j-slf4j-impl/2.6.1/log4j-slf4j-impl-2.6.1.jar to ${jetty.base}/lib/log4j/log4j-slf4j-impl-2.6.1.jar +DOWNLOAD: http://central.maven.org/maven2/org/apache/logging/log4j/log4j-core/2.6.1/log4j-core-2.6.1.jar to ${jetty.base}/lib/log4j/log4j-core-2.6.1.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   ├── log4j +│   │   ├── log4j-api-2.6.1.jar +│   │   ├── log4j-core-2.6.1.jar +│   │   └── log4j-slf4j-impl-2.6.1.jar +│   └── slf4j +│   └── slf4j-api-1.7.21.jar +├── resources +│   └── log4j2.xml +└── start.d + ├── logging-log4j2.ini +.... + +[[example-logging-logback]] +==== Logging with Logback + +It is possible to have the Jetty Server logging configured so that Logback controls the output of logging events produced by Jetty. +This is accomplished by configuring Jetty for logging to `Logback`, which uses http://slf4j.org/manual.html[Slf4j] and the http://logback.qos.ch/[Logback Implementation for Slf4j]. + +To set up Jetty logging via Logback, enable the `logging-logback` module. + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-logback + +ALERT: There are enabled module(s) with licenses. +The following 2 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: logback-impl + + Logback: the reliable, generic, fast and flexible logging framework. + + Copyright (C) 1999-2012, QOS.ch. All rights reserved. + + This program and the accompanying materials are dual-licensed under + + either: + + the terms of the Eclipse Public License v1.0 + + as published by the Eclipse Foundation: + + http://www.eclipse.org/legal/epl-v10.html + + or (per the licensee's choosing) under + + the terms of the GNU Lesser General Public License version 2.1 + + as published by the Free Software Foundation: + + http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : logback-impl transitive, ini template available with --add-to-start=logback-impl +INFO : slf4j-logback transitive +INFO : logging-logback initialized in ${jetty.base}/start.d/logging-logback.ini +INFO : resources transitive +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/ch/qos/logback/logback-core/1.1.7/logback-core-1.1.7.jar to ${jetty.base}/lib/logback/logback-core-1.1.7.jar +DOWNLOAD: http://central.maven.org/maven2/ch/qos/logback/logback-classic/1.1.7/logback-classic-1.1.7.jar to ${jetty.base}/lib/logback/logback-classic-1.1.7.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   ├── logback +│   │   ├── logback-classic-1.1.7.jar +│   │   └── logback-core-1.1.7.jar +│   └── slf4j +│   └── slf4j-api-1.7.21.jar +├── resources +│   └── logback.xml +└── start.d + ├── logging-logback.ini +.... + +At this point Jetty is configured so that the Jetty server itself will log using Logback, using the Logback configuration found in `{$jetty.base}/resources/logback.xml`. + +==== Logging with Java Util Logging + +[[example-logging-java-util-logging]] +===== Java Util Logging with SLF4J +It is possible to have the Jetty Server logging configured so that `java.util.logging` controls the output of logging events produced by Jetty. + +This example demonstrates how to configuring Jetty for logging to `java.util.logging` via http://slf4j.org/manual.html[Slf4j] and the http://slf4j.org/manual.html#swapping[Slf4j binding layer for java.util.logging]. +If you want to use the built-in native `java.util.logging` implementation, see link:#example-logging-java-util-logging-native[Native Java Util Logging]. + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-jul + +ALERT: There are enabled module(s) with licenses. +The following 1 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : slf4j-jul transitive +INFO : logging-jul initialized in ${jetty.base}/start.d/logging-jul.ini +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-jdk14/1.7.21/slf4j-jdk14-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-jdk14-1.7.21.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   └── slf4j +│   ├── slf4j-api-1.7.21.jar +│   └── slf4j-jdk14-1.7.21.jar +└── start.d + ├── logging-jul.ini +.... + +==== Logging with Java Commons Logging +Jetty provides support of the Java Commons Logging (jcl) through the `logging-jcl` module, using Slf4j as a bridge. +This can be enabled as shown below: + +[source, screen, subs="{sub-order}"] +.... +$ java -jar ../start.jar --add-to-start=logging-jcl + +ALERT: There are enabled module(s) with licenses. +The following 2 module(s): + + contains software not provided by the Eclipse Foundation! + + contains software not covered by the Eclipse Public License! + + has not been audited for compliance with its license + + Module: jcl-impl + + Log4j is released under the Apache 2.0 license. + + http://www.apache.org/licenses/LICENSE-2.0.html + + Module: slf4j-api + + SLF4J is distributed under the MIT License. + + Copyright (c) 2004-2013 QOS.ch + + All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining + + a copy of this software and associated documentation files (the + + "Software"), to deal in the Software without restriction, including + + without limitation the rights to use, copy, modify, merge, publish, + + distribute, sublicense, and/or sell copies of the Software, and to + + permit persons to whom the Software is furnished to do so, subject to + + the following conditions: + + The above copyright notice and this permission notice shall be + + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Proceed (y/N)? y +INFO : slf4j-api transitive, ini template available with --add-to-start=slf4j-api +INFO : jcl-impl transitive, ini template available with --add-to-start=jcl-impl +INFO : slf4j-jcl transitive +INFO : logging-jcl initialized in ${jetty.base}/start.d/logging-jcl.ini +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar +DOWNLOAD: http://central.maven.org/maven2/commons-logging/commons-logging/1.1.3/commons-logging-1.1.3.jar to ${jetty.base}/lib/jcl/commons-logging-1.1.3.jar +DOWNLOAD: http://central.maven.org/maven2/org/slf4j/slf4j-jcl/1.7.21/slf4j-jcl-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-jcl-1.7.21.jar +INFO : Base directory was modified + +$ tree +. +├── lib +│   ├── jcl +│   │   └── commons-logging-1.1.3.jar +│   └── slf4j +│   ├── slf4j-api-1.7.21.jar +│   └── slf4j-jcl-1.7.21.jar +└── start.d + ├── logging-jcl.ini +.... diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc index 4c593d6ac33..1d41d63c1f4 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc @@ -20,7 +20,7 @@ [[stderrlog-configuration]] ==== StdErrLog Configuration -If you do nothing to configure a separate logging framework, Jetty will default to using an internal `org.eclipse.jetty.util.log.StdErrLog` implementation. +If you do nothing to configure a separate logging framework, Jetty will default to using an internal `org.eclipse.jetty.util.log.StdErrLog` implementation. This will output all logging events to STDERR (aka `System.err`). Simply use Jetty and `StdErrLog` based logging is output. @@ -29,62 +29,55 @@ Included in the Jetty distribution is a logging module that is capable of perfor To enable on this feature via the command line: -[source,bash] ----- -[my-base]$ java -jar /opt/jetty/start.jar --module=logging ----- +[source, screen, subs="{sub-order}"] +.... +[my-base]$ java -jar /opt/jetty/start.jar --add-to-start=logging-jetty +.... -You can also include the `--module=logging` command in your `${jetty.base}/start.ini`. - -[source,bash] ----- -[my-base]$ java -jar /opt/jetty/start.jar --add-to-start=logging ----- - -The default configuration for logging output will create a file `${jetty.logs}/yyyy_mm_dd.stderrout.log` which allows configuration of the output directory by setting the `jetty.logs` property. +The default configuration for logging output will create a file `${jetty.base}/logs/yyyy_mm_dd.stderrout.log` which allows configuration of the output directory by setting the `jetty.logs` property. For more advanced logging configurations, please consider use of a separate logging library. -The recommended way to configure `StdErrLog` is to create a `${jetty.home}/resources/jetty-logging.properties` file, specify the log implementation to `StdErrLog` and then setup logging levels. +The recommended way to configure `StdErrLog` is to create a `${jetty.base}/resources/jetty-logging.properties` file, specify the log implementation to `StdErrLog` and then setup logging levels. -[source,properties] ----- +[source, properties, subs="{sub-order}"] +.... # Configure Jetty for StdErrLog Logging org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StrErrLog # Overall Logging Level is INFO org.eclipse.jetty.LEVEL=INFO # Detail Logging for WebSocket org.eclipse.jetty.websocket.LEVEL=DEBUG ----- +.... There are a number of properties that can be defined in the configuration that will affect the behavior of `StdErrLog`. `.LEVEL=`:: - Sets the logging level for all loggers within the `name` specified to the level, which can be (in increasing order of restriction) `ALL`, `DEBUG`, `INFO`, `WARN`, `OFF`. + Sets the logging level for all loggers within the `name` specified to the level, which can be (in increasing order of restriction) `ALL`, `DEBUG`, `INFO`, `WARN`, `OFF`. The name (or hierarchy) can be a specific fully qualified class or a package namespace. - For example, `org.eclipse.jetty.http.LEVEL=DEBUG` is a package namespace approach to turn all loggers in the Jetty HTTP package to DEBUG level, and `org.eclipse.jetty.io.ChanelEndPoint.LEVEL=ALL` turns on all logging events for the specific class, including `DEBUG`, `INFO`, `WARN` (and even special internally ignored exception classes). + For example, `org.eclipse.jetty.http.LEVEL=DEBUG` is a package namespace approach to turn all loggers in the Jetty HTTP package to DEBUG level, and `org.eclipse.jetty.io.ChanelEndPoint.LEVEL=ALL` turns on all logging events for the specific class, including `DEBUG`, `INFO`, `WARN` (and even special internally ignored exception classes). If more than one system property specifies a logging level, the most specific one applies. `.SOURCE=`:: - Named Logger specific, attempts to print the Java source file name and line number from where the logging event originated. - Name must be a fully qualified class name (this configurable does not support package name hierarchy). - Default is false. + Named Logger specific, attempts to print the Java source file name and line number from where the logging event originated. + Name must be a fully qualified class name (this configurable does not support package name hierarchy). + Default is false. Be aware that this is a slow operation and has an impact on performance. `.STACKS=`:: - Named Logger specific, controls the display of stacktraces. + Named Logger specific, controls the display of stacktraces. Name must be a fully qualified class name (this configurable does not support package name hierarchy). Default is true. `org.eclipse.jetty.util.log.stderr.SOURCE=`:: - Special Global Configuration. - Attempts to print the Java source file name and line number from where the logging event originated. + Special Global Configuration. + Attempts to print the Java source file name and line number from where the logging event originated. Default is false. `org.eclipse.jetty.util.log.stderr.LONG=`:: - Special Global Configuration. - When true, outputs logging events to `STDERR` using long form, fully qualified class names. + Special Global Configuration. + When true, outputs logging events to `STDERR` using long form, fully qualified class names. When false, uses abbreviated package names. Default is false. - + ++ * Example when set to false: - + ++ [source, screen, subs="{sub-order}"] .... 2014-06-03 14:36:16.013:INFO:oejs.Server:main: jetty-9.2.0.v20140526 @@ -93,9 +86,9 @@ There are a number of properties that can be defined in the configuration that w 2014-06-03 14:36:17.880:INFO:oejs.ServerConnector:main: Started ServerConnector@34f2d11a{HTTP/1.1}{0.0.0.0:8080} 2014-06-03 14:36:17.888:INFO:oejs.Server:main: Started @257ms .... - + ++ * Example when set to true: - + ++ [source, screen, subs="{sub-order}"] .... 2014-06-03 14:38:19.019:INFO:org.eclipse.jetty.server.Server:main: jetty-9.2.0.v20140526 @@ -108,7 +101,7 @@ There are a number of properties that can be defined in the configuration that w [[deprecated-parameters]] ==== Deprecated Parameters -These parameters existed in prior versions of Jetty, and are no longer supported. +These parameters existed in prior versions of Jetty, and are no longer supported. They are included here for historical (and search engine) reasons. `org.eclipse.jetty.util.log.DEBUG`:: diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc index 663ca27c8f4..92f72e8602b 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc @@ -14,10 +14,9 @@ // You may elect to redistribute this code under either of these licenses. // ======================================================================== -[[example-logging-log4j]] === Example: Logging with Apache Log4j -It is possible to have the Jetty Server logging configured so that Log4j controls the output of logging events produced by Jetty. +It is possible to have the Jetty Server logging configured so that Log4j controls the output of logging events produced by Jetty. This is accomplished by configuring Jetty for logging to http://logging.apache.org/log4j/[Apache Log4j] via http://slf4j.org/manual.html[Slf4j] and the http://slf4j.org/manual.html#swapping[Slf4j binding layer for Log4j]. A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with log4j. diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc index 9e29fbdbbfe..08e26d6518e 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc @@ -14,7 +14,6 @@ // You may elect to redistribute this code under either of these licenses. // ======================================================================== -[[example-logging-java-util-logging-native]] === Example: Logging with Java's java.util.logging via JavaUtilLog It is possible to have the Jetty Server logging configured so that @@ -26,7 +25,7 @@ This example demonstrates how to configuring Jetty for logging to ____ [IMPORTANT] -While this is a valid setup, the Jetty project recommends always using the link:#example-logging-java-util-logging[slf4j to java.util.logging configuration] for memory and performance reasons. +While this is a valid setup, the Jetty project recommends always using the link:#example-logging-java-util-logging[slf4j to java.util.logging configuration] for memory and performance reasons. This native implementation is very non-performant and is not guaranteed to exist in the future. ____ @@ -87,4 +86,4 @@ Other logging frameworks are more reliable in that they always initialize and co * While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique. For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle]. -____ \ No newline at end of file +____ diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc index 1e26e70a928..34ef7396576 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc @@ -14,7 +14,6 @@ // You may elect to redistribute this code under either of these licenses. // ======================================================================== -[[example-logging-java-util-logging]] === Example: Logging with Java's java.util.logging via Slf4j It is possible to have the Jetty Server logging configured so that `java.util.logging` controls the output of logging events produced by Jetty. @@ -82,4 +81,4 @@ Other logging frameworks are more reliable in that they always initialize and co * While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique. For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle]. -____ \ No newline at end of file +____ diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc index 9cfadf26f72..f24dfc2d795 100644 --- a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc @@ -14,10 +14,9 @@ // You may elect to redistribute this code under either of these licenses. // ======================================================================== -[[example-logging-logback]] === Example: Logging with Logback -It is possible to have the Jetty Server logging configured so that Logback controls the output of logging events produced by Jetty. +It is possible to have the Jetty Server logging configured so that Logback controls the output of logging events produced by Jetty. This is accomplished by configuring Jetty for logging to `Logback`, which uses http://slf4j.org/manual.html[Slf4j] and the http://logback.qos.ch/[Logback Implementation for Slf4j]. A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for logging with logback.