This is an automated email from the ASF dual-hosted git repository. grobmeier pushed a commit to branch ms12_conversion_of_md_files in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit e98471794559e41b108ace53db798322d1145b0a Author: Christian Grobmeier <[email protected]> AuthorDate: Thu Feb 22 18:31:57 2024 +0100 migrated more pages from markdown --- src/site/asciidoc/log4j-1.2-api.adoc | 69 ++++++++ .../log4j-api.md => asciidoc/log4j-api.adoc} | 20 +-- .../log4j-core.md => asciidoc/log4j-core.adoc} | 25 ++- src/site/asciidoc/log4j-iostreams.adoc | 46 ++++++ .../log4j-jdbc-dbcp2.adoc} | 29 ++-- .../log4j-jpl.md => asciidoc/log4j-jpl.adoc} | 19 +-- src/site/asciidoc/log4j-jul.adoc | 122 ++++++++++++++ .../log4j-layout-template-json.adoc} | 18 +- src/site/asciidoc/log4j-script.adoc | 124 ++++++++++++++ .../log4j-slf4j-impl.adoc} | 37 ++--- .../log4j-slf4j2-impl.adoc} | 33 ++-- .../asciidoc/log4j-spring-cloud-config-client.adoc | 184 +++++++++++++++++++++ .../log4j-to-jul.md => asciidoc/log4j-to-jul.adoc} | 33 ++-- .../log4j-to-slf4j.adoc} | 34 ++-- src/site/markdown/log4j-1.2-api.md | 48 ------ src/site/markdown/log4j-iostreams.md | 55 ------ src/site/markdown/log4j-jul.md | 118 ------------- src/site/markdown/log4j-script.md | 121 -------------- .../markdown/log4j-spring-cloud-config-client.md | 135 --------------- 19 files changed, 654 insertions(+), 616 deletions(-) diff --git a/src/site/asciidoc/log4j-1.2-api.adoc b/src/site/asciidoc/log4j-1.2-api.adoc new file mode 100644 index 0000000000..b831c39bf4 --- /dev/null +++ b/src/site/asciidoc/log4j-1.2-api.adoc @@ -0,0 +1,69 @@ +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// += Log4j 1.2 Bridge + +The Log4j 1.2 Bridge allows applications coded to use Log4j 1.2 API to use Log4j 2 instead. + +== Requirements + +The Log4j 1.2 bridge is dependent on the Log4j 2 API. +The following Log4j 1.x methods will behave differently when the Log4j 2 Core module is included then when it is not: + +|=== +| Method | Without log4j-core | With log4j-core + +| Category.getParent() +| Returns null +| Returns parent logger + +| Category.setLevel() +| NoOp +| Sets Logger Level + +| Category.setPriority() +| NoOp +| Sets Logger Level + +| Category.getAdditivity() +| Returns false +| Returns Logger's additivity setting + +| Category.setAdditivity() +| NoOp +| Sets additivity of LoggerConfig + +| Category.getResourceBundle() +| NoOp +| Returns the resource bundle associated with the Logger + +| BasicConfigurator.configure() +| NoOp +| Reconfigures Log4j 2 +|=== + +If log4j-core is not present location information will not be accurate in calls using the Log4j 1.2 API. +The config package which attempts to convert Log4j 1.x configurations to Log4j 2 is not supported without Log4j 2. + +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. + +== Usage + +To use the Log4j Legacy Bridge just remove all the Log4j 1.x jars from the application and replace them with the bridge jar. +Once in place all logging that uses Log4j 1.x will be routed to Log4j 2. +However, applications that attempt to modify legacy Log4j by adding Appenders, Filters, etc may experience problems if they try to verify the success of these actions as these methods are largely no-ops. diff --git a/src/site/markdown/log4j-api.md b/src/site/asciidoc/log4j-api.adoc similarity index 70% rename from src/site/markdown/log4j-api.md rename to src/site/asciidoc/log4j-api.adoc index f83cc0d7a6..89e016f502 100644 --- a/src/site/markdown/log4j-api.md +++ b/src/site/asciidoc/log4j-api.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,13 +15,12 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 API +//// += Log4j 2 API -The Log4j 2 API provides the interface that applications should code to and provides the -adapter components required for implementers to create a logging implementation. +The Log4j 2 API provides the interface that applications should code to and provides the adapter components required for implementers to create a logging implementation. -## Requirements +== Requirements -As of version 2.4, the Log4j 2 API requires Java 7. Versions 2.3 and earlier require Java 6. +As of version 2.4, the Log4j 2 API requires Java 7. +Versions 2.3 and earlier require Java 6. diff --git a/src/site/markdown/log4j-core.md b/src/site/asciidoc/log4j-core.adoc similarity index 69% rename from src/site/markdown/log4j-core.md rename to src/site/asciidoc/log4j-core.adoc index 7595a08e9a..b511c641a2 100644 --- a/src/site/markdown/log4j-core.md +++ b/src/site/asciidoc/log4j-core.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,20 +15,18 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 Implementation +//// += Log4j 2 Implementation The Log4j 2 implementation provides the functional components of the logging system. Users are free to create their own plugins and include them in the logging configuration. -## Requirements +== Requirements -As of version 2.4, Log4j 2 requires Java 7. Versions 2.3 and earlier require Java 6. -Some features may require optional -[dependencies](../runtime-dependencies.html). These dependencies are specified in the -documentation for those features. +As of version 2.4, Log4j 2 requires Java 7. +Versions 2.3 and earlier require Java 6. +Some features may require optional link:../runtime-dependencies.html[dependencies]. +These dependencies are specified in the documentation for those features. Some Log4j features require external dependencies. -See the [Dependency Tree](dependencies.html#Dependency_Tree) -for the exact list of JAR files needed for these features. +See the link:dependencies.html#Dependency_Tree[Dependency Tree] for the exact list of JAR files needed for these features. diff --git a/src/site/asciidoc/log4j-iostreams.adoc b/src/site/asciidoc/log4j-iostreams.adoc new file mode 100644 index 0000000000..9382dd5193 --- /dev/null +++ b/src/site/asciidoc/log4j-iostreams.adoc @@ -0,0 +1,46 @@ +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// += Log4j IOStreams + +== Log4j IOStreams + +The IOStreams component is a link:javadoc/log4j-api/index.html[Log4j API] extension that provides numerous classes from http://docs.oracle.com/javase/6/docs/api/java/io/package-summary.html[`java.io`] that can either write to a link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] while writing to another `OutputStream` or `Writer`, or the contents read by an `InputStream` or `Reader` can be http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`. + +== Requirements + +The Log4j IOStreams API extension requires the Log4j 2 API. +This component was introduced in Log4j 2.1. +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. + +== Usage + +The main entry point for the IOStreams module is the builder class `IoBuilder`, and in particular, the `IoBuilder.forLogger()` methods. +One primary usage of this API extension is for setting up loggers in the JDBC API. +For example: + +---- +PrintWriter logger = IoBuilder.forLogger(DriverManager.class) + .setLevel(Level.DEBUG) + .buildPrintWriter(); +DriverManager.setLogWriter(logger); +---- + +Using the `IoBuilder` class, there are a few more options that can be set. +In general, there are six primary classes one can build from it: `Reader`, `Writer`, `PrintWriter`, `InputStream`, `OutputStream`, and `PrintStream`. +The input-oriented classes are for wiretapping, and the output-oriented classes are for creating either an output class that solely outputs its lines as log messages, or an output filter class that logs all lines output through it to its delegate output class. diff --git a/src/site/markdown/log4j-jdbc-dbcp2.md b/src/site/asciidoc/log4j-jdbc-dbcp2.adoc similarity index 60% rename from src/site/markdown/log4j-jdbc-dbcp2.md rename to src/site/asciidoc/log4j-jdbc-dbcp2.adoc index b7fb5a56bd..0cfc478f62 100644 --- a/src/site/markdown/log4j-jdbc-dbcp2.md +++ b/src/site/asciidoc/log4j-jdbc-dbcp2.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,22 +15,18 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 JDBC Connection Source with Apache Commons DBCP 2 +//// += Log4j 2 JDBC Connection Source with Apache Commons DBCP 2 -This module adds a connection source for JDBC Appenders. The PoolingDriverConnectionSource -provides connection pooling through Apache Commons DBCP 2. +This module adds a connection source for JDBC Appenders. +The PoolingDriverConnectionSource provides connection pooling through Apache Commons DBCP 2. -## Requirements +== Requirements -This module was introduced in Log4j 2.11.0 and requires Apache Commons DBCP 2 to provide -connection pooling. +This module was introduced in Log4j 2.11.0 and requires Apache Commons DBCP 2 to provide connection pooling. -Some features may require optional -[dependencies](../runtime-dependencies.html). These dependencies are specified in the -documentation for those features. +Some features may require optional link:../runtime-dependencies.html[dependencies]. +These dependencies are specified in the documentation for those features. Some Log4j features require external dependencies. -See the [Dependency Tree](dependencies.html#Dependency_Tree) -for the exact list of JAR files needed for these features. +See the link:dependencies.html#Dependency_Tree[Dependency Tree] for the exact list of JAR files needed for these features. diff --git a/src/site/markdown/log4j-jpl.md b/src/site/asciidoc/log4j-jpl.adoc similarity index 78% rename from src/site/markdown/log4j-jpl.md rename to src/site/asciidoc/log4j-jpl.adoc index 1e5da7932e..0357415eff 100644 --- a/src/site/markdown/log4j-jpl.md +++ b/src/site/asciidoc/log4j-jpl.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,17 +15,15 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 JDK Platform Logging Adapter +//// += Log4j 2 JDK Platform Logging Adapter The Log4j 2 JDK Logging Adapter allow to route all System.Logger events to Log4j 2 APIs. -## Requirements +== Requirements The JDK Platform Logging Adapter is dependent on the Log4j API as well as Java 11. -## Usage +== Usage -Simply include the Log4j 2 JDK Platform Logging Adapter jar along with the Log4j2 jars to cause all System.Logger -logging to be handled by Log4j 2. +Simply include the Log4j 2 JDK Platform Logging Adapter jar along with the Log4j2 jars to cause all System.Logger logging to be handled by Log4j 2. diff --git a/src/site/asciidoc/log4j-jul.adoc b/src/site/asciidoc/log4j-jul.adoc new file mode 100644 index 0000000000..16dfc27f61 --- /dev/null +++ b/src/site/asciidoc/log4j-jul.adoc @@ -0,0 +1,122 @@ +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// +:doctype: book + +There are two possibilities: + +* Logging Adapter as complete replacement (preferred, but requires JVM start option) +* Bridge Handler, transfering JDK output to log4j, e.g. +useful for webapps + += Log4j JDK Logging Adapter + +The JDK Logging Adapter is a custom implementation of http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogManager.html[`java.util.logging.LogManager`] that uses link:javadoc/log4j-core/index.html[Log4j]. +This adapter can be used with either the Log4j API or Log4j Core. +When used with the API, there are a couple features of JUL that aren't supported. +However, this does allow any other Log4j Provider besides the Core provider to be used with JUL. + +== Requirements + +The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j Core. +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. + +== Usage + +To use the JDK Logging Adapter, you must set the system property `java.util.logging.manager` to `org.apache.logging.log4j.jul.LogManager`. + +This must be done either through the command line (i.e., using the `-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager` argument) or by using `System.setProperty()` before any calls are made to `LogManager` or `Logger`. + +== Compatibility + +The use of a http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html[`java.util.logging.Filter`] is supported on a per-http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html[`Logger`] basis. +However, it is recommended to use the standard link:manual/filters.html[Filters] feature in Log4j instead. + +The use of http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html[`java.util.logging.Handler`] classes is _NOT_ supported. +Custom Handlers should instead use an appropriate link:manual/appenders.html[Appender] or code their own link:javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html[`Appender`] plugin. + +Java logging levels are translated into Log4j logging levels dynamically. +The following table lists the conversions between a Java logging level and its equivalent Log4j level. +Custom levels should be implemented as an implementation of `LevelConverter`, and the Log4j property `log4j.jul.levelConverter` must be set to your custom class name. +Using the default `LevelConverter` implementation, custom logging levels are mapped to whatever the current level of the `Logger` being logged to is using. + +=== Default Level Conversions + +|=== +| Java Level | Log4j Level + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF[`OFF`] +| `OFF` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE[`SEVERE`] +| `ERROR` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING[`WARNING`] +| `WARN` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO[`INFO`] +| `INFO` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG[`CONFIG`] +| `CONFIG` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE[`FINE`] +| `DEBUG` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER[`FINER`] +| `TRACE` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST[`FINEST`] +| `FINEST` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL[`ALL`] +| `ALL` +|=== + += Log4j JDK Logging Bridge Handler + +The LogManager is not always useable because you have to set a JVM wide effective system property - e.g. +in web servers this is not possible if you are not the administrator. + +The `Log4jBridgeHandler` is an alternative that can be declaratively used via `logging.properties`. + +It is less performant than the LogManager but still okay to use: the LogManager replaces the JDK implementation, so your logging code (using JDK syntax) effectively directly uses log4j. +When using the BridgeHandler the original JDK implementation along with its configuration (e.g. +log levels) is still fully working but the log events are "written" via this handler to log4j as if you would have called log4j.Logger.debug() etc.; +it is like a FileHandler but instead of writing to a file, it "writes" to log4j Loggers - thus there is some overhead compared to using LogManager. + +== Usage + +The JUL configuration file `logging.properties` needs the line + +`handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler` + +and JUL logs go to log4j2. +Additionally, you typically want to use to following: + +`org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true` + +In a webapp on Tomcat (and maybe other servers, too), you may simply create a `WEB-INF/classes/logging.properties` file with above content. +The bridge and the log levels defined in this file are only valid for your webapp and do _not_ have any impact on the other webapps on the same Tomcat instance. + +Alternatively you may call `Log4jBridgeHandler.install()` inside your webapp's initialization code, e.g. +inside `ServletContextListener` or a `ServletFilter` static-class-init. +or `contextInitialized()`. + +IMPORTANT: Log levels of JDK should match the ones of log4j. +You may do this manually or use the automatic level propagation via `Log4jBridgeHandler.propagateLevels = true`. diff --git a/src/site/markdown/log4j-layout-template-json.md b/src/site/asciidoc/log4j-layout-template-json.adoc similarity index 74% rename from src/site/markdown/log4j-layout-template-json.md rename to src/site/asciidoc/log4j-layout-template-json.adoc index c79769640d..4cfbfdff6c 100644 --- a/src/site/markdown/log4j-layout-template-json.md +++ b/src/site/asciidoc/log4j-layout-template-json.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,19 +15,18 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Apache Log4j JSON Template Layout module +//// += Apache Log4j JSON Template Layout module This module provides a customizable, efficient, and garbage-free JSON generating Apache Log4j layout. It encodes log events according to the structure described by the JSON template provided. -## Requirements +== Requirements This module was introduced in Log4j 2.14.0. -Some features may require optional [dependencies](../runtime-dependencies.html). +Some features may require optional link:../runtime-dependencies.html[dependencies]. These dependencies are specified in the documentation for those features. Some Log4j features require external dependencies. -See the [Dependency Tree](dependencies.html#Dependency_Tree) for the exact list of JAR files needed for these features. +See the link:dependencies.html#Dependency_Tree[Dependency Tree] for the exact list of JAR files needed for these features. diff --git a/src/site/asciidoc/log4j-script.adoc b/src/site/asciidoc/log4j-script.adoc new file mode 100644 index 0000000000..2a19cad081 --- /dev/null +++ b/src/site/asciidoc/log4j-script.adoc @@ -0,0 +1,124 @@ +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// +:doctype: book + +There are two possibilities: + +* Logging Adapter as complete replacement (preferred, but requires JVM start option) +* Bridge Handler, transfering JDK output to log4j, e.g. +useful for webapps + += Log4j JDK Logging Adapter + +The JDK Logging Adapter is a custom implementation of http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogManager.html[`java.util.logging.LogManager`] that uses link:../log4j-core/index.html[Log4j]. +This adapter can be used with either the Log4j API or Log4j Core. +When used with the API, there are a couple features of JUL that aren't supported. +However, this does allow any other Log4j Provider besides the Core provider to be used with JUL. + +== Requirements + +The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j Core. +For more information, see link:../runtime-dependencies.html[Runtime Dependencies]. + +== Usage + +To use the JDK Logging Adapter, you must set the system property `java.util.logging.manager` to link:apidocs/org/apache/logging/log4j/jul/LogManager.html[`org.apache.logging.log4j.jul.LogManager`] + +This must be done either through the command line (i.e., using the `-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager` argument) or by using `System.setProperty()` before any calls are made to `LogManager` or `Logger`. + +== Compatibility + +The use of a http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html[`java.util.logging.Filter`] is supported on a per-http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html[`Logger`] basis. +However, it is recommended to use the standard link:../manual/filters.html[Filters] feature in Log4j instead. + +The use of http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html[`java.util.logging.Handler`] classes is _NOT_ supported. +Custom Handlers should instead use an appropriate link:../manual/appenders.html[Appender] or code their own link:../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html[`Appender`] plugin. + +Java logging levels are translated into Log4j logging levels dynamically. +The following table lists the conversions between a Java logging level and its equivalent Log4j level. +Custom levels should be implemented as an implementation of link:apidocs/org/apache/logging/log4j/jul/LevelConverter.html[`LevelConverter`], and the Log4j property `log4j.jul.levelConverter` must be set to your custom class name. +Using the default `LevelConverter` implementation, custom logging levels are mapped to whatever the current level of the `Logger` being logged to is using. + +=== Default Level Conversions + +|=== +| Java Level | Log4j Level + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF[`OFF`] +| `OFF` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE[`SEVERE`] +| `ERROR` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING[`WARNING`] +| `WARN` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO[`INFO`] +| `INFO` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG[`CONFIG`] +| link:apidocs/org/apache/logging/log4j/jul/LevelTranslator.html#CONFIG[`CONFIG`] + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE[`FINE`] +| `DEBUG` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER[`FINER`] +| `TRACE` + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST[`FINEST`] +| link:apidocs/org/apache/logging/log4j/jul/LevelTranslator.html#FINEST[`FINEST`] + +| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL[`ALL`] +| `ALL` +|=== + += Log4j JDK Logging Bridge Handler + +The LogManager is not always useable because you have to set a JVM wide effective system property - e.g. +in web servers this is not possible if you are not the administrator. + +The link:apidocs/org/apache/logging/log4j/jul/Log4jBridgeHandler.html[`Log4jBridgeHandler`] is an alternative that can be declaratively used via `logging.properties`. + +It is less performant than the LogManager but still okay to use: the LogManager replaces the JDK implementation, so your logging code (using JDK syntax) effectively directly uses log4j. +When using the BridgeHandler the original JDK implementation along with its configuration (e.g. +log levels) is still fully working but the log events are "written" via this handler to log4j as if you would have called log4j.Logger.debug() etc.; +it is like a FileHandler but instead of writing to a file, it "writes" to log4j Loggers - thus there is some overhead compared to using LogManager. + +== Usage + +The JUL configuration file `logging.properties` needs the line + +`handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler` + +and JUL logs go to log4j2. +Additionally, you typically want to use to following: + +`org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true` + +In a webapp on Tomcat (and maybe other servers, too), you may simply create a `WEB-INF/classes/logging.properties` file with above content. +The bridge and the log levels defined in this file are only valid for your webapp and do _not_ have any impact on the other webapps on the same Tomcat instance. + +Alternatively you may call `Log4jBridgeHandler.install()` inside your webapp's initialization code, e.g. +inside `ServletContextListener` or a `ServletFilter` static-class-init. +or `contextInitialized()`. + +IMPORTANT: Log levels of JDK should match the ones of log4j. +You may do this manually or use the automatic level propagation via `Log4jBridgeHandler.propagateLevels = true`. + +Please, read the link:apidocs/org/apache/logging/log4j/jul/Log4jBridgeHandler.html[JavaDoc] for detailed configuration and limitation information! diff --git a/src/site/markdown/log4j-slf4j-impl.md b/src/site/asciidoc/log4j-slf4j-impl.adoc similarity index 60% rename from src/site/markdown/log4j-slf4j-impl.md rename to src/site/asciidoc/log4j-slf4j-impl.adoc index 282b3cff6d..6dd6c36da8 100644 --- a/src/site/markdown/log4j-slf4j-impl.md +++ b/src/site/asciidoc/log4j-slf4j-impl.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,34 +15,26 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 SLF4J Binding +//// += Log4j 2 SLF4J Binding -The Log4j 2 SLF4J Binding allows applications coded to the SLF4J API to use -Log4j 2 as the implementation. +The Log4j 2 SLF4J Binding allows applications coded to the SLF4J API to use Log4j 2 as the implementation. Due to a break in compatibility in the SLF4J binding, as of release 2.11.1 two SLF4J to Log4j Adapters are provided. -1. log4j-slf4j-impl should be used with SLF4J 1.7.x releases or older. -1. log4j-slf4j18-impl should be used with SLF4J 1.8.x releases or newer. +. log4j-slf4j-impl should be used with SLF4J 1.7.x releases or older. +. log4j-slf4j18-impl should be used with SLF4J 1.8.x releases or newer. Applications that take advantage of the Java Module System should use SLF4J 1.8.x and log4j-slf4j18-impl. -## Requirements +== Requirements The Log4j 2 SLF4J Binding has a dependency on the Log4j 2 API as well as the SLF4J API. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. -## Usage +== Usage -The SLF4J binding provided in this component cause all the SLF4J APIs to be routed to Log4j 2. Simply -include the Log4j 2 SLF4J Binding jar along with the Log4j 2 jars and SLF4J API jar to cause all SLF4J -logging to be handled by Log4j 2. +The SLF4J binding provided in this component cause all the SLF4J APIs to be routed to Log4j 2. +Simply include the Log4j 2 SLF4J Binding jar along with the Log4j 2 jars and SLF4J API jar to cause all SLF4J logging to be handled by Log4j 2. -<div class="alert alert-danger"> -Use of the Log4j 2 SLF4J Binding (log4j-slf4j-impl-2.0.jar) together with -the SLF4J adapter (log4j-to-slf4j-2.0.jar) should -never be attempted, as it will cause events to endlessly be routed between -SLF4J and Log4j 2. -</div> +Use of the Log4j 2 SLF4J Binding (log4j-slf4j-impl-2.0.jar) together with the SLF4J adapter (log4j-to-slf4j-2.0.jar) should never be attempted, as it will cause events to endlessly be routed between SLF4J and Log4j 2. diff --git a/src/site/markdown/log4j-slf4j2-impl.md b/src/site/asciidoc/log4j-slf4j2-impl.adoc similarity index 60% rename from src/site/markdown/log4j-slf4j2-impl.md rename to src/site/asciidoc/log4j-slf4j2-impl.adoc index b88c3d9ff4..71626565bc 100644 --- a/src/site/markdown/log4j-slf4j2-impl.md +++ b/src/site/asciidoc/log4j-slf4j2-impl.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,27 +15,19 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j 2 SLF4J Binding +//// += Log4j 2 SLF4J Binding -The Log4j 2 SLF4J Binding allows applications coded to the SLF4J API to use -Log4j 2 as the implementation. +The Log4j 2 SLF4J Binding allows applications coded to the SLF4J API to use Log4j 2 as the implementation. -## Requirements +== Requirements The Log4j 2 SLF4J Binding has a dependency on the Log4j 2 API as well as the SLF4J API. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. -## Usage +== Usage -The SLF4J binding provided in this component cause all the SLF4J APIs to be routed to Log4j 2. Simply -include the Log4j 2 SLF4J Binding jar along with the Log4j 2 jars and SLF4J API jar to cause all SLF4J -logging to be handled by Log4j 2. +The SLF4J binding provided in this component cause all the SLF4J APIs to be routed to Log4j 2. +Simply include the Log4j 2 SLF4J Binding jar along with the Log4j 2 jars and SLF4J API jar to cause all SLF4J logging to be handled by Log4j 2. -<div class="alert alert-danger"> -Use of the Log4j 2 SLF4J Binding (log4j-slf4j-impl-2.0.jar) together with -the SLF4J adapter (log4j-to-slf4j-2.0.jar) should -never be attempted, as it will cause events to endlessly be routed between -SLF4J and Log4j 2. -</div> +Use of the Log4j 2 SLF4J Binding (log4j-slf4j-impl-2.0.jar) together with the SLF4J adapter (log4j-to-slf4j-2.0.jar) should never be attempted, as it will cause events to endlessly be routed between SLF4J and Log4j 2. diff --git a/src/site/asciidoc/log4j-spring-cloud-config-client.adoc b/src/site/asciidoc/log4j-spring-cloud-config-client.adoc new file mode 100644 index 0000000000..3032d9ba6d --- /dev/null +++ b/src/site/asciidoc/log4j-spring-cloud-config-client.adoc @@ -0,0 +1,184 @@ +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// += Log4j Spring Cloud Configuration + +This module allows logging configuration files to be dynamically updated when new versions are available in Spring Cloud Configuration. + +== Overview + +Spring Boot applications initialize logging 3 times. + +. SpringApplication declares a Logger. +This Logger will be initialized using Log4j's "normal" mechanisms. +Thus a system property named log4j2.configurationFile will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath. +The property may also be declare in log4j2.component.properties. + +== Usage + +Log4j configuration files that specify a monitor interval of greater than zero will use polling to determine whether the configuration has been updated. +If the monitor interval is zero then Log4j will listen for notifications from Spring Cloud Config and will check for configuration changes each time an event is generated. +If the monitor interval is less than zero Log4j will not check for changes to the logging configuration. + +When referencing a configuration located in Spring Cloud Config the configuration should be referenced similar to + +---- +log4j.configurationFile=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2.xml +---- + +Log4j also supports Composite Configurations. +The standard way to do that is to concatentate the paths to the files in a comma separated string. +Unfortunately, Spring validates the URL being provided and commas are not allowed. +Therefore, additional configurations must be supplied as "override" query parametes. + +---- +log4j.configurationFile=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2.xml +?override=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2-sampleapp.xml +---- + +Note that the location within the directory structure and how configuration files are located is completely dependent on the searchPaths setting in the Spring Cloud Config server. + +When running in a docker container host.docker.internal may be used as the domain name to access an application running on the same hose outside of the docker container. +Note that in accordance with Spring Cloud Config practices but the application, profile, and label should be specified in the url. + +The Spring Cloud Config support also allows connections using TLS and/or basic authentication. +When using basic authentication the userid and password may be specified as system properties, log4j2.component.properties or Spring Boot's bootstrap.yml. +The table below shows the alternate names that may be used to specify the properties. +Any of the alternatives may be used in any configuration location. + +|=== +| Property | Alias | Spring-like alias | Purpose + +| log4j2.configurationUserName +| log4j2.config.username +| logging.auth.username +| User name for basic authentication + +| log4j2.configurationPassword +| log4j2.config.password +| logging.auth.password +| Password for basic authentication + +| log4j2.authorizationProvider +| log4j2.config.authorizationProvider +| logging.auth.authorizationProvider +| Class used to create HTTP Authorization header +|=== + +---- +log4j2.configurationUserName=guest +log4j2.configurationPassword=guest +---- + +As noted above, Log4j supports accessing logging configuration from bootstrap.yml. +As an example, to configure reading from a Spring Cloud Configuration service using basic authoriztion you can do: + +---- +spring: + application: + name: myApp + cloud: + config: + uri: https://spring-configuration-server.mycorp.com + username: appuser + password: changeme + +logging: + config: classpath:log4j2.xml + label: ${spring.cloud.config.label} + +--- +spring: + profiles: dev + +logging: + config: https://spring-configuration-server.mycorp.com/myApp/default/${logging.label}/log4j2-dev.xml + auth: + username: appuser + password: changeme +---- + +Note that Log4j currently does not directly support encrypting the password. +However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well. + +If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`. + +TLS can be enabled by adding the following system properties or defining them in log4j2.component.properties + +|=== +| Property | Optional or Default Value | Description + +| log4j2.trustStoreLocation +| Optional +| The location of the trust store. +If not provided the default trust store will be used. + +| log4j2.trustStorePassword +| Optional +| Password needed to access the trust store. + +| log4j2.trustStorePasswordFile +| Optional +| The location of a file that contains the password for the trust store. + +| log4j2.trustStorePasswordEnvironmentVariable +| Optional +| The name of the environment variable that contains the trust store password. + +| log4j2.trustStoreKeyStoreType +| Required if keystore location provided +| The type of key store. + +| log4j2.trustStoreKeyManagerFactoryAlgorithm +| Optional +| Java cryptographic algorithm. + +| log4j2.keyStoreLocation +| Optional +| The location of the key store. +If not provided the default key store will be used. + +| log4j2.keyStorePassword +| Optional +| Password needed to access the key store. + +| log4j2.keyStorePasswordFile +| Optional +| The location of a file that contains the password for the key store. + +| log4j2.keyStorePasswordEnvironmentVariable +| Optional +| The name of the environment variable that contains the key store password. + +| log4j2.keyStoreType +| Required if trust store location provided. +| The type of key store. + +| log4j2.keyStoreKeyManagerFactoryAlgorithm +| Optional +| Java cryptographic algorithm. + +| log4j2.sslVerifyHostName +| false +| true or false +|=== + +== Requirements + +The Log4j 2 Spring Cloud Configuration integration has a dependency on Log4j 2 API, Log4j 2 Core, and Spring Cloud Configuration versions 2.0.3.RELEASE or 2.1.1.RELEASE or later versions it either release series. +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. diff --git a/src/site/markdown/log4j-to-jul.md b/src/site/asciidoc/log4j-to-jul.adoc similarity index 58% rename from src/site/markdown/log4j-to-jul.md rename to src/site/asciidoc/log4j-to-jul.adoc index ece1b5b69f..169fc3a283 100644 --- a/src/site/markdown/log4j-to-jul.md +++ b/src/site/asciidoc/log4j-to-jul.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,28 +15,22 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j to JUL Adapter +//// += Log4j to JUL Adapter The Log4j 2 to JUL Adapter allows applications coded to the Log4j 2 API to be routed to `java.util.logging` (JUL). -Use of this adapter may cause some loss of performance as the Log4j 2 Messages must be formatted -before they can be passed to JUL. With Log4j 2 as the implementation these would normally be -formatted only when they are accessed by a Filter or Appender. +Use of this adapter may cause some loss of performance as the Log4j 2 Messages must be formatted before they can be passed to JUL. +With Log4j 2 as the implementation these would normally be formatted only when they are accessed by a Filter or Appender. -## Requirements +== Requirements The Log4j 2 to JUL adapter is dependent on the Log4j 2 API. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. -## Usage +== Usage -Include this JAR. Configure JUL as usual. +Include this JAR. +Configure JUL as usual. -<div class="alert alert-danger"> -Use of the JUL adapter (log4j-to-jul-2.x.jar) together with -the JUL bridge (log4j-jul-2.x.jar) should -never be attempted as it will cause events to endlessly be routed between -SLF4J and JUL. -</div> \ No newline at end of file +Use of the JUL adapter (log4j-to-jul-2.x.jar) together with the JUL bridge (log4j-jul-2.x.jar) should never be attempted as it will cause events to endlessly be routed between SLF4J and JUL. diff --git a/src/site/markdown/log4j-to-slf4j.md b/src/site/asciidoc/log4j-to-slf4j.adoc similarity index 58% rename from src/site/markdown/log4j-to-slf4j.md rename to src/site/asciidoc/log4j-to-slf4j.adoc index 47a25146c1..a51395c095 100644 --- a/src/site/markdown/log4j-to-slf4j.md +++ b/src/site/asciidoc/log4j-to-slf4j.adoc @@ -1,6 +1,7 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more +// vim: set syn=markdown : + +//// +Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 @@ -14,28 +15,21 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - -# Log4j to SLF4J Adapter +//// += Log4j to SLF4J Adapter The Log4j 2 to SLF4J Adapter allows applications coded to the Log4j 2 API to be routed to SLF4J. -Use of this adapter may cause some loss of performance as the Log4j 2 Messages must be formatted -before they can be passed to SLF4J. With Log4j 2 as the implementation these would normally be -formatted only when they are accessed by a Filter or Appender. +Use of this adapter may cause some loss of performance as the Log4j 2 Messages must be formatted before they can be passed to SLF4J. +With Log4j 2 as the implementation these would normally be formatted only when they are accessed by a Filter or Appender. -## Requirements +== Requirements The Log4j 2 to SLF4J adapter is dependent on the Log4j 2 API and the SLF4J API. -For more information, see [Runtime Dependencies](runtime-dependencies.html). +For more information, see link:runtime-dependencies.html[Runtime Dependencies]. -## Usage +== Usage -Include this jar, the SLF4J jar(s) and an SLF4J logging implementation jar together. Configure -the logging implementation as required. +Include this jar, the SLF4J jar(s) and an SLF4J logging implementation jar together. +Configure the logging implementation as required. -<div class="alert alert-danger"> -Use of the SLF4J adapter (log4j-to-slf4j-2.x.jar) together with -the SLF4J bridge (log4j-slf4j-impl-2.x.jar) should -never be attempted as it will cause events to endlessly be routed between -SLF4J and Log4j 2. -</div> +Use of the SLF4J adapter (log4j-to-slf4j-2.x.jar) together with the SLF4J bridge (log4j-slf4j-impl-2.x.jar) should never be attempted as it will cause events to endlessly be routed between SLF4J and Log4j 2. diff --git a/src/site/markdown/log4j-1.2-api.md b/src/site/markdown/log4j-1.2-api.md deleted file mode 100644 index 4e1c1673e4..0000000000 --- a/src/site/markdown/log4j-1.2-api.md +++ /dev/null @@ -1,48 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -# Log4j 1.2 Bridge - -The Log4j 1.2 Bridge allows applications coded to use Log4j 1.2 API to use Log4j 2 instead. - -## Requirements - -The Log4j 1.2 bridge is dependent on the Log4j 2 API. The following Log4j 1.x methods will behave differently when -the Log4j 2 Core module is included then when it is not: - -| Method | Without log4j-core | With log4j-core | -| ----------------------------- | ------------------ | ------------------------------------ | -| Category.getParent() | Returns null | Returns parent logger | -| Category.setLevel() | NoOp | Sets Logger Level | -| Category.setPriority() | NoOp | Sets Logger Level | -| Category.getAdditivity() | Returns false | Returns Logger's additivity setting | -| Category.setAdditivity() | NoOp | Sets additivity of LoggerConfig | -| Category.getResourceBundle() | NoOp | Returns the resource bundle associated with the Logger | -| BasicConfigurator.configure() | NoOp | Reconfigures Log4j 2 | - -If log4j-core is not present location information will not be accurate in calls using the Log4j 1.2 API. The config -package which attempts to convert Log4j 1.x configurations to Log4j 2 is not supported without Log4j 2. - -For more information, see [Runtime Dependencies](runtime-dependencies.html). - -## Usage - -To use the Log4j Legacy Bridge just remove all the Log4j 1.x jars from the application and replace them -with the bridge jar. Once in place all logging that uses Log4j 1.x will be routed to Log4j 2. However, -applications that attempt to modify legacy Log4j by adding Appenders, Filters, etc may experience problems -if they try to verify the success of these actions as these methods are largely no-ops. diff --git a/src/site/markdown/log4j-iostreams.md b/src/site/markdown/log4j-iostreams.md deleted file mode 100644 index 26693de965..0000000000 --- a/src/site/markdown/log4j-iostreams.md +++ /dev/null @@ -1,55 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -# Log4j IOStreams - -## Log4j IOStreams - -The IOStreams component is a [Log4j API](javadoc/log4j-api/index.html) extension that provides numerous -classes from -[`java.io`](http://docs.oracle.com/javase/6/docs/api/java/io/package-summary.html) -that can either write to a -[`Logger`](javadoc/log4j-api/org/apache/logging/log4j/Logger.html) -while writing to another `OutputStream` or `Writer`, or the contents read by an -`InputStream` or `Reader` can be -[wiretapped](http://www.eaipatterns.com/WireTap.html) by a `Logger`. - -## Requirements - -The Log4j IOStreams API extension requires the Log4j 2 API. This component was introduced in Log4j 2.1. -For more information, see [Runtime Dependencies](runtime-dependencies.html). - -## Usage -The main entry point for the IOStreams module is the builder class -`IoBuilder`, and in particular, -the `IoBuilder.forLogger()` methods. One primary usage of this API extension is for setting up -loggers in the JDBC API. For example: - -``` -PrintWriter logger = IoBuilder.forLogger(DriverManager.class) - .setLevel(Level.DEBUG) - .buildPrintWriter(); -DriverManager.setLogWriter(logger); -``` - -Using the `IoBuilder` class, there are a few more options that can be set. In general, there are six -primary classes one can build from it: `Reader`, `Writer`, `PrintWriter`, -`InputStream`, `OutputStream`, and `PrintStream`. The input-oriented classes -are for wiretapping, and the output-oriented classes are for creating either an output class that solely outputs -its lines as log messages, or an output filter class that logs all lines output through it to its delegate -output class. diff --git a/src/site/markdown/log4j-jul.md b/src/site/markdown/log4j-jul.md deleted file mode 100644 index 5154e7727a..0000000000 --- a/src/site/markdown/log4j-jul.md +++ /dev/null @@ -1,118 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -There are two possibilities: -- Logging Adapter as complete replacement (preferred, but requires JVM start option) -- Bridge Handler, transfering JDK output to log4j, e.g. useful for webapps - -# Log4j JDK Logging Adapter - -The JDK Logging Adapter is a custom implementation of -[`java.util.logging.LogManager`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogManager.html) -that uses [Log4j](javadoc/log4j-core/index.html). This adapter can be used with either the Log4j API or -Log4j Core. When used with the API, there are a couple features of JUL that aren't supported. However, this -does allow any other Log4j Provider besides the Core provider to be used with JUL. - -## Requirements - -The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j Core. -For more information, see [Runtime Dependencies](runtime-dependencies.html). - -## Usage - -To use the JDK Logging Adapter, you must set the system property `java.util.logging.manager` to -`org.apache.logging.log4j.jul.LogManager`. - -This must be done either through the command line (i.e., using the -`-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager` argument) or by using -`System.setProperty()` before any calls are made to `LogManager` or `Logger`. - -## Compatibility - -The use of a -[`java.util.logging.Filter`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html) -is supported on a per-[`Logger`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html) -basis. However, it is recommended to use the standard [Filters](manual/filters.html) feature in -Log4j instead. - -The use of -[`java.util.logging.Handler`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html) -classes is _NOT_ supported. Custom Handlers should instead use an appropriate -[Appender](manual/appenders.html) or code their own -[`Appender`](javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html) -plugin. - -Java logging levels are translated into Log4j logging levels dynamically. The following table lists the -conversions between a Java logging level and its equivalent Log4j level. Custom levels should be implemented -as an implementation of -`LevelConverter`, and the -Log4j property `log4j.jul.levelConverter` must be set to your custom class name. Using the default -`LevelConverter` implementation, custom logging levels are mapped to whatever the current level of -the `Logger` being logged to is using. - -### Default Level Conversions - -Java Level | Log4j Level ----------- | ----------- -[`OFF`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF) | `OFF` -[`SEVERE`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE) | `ERROR` -[`WARNING`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING) | `WARN` -[`INFO`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO) | `INFO` -[`CONFIG`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG) | `CONFIG` -[`FINE`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE) | `DEBUG` -[`FINER`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER) | `TRACE` -[`FINEST`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST) | `FINEST` -[`ALL`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL) | `ALL` - - -# Log4j JDK Logging Bridge Handler - -The LogManager is not always useable because you have to set a JVM wide effective system -property - e.g. in web servers this is not possible if you are not the administrator. - -The `Log4jBridgeHandler` is an -alternative that can be declaratively used via `logging.properties`. - -It is less performant than the LogManager but still okay to use: the LogManager replaces the JDK -implementation, so your logging code (using JDK syntax) effectively directly uses log4j. -When using the BridgeHandler the original JDK implementation along with its configuration -(e.g. log levels) is still fully working but the log events are "written" via this handler to log4j -as if you would have called log4j.Logger.debug() etc.; it is like a FileHandler but instead of -writing to a file, it "writes" to log4j Loggers - thus there is some overhead compared to using -LogManager. - -## Usage - -The JUL configuration file `logging.properties` needs the line - -`handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler` - -and JUL logs go to log4j2. Additionally, you typically want to use to following: - -`org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true` - -In a webapp on Tomcat (and maybe other servers, too), you may simply create a -`WEB-INF/classes/logging.properties` file with above content. -The bridge and the log levels defined in this file are only valid for your webapp and -do *not* have any impact on the other webapps on the same Tomcat instance. - -Alternatively you may call `Log4jBridgeHandler.install()` inside your webapp's initialization code, -e.g. inside `ServletContextListener` or a `ServletFilter` static-class-init. or `contextInitialized()`. - -**Important:** Log levels of JDK should match the ones of log4j. You may do this manually or use the -automatic level propagation via `Log4jBridgeHandler.propagateLevels = true`. diff --git a/src/site/markdown/log4j-script.md b/src/site/markdown/log4j-script.md deleted file mode 100644 index 06e137ca51..0000000000 --- a/src/site/markdown/log4j-script.md +++ /dev/null @@ -1,121 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -There are two possibilities: -- Logging Adapter as complete replacement (preferred, but requires JVM start option) -- Bridge Handler, transfering JDK output to log4j, e.g. useful for webapps - -# Log4j JDK Logging Adapter - -The JDK Logging Adapter is a custom implementation of -[`java.util.logging.LogManager`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogManager.html) -that uses [Log4j](../log4j-core/index.html). This adapter can be used with either the Log4j API or -Log4j Core. When used with the API, there are a couple features of JUL that aren't supported. However, this -does allow any other Log4j Provider besides the Core provider to be used with JUL. - -## Requirements - -The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j Core. -For more information, see [Runtime Dependencies](../runtime-dependencies.html). - -## Usage - -To use the JDK Logging Adapter, you must set the system property `java.util.logging.manager` to -[`org.apache.logging.log4j.jul.LogManager`](apidocs/org/apache/logging/log4j/jul/LogManager.html) - -This must be done either through the command line (i.e., using the -`-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager` argument) or by using -`System.setProperty()` before any calls are made to `LogManager` or `Logger`. - -## Compatibility - -The use of a -[`java.util.logging.Filter`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html) -is supported on a per-[`Logger`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html) -basis. However, it is recommended to use the standard [Filters](../manual/filters.html) feature in -Log4j instead. - -The use of -[`java.util.logging.Handler`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html) -classes is _NOT_ supported. Custom Handlers should instead use an appropriate -[Appender](../manual/appenders.html) or code their own -[`Appender`](../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html) -plugin. - -Java logging levels are translated into Log4j logging levels dynamically. The following table lists the -conversions between a Java logging level and its equivalent Log4j level. Custom levels should be implemented -as an implementation of -[`LevelConverter`](apidocs/org/apache/logging/log4j/jul/LevelConverter.html), and the -Log4j property `log4j.jul.levelConverter` must be set to your custom class name. Using the default -`LevelConverter` implementation, custom logging levels are mapped to whatever the current level of -the `Logger` being logged to is using. - -### Default Level Conversions - -Java Level | Log4j Level ----------- | ----------- -[`OFF`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF) | `OFF` -[`SEVERE`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE) | `ERROR` -[`WARNING`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING) | `WARN` -[`INFO`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO) | `INFO` -[`CONFIG`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG) | [`CONFIG`](apidocs/org/apache/logging/log4j/jul/LevelTranslator.html#CONFIG) -[`FINE`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE) | `DEBUG` -[`FINER`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER) | `TRACE` -[`FINEST`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST) | [`FINEST`](apidocs/org/apache/logging/log4j/jul/LevelTranslator.html#FINEST) -[`ALL`](http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL) | `ALL` - - -# Log4j JDK Logging Bridge Handler - -The LogManager is not always useable because you have to set a JVM wide effective system -property - e.g. in web servers this is not possible if you are not the administrator. - -The [`Log4jBridgeHandler`](apidocs/org/apache/logging/log4j/jul/Log4jBridgeHandler.html) is an -alternative that can be declaratively used via `logging.properties`. - -It is less performant than the LogManager but still okay to use: the LogManager replaces the JDK -implementation, so your logging code (using JDK syntax) effectively directly uses log4j. -When using the BridgeHandler the original JDK implementation along with its configuration -(e.g. log levels) is still fully working but the log events are "written" via this handler to log4j -as if you would have called log4j.Logger.debug() etc.; it is like a FileHandler but instead of -writing to a file, it "writes" to log4j Loggers - thus there is some overhead compared to using -LogManager. - -## Usage - -The JUL configuration file `logging.properties` needs the line - -`handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler` - -and JUL logs go to log4j2. Additionally, you typically want to use to following: - -`org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true` - -In a webapp on Tomcat (and maybe other servers, too), you may simply create a -`WEB-INF/classes/logging.properties` file with above content. -The bridge and the log levels defined in this file are only valid for your webapp and -do *not* have any impact on the other webapps on the same Tomcat instance. - -Alternatively you may call `Log4jBridgeHandler.install()` inside your webapp's initialization code, -e.g. inside `ServletContextListener` or a `ServletFilter` static-class-init. or `contextInitialized()`. - -**Important:** Log levels of JDK should match the ones of log4j. You may do this manually or use the -automatic level propagation via `Log4jBridgeHandler.propagateLevels = true`. - -Please, read the [JavaDoc](apidocs/org/apache/logging/log4j/jul/Log4jBridgeHandler.html) for detailed -configuration and limitation information! diff --git a/src/site/markdown/log4j-spring-cloud-config-client.md b/src/site/markdown/log4j-spring-cloud-config-client.md deleted file mode 100644 index 4244f02cab..0000000000 --- a/src/site/markdown/log4j-spring-cloud-config-client.md +++ /dev/null @@ -1,135 +0,0 @@ -<!-- vim: set syn=markdown : --> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -# Log4j Spring Cloud Configuration - -This module allows logging configuration files to be dynamically updated when new versions are available in -Spring Cloud Configuration. - -## Overview - -Spring Boot applications initialize logging 3 times. -1. SpringApplication declares a Logger. This Logger will be initialized using Log4j's "normal" mechanisms. Thus -a system property named log4j2.configurationFile will be checked to see if a specific configuration file has been -provided, otherwise it will search for a configuration file on the classpath. The property may also be declare -in log4j2.component.properties. - -## Usage - -Log4j configuration files that specify a monitor interval of greater than zero will use polling to determine -whether the configuration has been updated. If the monitor interval is zero then Log4j will listen for notifications -from Spring Cloud Config and will check for configuration changes each time an event is generated. If the -monitor interval is less than zero Log4j will not check for changes to the logging configuration. - -When referencing a configuration located in Spring Cloud Config the configuration should be referenced similar to - -``` -log4j.configurationFile=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2.xml -``` - -Log4j also supports Composite Configurations. The standard way to do that is to concatentate the paths to the files in -a comma separated string. Unfortunately, Spring validates the URL being provided and commas are not allowed. -Therefore, additional configurations must be supplied as "override" query parametes. - -``` -log4j.configurationFile=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2.xml -?override=http://host.docker.internal:8888/ConfigService/sampleapp/default/master/log4j2-sampleapp.xml -``` -Note that the location within the directory structure and how configuration files are located is completely -dependent on the searchPaths setting in the Spring Cloud Config server. - -When running in a docker container host.docker.internal may be used as the domain name to access an application -running on the same hose outside of the docker container. Note that in accordance with Spring Cloud Config -practices but the application, profile, and label should be specified in the url. - -The Spring Cloud Config support also allows connections using TLS and/or basic authentication. When using basic -authentication the userid and password may be specified as system properties, log4j2.component.properties or Spring -Boot's bootstrap.yml. The table below shows the alternate names that may be used to specify the properties. Any of -the alternatives may be used in any configuration location. - -| Property | Alias | Spring-like alias | Purpose | -|----------|---------|---------|---------| -| log4j2.configurationUserName | log4j2.config.username | logging.auth.username | User name for basic authentication | -| log4j2.configurationPassword | log4j2.config.password | logging.auth.password | Password for basic authentication | -| log4j2.authorizationProvider | log4j2.config.authorizationProvider | logging.auth.authorizationProvider | Class used to create HTTP Authorization header | - -``` -log4j2.configurationUserName=guest -log4j2.configurationPassword=guest -``` -As noted above, Log4j supports accessing logging configuration from bootstrap.yml. As an example, to configure reading -from a Spring Cloud Configuration service using basic authoriztion you can do: -``` -spring: - application: - name: myApp - cloud: - config: - uri: https://spring-configuration-server.mycorp.com - username: appuser - password: changeme - -logging: - config: classpath:log4j2.xml - label: ${spring.cloud.config.label} - ---- -spring: - profiles: dev - -logging: - config: https://spring-configuration-server.mycorp.com/myApp/default/${logging.label}/log4j2-dev.xml - auth: - username: appuser - password: changeme -``` - -Note that Log4j currently does not directly support encrypting the password. However, Log4j does use Spring's -standard APIs to access properties in the Spring configuration so any customizations made to Spring's property -handling would apply to the properties Log4j uses as well. - -If more extensive authentication is required an ```AuthorizationProvider``` can be implemented and the fully -qualified class name in -the ```log4j2.authorizationProvider``` system property, in log4j2.component.properties or in Spring's bootstrap.yml -using either the ```log4j2.authorizationProvider``` key or with the key ```logging.auth.authorizationProvider```. - -TLS can be enabled by adding the following system properties or defining them in log4j2.component.properties - -| Property | Optional or Default Value | Description | -| ------------- |-------|:-------------| -| log4j2.trustStoreLocation | Optional | The location of the trust store. If not provided the default trust store will be used.| -| log4j2.trustStorePassword | Optional | Password needed to access the trust store. | -| log4j2.trustStorePasswordFile | Optional | The location of a file that contains the password for the trust store. | -| log4j2.trustStorePasswordEnvironmentVariable | Optional | The name of the environment variable that contains the trust store password. | -| log4j2.trustStoreKeyStoreType | Required if keystore location provided | The type of key store. | -| log4j2.trustStoreKeyManagerFactoryAlgorithm | Optional | Java cryptographic algorithm. | -| log4j2.keyStoreLocation | Optional | The location of the key store. If not provided the default key store will be used.| -| log4j2.keyStorePassword | Optional | Password needed to access the key store. | -| log4j2.keyStorePasswordFile | Optional | The location of a file that contains the password for the key store. | -| log4j2.keyStorePasswordEnvironmentVariable | Optional | The name of the environment variable that contains the key store password.| -| log4j2.keyStoreType | Required if trust store location provided. | The type of key store. | -| log4j2.keyStoreKeyManagerFactoryAlgorithm | Optional | Java cryptographic algorithm. | -| log4j2.sslVerifyHostName | false | true or false | - - - -## Requirements - -The Log4j 2 Spring Cloud Configuration integration has a dependency on Log4j 2 API, Log4j 2 Core, and -Spring Cloud Configuration versions 2.0.3.RELEASE or 2.1.1.RELEASE or later versions it either release series. -For more information, see [Runtime Dependencies](runtime-dependencies.html).
