You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@logging.apache.org by "vy (via GitHub)" <gi...@apache.org> on 2024/04/30 08:36:19 UTC
[PR] Revamp the F.A.Q. page (#2506) (logging-log4j2)
vy opened a new pull request, #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549
Fixes #2506.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy merged PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584427357
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
Review Comment:
Right. Fixed in cd5af0422cc43c726a230ac2d3fbe114997ac984.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584368021
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
Review Comment:
Removed these two sections, since their content is extensively covered in `installation.adoc`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584472799
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
Review Comment:
I just noticed I had already added _"document `SimpleLogger`"_ to #2535. :sweat_smile:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584430262
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
Review Comment:
Fixed in 16a4e08a770abf60bf8951b5e32f11a31f48ca61.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584370858
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
Review Comment:
@ppkarwasz, there are several sections here dealing with programmatic configuration. I need your help to wire these to the configuration pages you are working on.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584397221
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
Review Comment:
Users should rather use `Configurator`.
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
Review Comment:
```suggestion
`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
```
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
Review Comment:
IMHO, `Configurator` **is** public API.
I would remove all the `(LoggerContext) LogManager.getContext(false)` tricks from our documentation, since they are a source of `ClassCastException`s, whereas `Configurator` logs the errors instead of throwing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584392817
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
Review Comment:
For `SimpleLogger` we probably need to amend the Installation page: there is no simple way to disable the warning/error if a user wants to use `SimpleLogger`.
We might consider creating a `log4j-simple` artifact with a single class: a `Provider` for `SimpleLogger`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584424533
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
Review Comment:
Sure, add it to the task.
The warning message is here:
https://github.com/apache/logging-log4j2/blob/be8843567858a4cd926e10f67652eb04b2f5d749/log4j-api/src/main/java/org/apache/logging/log4j/util/ProviderUtil.java#L240-L257
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
+Your code may break with any minor release.
[#config_sep_appender_level]
== How do I send log messages with different levels to different appenders?
+
You don't need to declare separate loggers to achieve this.
You can set the logging level on the `AppenderRef` element.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+ <appenders>
<File name="file" fileName="app.log">
- <PatternLayout>
- <Pattern>%d %p %c{1.} [%t] %m %ex%n</Pattern>
- </PatternLayout>
+ <PatternLayout pattern="%d %p %c{1.} [%t] %m %ex%n"/>
</File>
- <Console name="STDOUT" target="SYSTEM_OUT">
+ <Console name="stdout" target="SYSTEM_OUT">
<PatternLayout pattern="%m%n"/>
</Console>
- </Appenders>
- <Loggers>
- <Root level="trace">
+ </appenders>
+ <loggers>
+ <root level="WARN">
<AppenderRef ref="file" level="DEBUG"/>
- <AppenderRef ref="STDOUT" level="INFO"/>
- </Root>
- </Loggers>
+ <AppenderRef ref="stdout" level="INFO"/>
+ </root>
+ </loggers>
</Configuration>
----
[#troubleshooting]
== How do I debug my configuration?
-First, make sure you have <<which_jars,the right jar files>> on your classpath.
-You need at least log4j-api and log4j-core.
-
-Next, check the name of your configuration file.
-By default, log4j2 will look for a configuration file named `log4j2.xml` on the classpath.
-Note the "2" in the file name!
-(See the xref:manual/configuration.adoc#AutomaticConfiguration[configuration manual page] for more details.)
-
-*From log4j-2.9 onward*
+. Make sure you have xref:manual/installation.adoc[the right JAR files] on your classpath.
-From log4j-2.9 onward, log4j2 will print all internal logging to the console if system property `log4j2.debug` is either defined empty or its value equals to `true` (ignoring case).
+. Check the name of your configuration file.
+By default, Log4j looks for a configuration file named `log4j2.xml` on the classpath.
+Note the `2` in the file name!
+(See xref:manual/configuration.adoc[the Configuration page] for more details.)
-*Prior to log4j-2.9*
+. Increase the logging verbosity of the internal status logger: +
+`-Dlog4j2.StatusLogger.level=TRACE`
Review Comment:
```suggestion
`-Dlog4j2.statusLoggerLevel=TRACE`
```
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
Review Comment:
I haven't gotten to that part yet, you can add some bogus link and I'll replace it later.
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
+Your code may break with any minor release.
[#config_sep_appender_level]
== How do I send log messages with different levels to different appenders?
+
You don't need to declare separate loggers to achieve this.
You can set the logging level on the `AppenderRef` element.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+ <appenders>
<File name="file" fileName="app.log">
- <PatternLayout>
- <Pattern>%d %p %c{1.} [%t] %m %ex%n</Pattern>
- </PatternLayout>
+ <PatternLayout pattern="%d %p %c{1.} [%t] %m %ex%n"/>
</File>
- <Console name="STDOUT" target="SYSTEM_OUT">
+ <Console name="stdout" target="SYSTEM_OUT">
<PatternLayout pattern="%m%n"/>
</Console>
- </Appenders>
- <Loggers>
- <Root level="trace">
+ </appenders>
+ <loggers>
+ <root level="WARN">
<AppenderRef ref="file" level="DEBUG"/>
- <AppenderRef ref="STDOUT" level="INFO"/>
- </Root>
- </Loggers>
+ <AppenderRef ref="stdout" level="INFO"/>
+ </root>
+ </loggers>
</Configuration>
----
[#troubleshooting]
== How do I debug my configuration?
-First, make sure you have <<which_jars,the right jar files>> on your classpath.
-You need at least log4j-api and log4j-core.
-
-Next, check the name of your configuration file.
-By default, log4j2 will look for a configuration file named `log4j2.xml` on the classpath.
-Note the "2" in the file name!
-(See the xref:manual/configuration.adoc#AutomaticConfiguration[configuration manual page] for more details.)
-
-*From log4j-2.9 onward*
+. Make sure you have xref:manual/installation.adoc[the right JAR files] on your classpath.
-From log4j-2.9 onward, log4j2 will print all internal logging to the console if system property `log4j2.debug` is either defined empty or its value equals to `true` (ignoring case).
+. Check the name of your configuration file.
+By default, Log4j looks for a configuration file named `log4j2.xml` on the classpath.
+Note the `2` in the file name!
+(See xref:manual/configuration.adoc[the Configuration page] for more details.)
-*Prior to log4j-2.9*
+. Increase the logging verbosity of the internal status logger: +
+`-Dlog4j2.StatusLogger.level=TRACE`
-Prior to log4j-2.9, there are two places where internal logging can be controlled:
-
-If the configuration file is found correctly, log4j2 internal status logging can be controlled by setting `<Configuration status="trace">` in the configuration file.
-This will display detailed log4j2-internal log statements on the console about what happens during the configuration process.
-This may be useful to trouble-shoot configuration issues.
-By default the status logger level is WARN, so you only see notifications when there is a problem.
-
-If the configuration file is not found correctly, you can still enable log4j2 internal status logging by setting system property `-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE`.
+. Enable all internal debug logging: `-Dlog4j2.debug`.
+This disables level-based status logger filtering and effectively allows all status logs.
[#separate_log_files]
== How do I dynamically write to separate log files?
-Look at the http://logging.apache.org/log4j/2.x/manual/appenders.html#RoutingAppender[RoutingAppender].
-You can define multiple routes in the configuration, and put values in the `ThreadContext` map that determine which log file subsequent events in this thread get logged to.
-
-You can use the `ThreadContext` map value to determine the log file name.
-
-[source,xml]
-----
-<Routing name="Routing">
- <Routes pattern="$${ctx:ROUTINGKEY}">
-
- <!-- This route is chosen if ThreadContext has value 'special' for key ROUTINGKEY. -->
- <Route key="special">
- <RollingFile name="Rolling-${ctx:ROUTINGKEY}" fileName="logs/special-${ctx:ROUTINGKEY}.log"
- filePattern="./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-special-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
-
- <!-- This route is chosen if ThreadContext has no value for key ROUTINGKEY. -->
- <Route key="$${ctx:ROUTINGKEY}">
- <RollingFile name="Rolling-default" fileName="logs/default.log"
- filePattern="./logs/${date:yyyy-MM}/default-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
-
- <!-- This route is chosen if ThreadContext has a value for ROUTINGKEY
- (other than the value 'special' which had its own route above).
- The value dynamically determines the name of the log file. -->
- <Route>
- <RollingFile name="Rolling-${ctx:ROUTINGKEY}" fileName="logs/other-${ctx:ROUTINGKEY}.log"
- filePattern="./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-other-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
- </Routes>
-</Routing>
-----
-
-[#reconfig_level_from_code]
-== How do I set a logger's level programmatically?
-
-You can set a logger's level with the class link:javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core.
-Be aware that the `Configurator` class is not part of the public API.
-
-[source,java]
-----
-// org.apache.logging.log4j.core.config.Configurator;
-
-Configurator.setLevel("com.example.Foo", Level.DEBUG);
-
-// You can also set the root logger:
-Configurator.setRootLevel(Level.DEBUG);
-----
-
-[#retention]
-== How do I set my log archive retention policy?
-How do I delete old log archives?
-
-The `DefaultRolloverStrategy` of the Rolling File appender (and Rolling Random Access File appender) supports a xref:manual/appenders.adoc#CustomDeleteOnRollover[Delete] element.
-
-Starting at a specified base directory, you can delete all files for which some condition holds true, for example all files that match a given file name pattern and are older than some number of days.
-More complex conditions are possible, and if the built-in conditions are not sufficient, users can provide custom conditions by creating xref:manual/appenders.adoc#DeletePathCondition[plugin conditions] or by writing a xref:manual/appenders.adoc#ScriptCondition[script condition].
+You can use xref:manual/appenders.adoc#RoutingAppender[the routing appender] to evaluate a log message and forward it to a particular appender.
[#api-tradeoffs]
-== What are the trade-offs of using the Log4j 2 API versus the SLF4J API?
+== What are the trade-offs of using Log4j API versus SLF4J?
-The Log4j 2 API and SLF4J have a lot in common.
+Log4j API and SLF4J have a lot in common.
They both share the objective of cleanly separating the logging API from the implementation.
-We believe that the Log4j 2 API can help make your application more performant while offering more functionality and more flexibility.
+We believe that Log4j API can help make your application more performant while offering more functionality and more flexibility.
-There may be a concern that using the Log4j 2 API will tightly couple your application to Log4j 2.
-This is not the case: applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant library as their logging implementation with the log4j-to-slf4j adapter.
-See the <<which_jars_log4j-to-slf4j,which jars>> FAQ entry for details.
+There may be a concern that using the Log4j API will tightly couple your application to Log4j.
+This is not the case: applications coded to Log4j API always have the option to use any SLF4J-compliant logging implementation with the `log4j-to-slf4j` bridge.
+See xref:manual/installation.adoc[the Installation page] for details.
-There are several advantages to using the Log4j 2 API:
+There are several advantages to using Log4j API:
-* SLF4J forces your application to log Strings.
-The Log4j 2 API supports logging any CharSequence if you want to log text, but also supports logging any Object as is.
-It is the responsibility of the logging _implementation_ to handle this object, and we consider it a design mistake to limit applications to logging Strings.
-* The Log4j 2 API offers support for logging xref:manual/messages.adoc[Message objects].
+* SLF4J forces your application to log ``String``s.
+Log4j API supports logging any `CharSequence` if you want to log text, but also supports logging any `Object` as is.
+It is the responsibility of the logging _implementation_ to handle this object, and we consider it a design mistake to limit applications to logging ``String``s.
+* Log4j API offers support for logging xref:manual/messages.adoc[`Message` objects].
Messages allow support for interesting and complex constructs to be passed through the logging system and be efficiently manipulated.
-Users are free to create their own Message types and write custom Layouts, Filters and Lookups to manipulate them.
-* The Log4j 2 API has support for Java 8 xref:manual/api.adoc#LambdaSupport[lambda expressions].
-* The Log4j 2 API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating vararg arrays and avoids creating Strings when logging CharSequence objects.
+Users are free to create their own message types and write custom layouts, filters and lookups to manipulate them.
+* Log4j API supports xref:manual/api.adoc#LambdaSupport[lambda expressions] both in its plain and fluent API.
+* Log4j API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating `vararg` arrays and avoids creating ``String``s when logging ``CharSequence``s.
[#gc-free-slf4j]
-== Is Log4j 2 still garbage-free when I use the SLF4J API?
+== Is Log4j still garbage-free when I use SLF4J?
-Yes, the log4j-slf4j-impl binding (together with log4j-core) implements the `org.slf4j.Logger` methods to be GC-free.
+If you use SLF4J as your logging API and Log4j Core as the logging implementation, yes.
+The `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges (together with `log4j-core`) implement the `org.slf4j.Logger` methods to be garbage-free.
However, bear in mind that there are some limitations:
-The SLF4J API only offers up to two parameters for a parameterized message.
-More than that uses varargs which creates a temporary object for the parameter array.
-The Log4j 2.6 API has methods for up to ten unrolled parameters.
+* The SLF4J API only offers up to two parameters for a parameterized message.
+More than that uses ``vararg``s, which create a temporary object for the parameter array.
+In contrast, Log4j API has methods for up to ten unrolled parameters.
-Another consideration is that the SLF4J API forces your application to log Strings.
-Log4j 2 API lets you log any java.lang.CharSequence, and even any Objects.
-Log4j can log any Object that implements `java.lang.CharSequence` or `org.apache.logging.log4j.util.StringBuilderFormattable` without creating garbage.
+* SLF4J forces your application to log ``String``s.
+Log4j API lets you log any `CharSequence` or `Object`.
+Log4j Core can log any `Object` that implements `CharSequence` or `org.apache.logging.log4j.util.StringBuilderFormattable` without creating garbage.
-The https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log-org.slf4j.Marker-java.lang.String-int-java.lang.String-java.lang.Object:A-java.lang.Throwable-[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the log4j-slf4j-impl binding.
+* The https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log(org.slf4j.Marker,java.lang.String,int,java.lang.String,java.lang.Object%5B%5D,java.lang.Throwable)[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges.
It creates a new message object for each call.
[#gc-free-domain-object]
== How do I log my domain object without creating garbage?
-One option is to let the domain object implement java.lang.CharSequence.
+One option is to let the domain object implement `CharSequence`.
However, for many domain objects it may not be trivial to implement this without allocating temporary objects.
An alternative is to implement the `org.apache.logging.log4j.util.StringBuilderFormattable` interface.
-If an object is logged that implements this interface, its `formatTo` method is called instead of `toString()`.
-
-[source,java]
-----
-package org.apache.logging.log4j.util;
-public interface StringBuilderFormattable {
- /**
- * Writes a text representation of this object into the specified {@code StringBuilder},
- * ideally without allocating temporary objects.
- *
- * @param buffer the StringBuilder to write into
- */
- void formatTo(StringBuilder buffer);
-}
-----
+If an object is logged that implements this interface, its `formatTo(StringBuilder)` method is called instead of `toString()`.
[#logger-wrapper]
-== How do I create a custom logger wrapper that shows the correct class, method and line number?
+== How do I create a custom logger wrapper that shows the correct class, method, and line number?
Log4j remembers the fully qualified class name (FQCN) of the logger and uses this to walk the stack trace for every log event when configured to print location.
-(Be aware that logging with location is slow and may impact the performance of your application.)
+
+[WARNING]
+====
+Be aware that logging with location is slow and may impact the performance of your application.
+====
The problem with custom logger wrappers is that they have a different FQCN than the actual logger, so Log4j can't find the place where your custom logger was called.
The solution is to provide the correct FQCN.
The easiest way to do this is to let Log4j generate the logger wrapper for you.
Log4j comes with a Logger wrapper generator tool.
-This tool was originally meant to support custom log levels and is documented https://logging.apache.org/log4j/2.x/manual/customloglevels.html#CustomLoggers[here].
-
+This tool was originally meant to support custom log levels and is documented xref:manual/customloglevels.adoc#CustomLoggers[here].
Review Comment:
The tool is currently here: apache/logging-log4j-transform#92
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584375958
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
Review Comment:
@ppkarwasz, I am really confused by our approach here. We explain users how they can use Log4j Core to do `X`, where we sort of recognize `X` as a valid use case, yet warn them that they will be using an internal API (contrast this to Java's `Unsafe`), which implies, they better should not do it. I have a feeling that we either should not officially document its usage, or remove the warning.
(There is a similar case for the `org.apache.logging.log4j.core.LoggerContext` shared a little bit above.)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584415137
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
Review Comment:
Agreed that `installation.adoc` needs to be updated to adopt `SimpleLogger`. Shall we add this as a task to #2535?
> there is no simple way to disable the warning/error if a user wants to use `SimpleLogger`.
Is it so? I searched for the `Unable to locate a logging implementation` message and it was gone long ago. Am I mistaken?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584521408
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
Review Comment:
Currently programmatic configuration is [documented here](https://logging.apache.org/log4j/2.x/manual/customconfig#programmatic-configuration).
In order to provide a maximum compatibility with existing links, I'll also use a `#programmatic-configuration` in the new Configuration page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the F.A.Q. page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2549:
URL: https://github.com/apache/logging-log4j2/pull/2549#discussion_r1584477935
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -17,404 +17,196 @@ Licensed to the Apache Software Foundation (ASF) under one or more
= F.A.Q.
-[#missing_core]
-== I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?
-
-You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath.
-(Also, it looks like you are using an old version of Log4j 2.
-You may want to upgrade.)
-
-[#which_jars]
-== Which JAR files do I need?
-
-You need at least the log4j-api-2.x and the log4j-core-2.x jar files.
-
-The other jars are necessary if your application calls the API of another logging framework and you want to route logging calls to the Log4j 2 implementation.
-
-image:whichjar-2.x.png[Diagram showing which JARs correspond to which systems]
-
-[#which_jars_log4j-to-slf4j] You can use the log4j-to-slf4j adapter jar when your application calls the Log4j 2 API and you want to route logging calls to a SLF4J implementation.
-
-image:whichjar-slf4j-2.x.png[Diagram showing the dependency flow to use Log4j 2 API with SLF4J]
-
-Some of the Log4j components have features with optional dependencies.
-See xref:runtime-dependencies.adoc[the runtime dependencies page] for more information.
-
-[#exclusions]
-== How do I exclude conflicting dependencies?
-
-There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones.
-The following table shows for each Log4j dependency on the left (implicit groupId of `org.apache.logging.log4j`), the following dependencies on the right can be safely excluded (given in the format `groupId:artifactId`).
-
-[%header,cols="1m,3m"]
-|===
-|Log4j dependency
-|Dependencies to exclude
-
-|log4j-1.2-api
-|log4j:log4j +
-org.slf4j:log4j-over-slf4j
-
-|log4j-core
-|log4j:log4j +
-ch.qos.logback:logback-core +
-org.apache.logging.log4j:log4j-to-slf4j
-
-|log4j-jcl
-|org.slf4j:jcl-over-slf4j
-
-|log4j-jul
-|org.slf4j:jul-to-slf4j
-
-|log4j-slf4j-impl
-|org.apache.logging.log4j:log4j-to-slf4j +
-ch.qos.logback:logback-core
-|===
-
-Using Apache Maven, dependencies can be globally excluded in your project like so:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.17</version>
- <scope>provided</scope>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be explicitly excluded for specific dependencies as well.
-For example, to use a project with Log4j 2 instead of Log4j 1.x:
-
-[source,xml]
-----
-<dependencies>
- <dependency>
- <groupId>com.example</groupId>
- <artifactId>example-project</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-1.2-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
-</dependencies>
-----
-
-Dependencies can be globally excluded in Gradle like so:
-
-[source]
-----
-configurations {
- all*.exclude group: 'log4j', module: 'log4j'
-}
-----
-
-The equivalent Gradle config for the above Maven exclusion would look like:
-
-[source]
-----
-dependencies {
- compile('com.example:example-project:1.0') {
- exclude group: 'log4j', module: 'log4j'
- exclude group: 'org.slf4j', module: 'slf4j-log4j12'
- }
- compile('org.apache.logging.log4j:log4j-core:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-slf4j-impl:${Log4jReleaseVersion}')
- compile('org.apache.logging.log4j:log4j-1.2-api:${Log4jReleaseVersion}')
-}
-----
+This page compiles a list of frequently asked questions.
+If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
[#config_location]
== How do I specify the configuration file location?
-By default, Log4j looks for a configuration file named *log4j2.xml* (not log4j.xml) in the classpath.
+By default, Log4j looks for a configuration file named `log4j2.xml`, `log4j2.properties`, etc. in the classpath.
+
+[WARNING]
+====
+Log4j 1 (which has reached its end-of-life in 2015!) uses `log4j.xml`.
+Log4j 2 and onwards use `log4j2.xml`.
+====
-You can also specify the full path of the configuration file with this system property: `-Dlog4j.configurationFile=path/to/log4j2.xml`
+You can also specify the full path of the configuration file using a system property: +
+`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
Web applications can specify the Log4j configuration file location with a servlet context parameter.
-See http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams[this section] of the Using Log4j 2 in Web Applications manual page.
+See xref:manual/webapp.adoc#ContextParams[the related page on web applications].
+
+Refer to xref:manual/configuration.adoc[the Configuration page] for further details.
[#config_from_code]
-== How do I configure log4j2 in code without a configuration file?
+== How do I configure Log4j programmatically?
-Starting with version 2.4, Log4j 2 provides an xref:manual/customconfig.adoc[API for programmatic configuration] The new link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[`ConfigurationBuilder` API] allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.
+Starting with version `2.4`, Log4j provides xref:manual/customconfig.adoc[an API for programmatic configuration].
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html[The new `ConfigurationBuilder` API] allows you to create ``Configuration``s in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like loggers and appenders.
[#reconfig_from_code]
-== How do I reconfigure log4j2 in code with a specific configuration file?
+== How do I reconfigure Log4j programmatically?
-See the below example.
-Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release.
+You can reconfigure Log4j programmatically as follows:
[source,java]
----
-// import org.apache.logging.log4j.core.LoggerContext;
-
-LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false);
-File file = new File("path/to/a/different/log4j2.xml");
+LoggerContext context = (org.apache.logging.log4j.core.LoggerContext) LogManager.getContext(false); // <1>
+File file = new File("/path/to/a/different/log4j2.xml");
-// this will force a reconfiguration
+// This will force a reconfiguration
context.setConfigLocation(file.toURI());
----
+<1> Be aware that this `LoggerContext` class is not part of the public API.
+Your code may break with any minor release.
[#shutdown]
-== How do I shut down log4j2 in code?
+== How do I shut down Log4j programmatically?
Normally there is no need to do this manually.
-Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property `log4j.shutdownHookEnabled` is set to `false`).
-Web applications should include the log4j-web module in their classpath which disables the shutdown hook but instead cleans up log4j resources when the web application is stopped.
+Each `LoggerContext` registers a shutdown hook that takes care of releasing resources when the JVM exits, unless the `log4j.shutdownHookEnabled` system property is set to `false`.
+Likewise, xref:manual/webapp.adoc[Web applications] replace the shutdown hook with their own resource management mechanisms.
+That is, they clean up necessary resources when the web application is stopped.
+However, if you need to manually shut down Log4j, you can use one of the `shutdown()` methods of link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#shutdown()[`LogManager`].
-However, if you need to manually shut down Log4j, you can do so as in the below example.
-Note that there is an optional parameter for specifying which `LoggerContext` to shut down.
+[#reconfig_level_from_code]
+== How do I set a logger level programmatically?
+
+You can set the level of a logger using link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core:
[source,java]
----
-import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.config.Configurator; // <1>
-// ...
+// Set the level of particular logger associated with a class
+Configurator.setLevel("com.example.Foo", Level.DEBUG);
-LogManager.shutdown();
+// Set the level of the root logger
+Configurator.setRootLevel(Level.DEBUG);
----
+<1> Be aware that `Configurator` is not part of the public API.
+Your code may break with any minor release.
[#config_sep_appender_level]
== How do I send log messages with different levels to different appenders?
+
You don't need to declare separate loggers to achieve this.
You can set the logging level on the `AppenderRef` element.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+ <appenders>
<File name="file" fileName="app.log">
- <PatternLayout>
- <Pattern>%d %p %c{1.} [%t] %m %ex%n</Pattern>
- </PatternLayout>
+ <PatternLayout pattern="%d %p %c{1.} [%t] %m %ex%n"/>
</File>
- <Console name="STDOUT" target="SYSTEM_OUT">
+ <Console name="stdout" target="SYSTEM_OUT">
<PatternLayout pattern="%m%n"/>
</Console>
- </Appenders>
- <Loggers>
- <Root level="trace">
+ </appenders>
+ <loggers>
+ <root level="WARN">
<AppenderRef ref="file" level="DEBUG"/>
- <AppenderRef ref="STDOUT" level="INFO"/>
- </Root>
- </Loggers>
+ <AppenderRef ref="stdout" level="INFO"/>
+ </root>
+ </loggers>
</Configuration>
----
[#troubleshooting]
== How do I debug my configuration?
-First, make sure you have <<which_jars,the right jar files>> on your classpath.
-You need at least log4j-api and log4j-core.
-
-Next, check the name of your configuration file.
-By default, log4j2 will look for a configuration file named `log4j2.xml` on the classpath.
-Note the "2" in the file name!
-(See the xref:manual/configuration.adoc#AutomaticConfiguration[configuration manual page] for more details.)
-
-*From log4j-2.9 onward*
+. Make sure you have xref:manual/installation.adoc[the right JAR files] on your classpath.
-From log4j-2.9 onward, log4j2 will print all internal logging to the console if system property `log4j2.debug` is either defined empty or its value equals to `true` (ignoring case).
+. Check the name of your configuration file.
+By default, Log4j looks for a configuration file named `log4j2.xml` on the classpath.
+Note the `2` in the file name!
+(See xref:manual/configuration.adoc[the Configuration page] for more details.)
-*Prior to log4j-2.9*
+. Increase the logging verbosity of the internal status logger: +
+`-Dlog4j2.StatusLogger.level=TRACE`
-Prior to log4j-2.9, there are two places where internal logging can be controlled:
-
-If the configuration file is found correctly, log4j2 internal status logging can be controlled by setting `<Configuration status="trace">` in the configuration file.
-This will display detailed log4j2-internal log statements on the console about what happens during the configuration process.
-This may be useful to trouble-shoot configuration issues.
-By default the status logger level is WARN, so you only see notifications when there is a problem.
-
-If the configuration file is not found correctly, you can still enable log4j2 internal status logging by setting system property `-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE`.
+. Enable all internal debug logging: `-Dlog4j2.debug`.
+This disables level-based status logger filtering and effectively allows all status logs.
[#separate_log_files]
== How do I dynamically write to separate log files?
-Look at the http://logging.apache.org/log4j/2.x/manual/appenders.html#RoutingAppender[RoutingAppender].
-You can define multiple routes in the configuration, and put values in the `ThreadContext` map that determine which log file subsequent events in this thread get logged to.
-
-You can use the `ThreadContext` map value to determine the log file name.
-
-[source,xml]
-----
-<Routing name="Routing">
- <Routes pattern="$${ctx:ROUTINGKEY}">
-
- <!-- This route is chosen if ThreadContext has value 'special' for key ROUTINGKEY. -->
- <Route key="special">
- <RollingFile name="Rolling-${ctx:ROUTINGKEY}" fileName="logs/special-${ctx:ROUTINGKEY}.log"
- filePattern="./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-special-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
-
- <!-- This route is chosen if ThreadContext has no value for key ROUTINGKEY. -->
- <Route key="$${ctx:ROUTINGKEY}">
- <RollingFile name="Rolling-default" fileName="logs/default.log"
- filePattern="./logs/${date:yyyy-MM}/default-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
-
- <!-- This route is chosen if ThreadContext has a value for ROUTINGKEY
- (other than the value 'special' which had its own route above).
- The value dynamically determines the name of the log file. -->
- <Route>
- <RollingFile name="Rolling-${ctx:ROUTINGKEY}" fileName="logs/other-${ctx:ROUTINGKEY}.log"
- filePattern="./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-other-%d{yyyy-MM-dd}-%i.log.gz">
- <PatternLayout>
- <pattern>%d{ISO8601} [%t] %p %c{3} - %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true" />
- <SizeBasedTriggeringPolicy size="10 MB" />
- </Policies>
- </RollingFile>
- </Route>
- </Routes>
-</Routing>
-----
-
-[#reconfig_level_from_code]
-== How do I set a logger's level programmatically?
-
-You can set a logger's level with the class link:javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html[`Configurator`] from Log4j Core.
-Be aware that the `Configurator` class is not part of the public API.
-
-[source,java]
-----
-// org.apache.logging.log4j.core.config.Configurator;
-
-Configurator.setLevel("com.example.Foo", Level.DEBUG);
-
-// You can also set the root logger:
-Configurator.setRootLevel(Level.DEBUG);
-----
-
-[#retention]
-== How do I set my log archive retention policy?
-How do I delete old log archives?
-
-The `DefaultRolloverStrategy` of the Rolling File appender (and Rolling Random Access File appender) supports a xref:manual/appenders.adoc#CustomDeleteOnRollover[Delete] element.
-
-Starting at a specified base directory, you can delete all files for which some condition holds true, for example all files that match a given file name pattern and are older than some number of days.
-More complex conditions are possible, and if the built-in conditions are not sufficient, users can provide custom conditions by creating xref:manual/appenders.adoc#DeletePathCondition[plugin conditions] or by writing a xref:manual/appenders.adoc#ScriptCondition[script condition].
+You can use xref:manual/appenders.adoc#RoutingAppender[the routing appender] to evaluate a log message and forward it to a particular appender.
[#api-tradeoffs]
-== What are the trade-offs of using the Log4j 2 API versus the SLF4J API?
+== What are the trade-offs of using Log4j API versus SLF4J?
-The Log4j 2 API and SLF4J have a lot in common.
+Log4j API and SLF4J have a lot in common.
They both share the objective of cleanly separating the logging API from the implementation.
-We believe that the Log4j 2 API can help make your application more performant while offering more functionality and more flexibility.
+We believe that Log4j API can help make your application more performant while offering more functionality and more flexibility.
-There may be a concern that using the Log4j 2 API will tightly couple your application to Log4j 2.
-This is not the case: applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant library as their logging implementation with the log4j-to-slf4j adapter.
-See the <<which_jars_log4j-to-slf4j,which jars>> FAQ entry for details.
+There may be a concern that using the Log4j API will tightly couple your application to Log4j.
+This is not the case: applications coded to Log4j API always have the option to use any SLF4J-compliant logging implementation with the `log4j-to-slf4j` bridge.
+See xref:manual/installation.adoc[the Installation page] for details.
-There are several advantages to using the Log4j 2 API:
+There are several advantages to using Log4j API:
-* SLF4J forces your application to log Strings.
-The Log4j 2 API supports logging any CharSequence if you want to log text, but also supports logging any Object as is.
-It is the responsibility of the logging _implementation_ to handle this object, and we consider it a design mistake to limit applications to logging Strings.
-* The Log4j 2 API offers support for logging xref:manual/messages.adoc[Message objects].
+* SLF4J forces your application to log ``String``s.
+Log4j API supports logging any `CharSequence` if you want to log text, but also supports logging any `Object` as is.
+It is the responsibility of the logging _implementation_ to handle this object, and we consider it a design mistake to limit applications to logging ``String``s.
+* Log4j API offers support for logging xref:manual/messages.adoc[`Message` objects].
Messages allow support for interesting and complex constructs to be passed through the logging system and be efficiently manipulated.
-Users are free to create their own Message types and write custom Layouts, Filters and Lookups to manipulate them.
-* The Log4j 2 API has support for Java 8 xref:manual/api.adoc#LambdaSupport[lambda expressions].
-* The Log4j 2 API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating vararg arrays and avoids creating Strings when logging CharSequence objects.
+Users are free to create their own message types and write custom layouts, filters and lookups to manipulate them.
+* Log4j API supports xref:manual/api.adoc#LambdaSupport[lambda expressions] both in its plain and fluent API.
+* Log4j API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating `vararg` arrays and avoids creating ``String``s when logging ``CharSequence``s.
[#gc-free-slf4j]
-== Is Log4j 2 still garbage-free when I use the SLF4J API?
+== Is Log4j still garbage-free when I use SLF4J?
-Yes, the log4j-slf4j-impl binding (together with log4j-core) implements the `org.slf4j.Logger` methods to be GC-free.
+If you use SLF4J as your logging API and Log4j Core as the logging implementation, yes.
+The `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges (together with `log4j-core`) implement the `org.slf4j.Logger` methods to be garbage-free.
However, bear in mind that there are some limitations:
-The SLF4J API only offers up to two parameters for a parameterized message.
-More than that uses varargs which creates a temporary object for the parameter array.
-The Log4j 2.6 API has methods for up to ten unrolled parameters.
+* The SLF4J API only offers up to two parameters for a parameterized message.
+More than that uses ``vararg``s, which create a temporary object for the parameter array.
+In contrast, Log4j API has methods for up to ten unrolled parameters.
-Another consideration is that the SLF4J API forces your application to log Strings.
-Log4j 2 API lets you log any java.lang.CharSequence, and even any Objects.
-Log4j can log any Object that implements `java.lang.CharSequence` or `org.apache.logging.log4j.util.StringBuilderFormattable` without creating garbage.
+* SLF4J forces your application to log ``String``s.
+Log4j API lets you log any `CharSequence` or `Object`.
+Log4j Core can log any `Object` that implements `CharSequence` or `org.apache.logging.log4j.util.StringBuilderFormattable` without creating garbage.
-The https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log-org.slf4j.Marker-java.lang.String-int-java.lang.String-java.lang.Object:A-java.lang.Throwable-[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the log4j-slf4j-impl binding.
+* The https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log(org.slf4j.Marker,java.lang.String,int,java.lang.String,java.lang.Object%5B%5D,java.lang.Throwable)[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges.
It creates a new message object for each call.
[#gc-free-domain-object]
== How do I log my domain object without creating garbage?
-One option is to let the domain object implement java.lang.CharSequence.
+One option is to let the domain object implement `CharSequence`.
However, for many domain objects it may not be trivial to implement this without allocating temporary objects.
An alternative is to implement the `org.apache.logging.log4j.util.StringBuilderFormattable` interface.
-If an object is logged that implements this interface, its `formatTo` method is called instead of `toString()`.
-
-[source,java]
-----
-package org.apache.logging.log4j.util;
-public interface StringBuilderFormattable {
- /**
- * Writes a text representation of this object into the specified {@code StringBuilder},
- * ideally without allocating temporary objects.
- *
- * @param buffer the StringBuilder to write into
- */
- void formatTo(StringBuilder buffer);
-}
-----
+If an object is logged that implements this interface, its `formatTo(StringBuilder)` method is called instead of `toString()`.
[#logger-wrapper]
-== How do I create a custom logger wrapper that shows the correct class, method and line number?
+== How do I create a custom logger wrapper that shows the correct class, method, and line number?
Log4j remembers the fully qualified class name (FQCN) of the logger and uses this to walk the stack trace for every log event when configured to print location.
-(Be aware that logging with location is slow and may impact the performance of your application.)
+
+[WARNING]
+====
+Be aware that logging with location is slow and may impact the performance of your application.
+====
The problem with custom logger wrappers is that they have a different FQCN than the actual logger, so Log4j can't find the place where your custom logger was called.
The solution is to provide the correct FQCN.
The easiest way to do this is to let Log4j generate the logger wrapper for you.
Log4j comes with a Logger wrapper generator tool.
-This tool was originally meant to support custom log levels and is documented https://logging.apache.org/log4j/2.x/manual/customloglevels.html#CustomLoggers[here].
-
+This tool was originally meant to support custom log levels and is documented xref:manual/customloglevels.adoc#CustomLoggers[here].
Review Comment:
:+1: `customloglevels.adoc` will be revamped in #2530.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org