Repository: logging-log4j2 Updated Branches: refs/heads/master 1856a6ab5 -> abe74abdf
-the log4j-api-2.1 and the log4j-core-2.1 jar files +the log4j-api-2.4 and the log4j-core-2.4 jar files Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/abe74abd Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/abe74abd Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/abe74abd Branch: refs/heads/master Commit: abe74abdf86359b376533b1f0f3e121993d5b4c2 Parents: 1856a6a Author: ggregory <[email protected]> Authored: Mon Sep 21 14:17:00 2015 -0700 Committer: ggregory <[email protected]> Committed: Mon Sep 21 14:17:00 2015 -0700 ---------------------------------------------------------------------- src/site/xdoc/faq.xml | 500 ++++++++++++++++++++++----------------------- 1 file changed, 250 insertions(+), 250 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/abe74abd/src/site/xdoc/faq.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/faq.xml b/src/site/xdoc/faq.xml index 44359cb..eb848c8 100644 --- a/src/site/xdoc/faq.xml +++ b/src/site/xdoc/faq.xml @@ -1,250 +1,250 @@ -<?xml version="1.0"?> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<document> - <properties> - <title>Frequently Asked Questions</title> - <author email="[email protected]">Remko Popma</author> - </properties> - - <body> - <section name="Frequently Asked Questions"> - <ul> - <li><a href="#which_jars">Which JAR files do I need?</a></li> - <li><a href="#config_location">How do I specify the configuration file location?</a></li> - <li><a href="#config_from_code">How do I configure log4j2 in code without a configuration file?</a></li> - <li><a href="#reconfig_from_code">How do I reconfigure log4j2 in code with a specific configuration file?</a></li> - <li><a href="#set_logger_level_from_code">How do I change a logger's level in code?</a></li> - <li><a href="#shutdown">How do I shut down log4j2 in code?</a></li> - <li><a href="#config_sep_appender_level">How do I send log messages with different levels to different appenders?</a></li> - <li><a href="#troubleshooting">How do I debug my configuration?</a></li> - <li><a href="#separate_log_files">How do I dynamically write to separate log files?</a></li> - <li><a href="#reconfig_level_from_code">How do I set a logger's level programmatically?</a></li> - <!-- - <li><a href="#custom_plugin">How do I get log4j2 to recognize my custom plugin?</a></li> - --> - </ul> - <subsection> - <a name="which_jars" /> - <h4>Which JAR files do I need?</h4> - <p>You need at least the log4j-api-2.1 and the log4j-core-2.1 jar files.</p> - <p>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.</p> - <p><img src="images/whichjar-2.1.png" alt="Diagram showing which JARs correspond to which systems" /></p> - <p>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.</p> - <p><img src="images/whichjar-slf4j-2.1.png" alt="Diagram showing the dependency flow to use Log4j 2 API with SLF4J" /></p> - <p>Some of the Log4j components have features with optional dependencies. - The component page will have more detail. - For example, the <a href="log4j-core/index.html">log4j-core component page</a> - has an outline of which log4j-core features have external dependencies.</p> - - <a name="config_location" /> - <h4>How do I specify the configuration file location?</h4> - <p>By default, Log4j looks for a configuration file named <b>log4j2.xml</b> (not log4j.xml) in the classpath. - </p><p> - You can also specify the full path of the configuration file with this system property:<br /> - <code>-Dlog4j.configurationFile=path/to/log4j2.xml</code></p> - - <a name="config_from_code" /> - <h4>How do I configure log4j2 in code without a configuration file?</h4> - <p>You could use the static method <code>#initialize(String contextName, ClassLoader loader, String configLocation)</code> - (see - <a href="log4j-core/xref/org/apache/logging/log4j/core/config/Configurator.html">source code</a>) - in <code>org.apache.logging.log4j.core.config.Configurator</code>. - (You can pass null for the class loader.) - Be aware that this class is not part of the public API so your code may break with any minor release.</p> - - <a name="reconfig_from_code" /> - <h4>How do I reconfigure log4j2 in code with a specific configuration file?</h4> - <p>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.</p> - <pre class="prettyprint linenums">// 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"); - -// this will force a reconfiguration -context.setConfigLocation(file.toURI()); -</pre> - - <a name="set_logger_level_from_code" /> - <h4>How do I change a logger's level in code?</h4> - <p>See the below example. - Be aware that these classes are not part of the public API so your code may break with any minor release.</p> - <pre class="prettyprint linenums">// import org.apache.logging.log4j.core.LoggerContext; -// import org.apache.logging.log4j.core.config.Configuration; -// import org.apache.logging.log4j.core.config.LoggerConfig; - -LoggerContext context = (LoggerContext) LogManager.getContext(false); -Configuration config = context.getConfiguration(); -LoggerConfig rootConfig = config.getLoggerConfig(LogManager.ROOT_LOGGER_NAME); -rootConfig.setLevel(Level.DEBUG); - -// You could also specify the actual logger name as below -// and it will return the LoggerConfig used by the Logger. -LoggerConfig loggerConfig = config.getLoggerConfig("com.apache.test"); -loggerConfig.setLevel(Level.TRACE); - -// This causes all Loggers to refetch information from their LoggerConfig. -context.updateLoggers(); -</pre> - - <a name="shutdown" /> - <h4>How do I shut down log4j2 in code?</h4> - <p>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 <code>log4j.shutdownHookEnabled</code> - is set to <code>false</code>). - 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.</p> - <p>However, if you need to manually shut down log4j, you can do so - as in the below example. - Be aware that these classes are not part of the public API so your code may break with any minor release.</p> - <pre class="prettyprint linenums">// import org.apache.logging.log4j.core.LoggerContext; -// import org.apache.logging.log4j.core.config.Configurator; - -// get the current context -LoggerContext context = (LoggerContext) LogManager.getContext(); -Configurator.shutdown(context);</pre> - - <a name="config_sep_appender_level" /> - <h4>How do I send log messages with different levels to different appenders?</h4> - You don't need to declare separate loggers to achieve this. - You can set the logging level on the <code>AppenderRef</code> element. - <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="WARN"> - <Appenders> - <File name="file" fileName="app.log"> - <PatternLayout> - <Pattern>%d %p %c{1.} [%t] %m %ex%n</Pattern> - </PatternLayout> - </File> - <Console name="STDOUT" target="SYSTEM_OUT"> - <PatternLayout pattern="%m%n"/> - </Console> - </Appenders> - <Loggers> - <Root level="trace"> - <AppenderRef ref="file" level="DEBUG"/> - <AppenderRef ref="STDOUT" level="INFO"/> - </Root> - </Loggers> -</Configuration>]]></pre> - - <a name="troubleshooting" /> - <h4>How do I debug my configuration?</h4> - <p>First, make sure you have <a href="#which_jars">the right jar files</a> on your classpath. - You need at least log4j-api and log4j-core.</p> - <p>Next, check the name of your configuration file. By default, log4j2 will look - for a configuration file named <code>log4j2.xml</code> on the classpath. Note the "2" in the file name! - (See the <a href="manual/configuration.html#AutomaticConfiguration">configuration manual page</a> - for more details.)</p> - <p>If the configuration file is found correctly, log4j2 internal status logging can be controlled by - setting <code><Configuration status="trace"></code> 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. - </p> - <p>If the configuration file is not found correctly, you can still enable - log4j2 internal status logging by setting system property - <code>-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE</code>.</p> - - <a name="separate_log_files" /> - <h4>How do I dynamically write to separate log files?</h4> - <p> - Look at the - <a href="http://logging.apache.org/log4j/2.x/manual/appenders.html#RoutingAppender";>RoutingAppender</a>. - You can define multiple routes in the configuration, - and put values in the <code>ThreadContext</code> map that determine - which log file subsequent events in this thread get logged to.</p> - <p> - You can use the <code>ThreadContext</code> map value to determine the log file name. - </p> - <pre class="prettyprint linenums"><![CDATA[<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>]]></pre> - - <a name="reconfig_level_from_code" /> - <h4>How do I set a logger's level programmatically?</h4> - <p>You can set a logger's level with the class Configurator from Core module. - Be aware that the Configuration class is not part of the public API.</p> - <pre class="prettyprint linenums">// 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); -</pre> - - <!-- - <a name="custom_plugin" /> - <h4>How do I get log4j2 to recognize my custom plugin?</h4> - --> - </subsection> - </section> - - </body> -</document> +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<document> + <properties> + <title>Frequently Asked Questions</title> + <author email="[email protected]">Remko Popma</author> + </properties> + + <body> + <section name="Frequently Asked Questions"> + <ul> + <li><a href="#which_jars">Which JAR files do I need?</a></li> + <li><a href="#config_location">How do I specify the configuration file location?</a></li> + <li><a href="#config_from_code">How do I configure log4j2 in code without a configuration file?</a></li> + <li><a href="#reconfig_from_code">How do I reconfigure log4j2 in code with a specific configuration file?</a></li> + <li><a href="#set_logger_level_from_code">How do I change a logger's level in code?</a></li> + <li><a href="#shutdown">How do I shut down log4j2 in code?</a></li> + <li><a href="#config_sep_appender_level">How do I send log messages with different levels to different appenders?</a></li> + <li><a href="#troubleshooting">How do I debug my configuration?</a></li> + <li><a href="#separate_log_files">How do I dynamically write to separate log files?</a></li> + <li><a href="#reconfig_level_from_code">How do I set a logger's level programmatically?</a></li> + <!-- + <li><a href="#custom_plugin">How do I get log4j2 to recognize my custom plugin?</a></li> + --> + </ul> + <subsection> + <a name="which_jars" /> + <h4>Which JAR files do I need?</h4> + <p>You need at least the log4j-api-2.4 and the log4j-core-2.4 jar files.</p> + <p>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.</p> + <p><img src="images/whichjar-2.1.png" alt="Diagram showing which JARs correspond to which systems" /></p> + <p>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.</p> + <p><img src="images/whichjar-slf4j-2.1.png" alt="Diagram showing the dependency flow to use Log4j 2 API with SLF4J" /></p> + <p>Some of the Log4j components have features with optional dependencies. + The component page will have more detail. + For example, the <a href="log4j-core/index.html">log4j-core component page</a> + has an outline of which log4j-core features have external dependencies.</p> + + <a name="config_location" /> + <h4>How do I specify the configuration file location?</h4> + <p>By default, Log4j looks for a configuration file named <b>log4j2.xml</b> (not log4j.xml) in the classpath. + </p><p> + You can also specify the full path of the configuration file with this system property:<br /> + <code>-Dlog4j.configurationFile=path/to/log4j2.xml</code></p> + + <a name="config_from_code" /> + <h4>How do I configure log4j2 in code without a configuration file?</h4> + <p>You could use the static method <code>#initialize(String contextName, ClassLoader loader, String configLocation)</code> + (see + <a href="log4j-core/xref/org/apache/logging/log4j/core/config/Configurator.html">source code</a>) + in <code>org.apache.logging.log4j.core.config.Configurator</code>. + (You can pass null for the class loader.) + Be aware that this class is not part of the public API so your code may break with any minor release.</p> + + <a name="reconfig_from_code" /> + <h4>How do I reconfigure log4j2 in code with a specific configuration file?</h4> + <p>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.</p> + <pre class="prettyprint linenums">// 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"); + +// this will force a reconfiguration +context.setConfigLocation(file.toURI()); +</pre> + + <a name="set_logger_level_from_code" /> + <h4>How do I change a logger's level in code?</h4> + <p>See the below example. + Be aware that these classes are not part of the public API so your code may break with any minor release.</p> + <pre class="prettyprint linenums">// import org.apache.logging.log4j.core.LoggerContext; +// import org.apache.logging.log4j.core.config.Configuration; +// import org.apache.logging.log4j.core.config.LoggerConfig; + +LoggerContext context = (LoggerContext) LogManager.getContext(false); +Configuration config = context.getConfiguration(); +LoggerConfig rootConfig = config.getLoggerConfig(LogManager.ROOT_LOGGER_NAME); +rootConfig.setLevel(Level.DEBUG); + +// You could also specify the actual logger name as below +// and it will return the LoggerConfig used by the Logger. +LoggerConfig loggerConfig = config.getLoggerConfig("com.apache.test"); +loggerConfig.setLevel(Level.TRACE); + +// This causes all Loggers to refetch information from their LoggerConfig. +context.updateLoggers(); +</pre> + + <a name="shutdown" /> + <h4>How do I shut down log4j2 in code?</h4> + <p>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 <code>log4j.shutdownHookEnabled</code> + is set to <code>false</code>). + 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.</p> + <p>However, if you need to manually shut down log4j, you can do so + as in the below example. + Be aware that these classes are not part of the public API so your code may break with any minor release.</p> + <pre class="prettyprint linenums">// import org.apache.logging.log4j.core.LoggerContext; +// import org.apache.logging.log4j.core.config.Configurator; + +// get the current context +LoggerContext context = (LoggerContext) LogManager.getContext(); +Configurator.shutdown(context);</pre> + + <a name="config_sep_appender_level" /> + <h4>How do I send log messages with different levels to different appenders?</h4> + You don't need to declare separate loggers to achieve this. + You can set the logging level on the <code>AppenderRef</code> element. + <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="WARN"> + <Appenders> + <File name="file" fileName="app.log"> + <PatternLayout> + <Pattern>%d %p %c{1.} [%t] %m %ex%n</Pattern> + </PatternLayout> + </File> + <Console name="STDOUT" target="SYSTEM_OUT"> + <PatternLayout pattern="%m%n"/> + </Console> + </Appenders> + <Loggers> + <Root level="trace"> + <AppenderRef ref="file" level="DEBUG"/> + <AppenderRef ref="STDOUT" level="INFO"/> + </Root> + </Loggers> +</Configuration>]]></pre> + + <a name="troubleshooting" /> + <h4>How do I debug my configuration?</h4> + <p>First, make sure you have <a href="#which_jars">the right jar files</a> on your classpath. + You need at least log4j-api and log4j-core.</p> + <p>Next, check the name of your configuration file. By default, log4j2 will look + for a configuration file named <code>log4j2.xml</code> on the classpath. Note the "2" in the file name! + (See the <a href="manual/configuration.html#AutomaticConfiguration">configuration manual page</a> + for more details.)</p> + <p>If the configuration file is found correctly, log4j2 internal status logging can be controlled by + setting <code><Configuration status="trace"></code> 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. + </p> + <p>If the configuration file is not found correctly, you can still enable + log4j2 internal status logging by setting system property + <code>-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE</code>.</p> + + <a name="separate_log_files" /> + <h4>How do I dynamically write to separate log files?</h4> + <p> + Look at the + <a href="http://logging.apache.org/log4j/2.x/manual/appenders.html#RoutingAppender";>RoutingAppender</a>. + You can define multiple routes in the configuration, + and put values in the <code>ThreadContext</code> map that determine + which log file subsequent events in this thread get logged to.</p> + <p> + You can use the <code>ThreadContext</code> map value to determine the log file name. + </p> + <pre class="prettyprint linenums"><![CDATA[<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>]]></pre> + + <a name="reconfig_level_from_code" /> + <h4>How do I set a logger's level programmatically?</h4> + <p>You can set a logger's level with the class Configurator from Core module. + Be aware that the Configuration class is not part of the public API.</p> + <pre class="prettyprint linenums">// 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); +</pre> + + <!-- + <a name="custom_plugin" /> + <h4>How do I get log4j2 to recognize my custom plugin?</h4> + --> + </subsection> + </section> + + </body> +</document>
