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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
