src/site/xdoc/faq.xml - logging-log4j2 - Git at Google

 <?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="remkop@yahoo.com">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>&lt;Configuration status="trace"&gt;</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="remkop@yahoo.com">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>