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="#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="#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.0 and the log4j-core-2.0 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.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.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="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>Set configuration <code>status="trace"</code> and you will see
 		detailed log4j2-internal
         log statements 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>

 		<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="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="#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="#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.0 and the log4j-core-2.0 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.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.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="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>Set configuration <code>status="trace"</code> and you will see
	detailed log4j2-internal
	log statements 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>

	<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="custom_plugin" />
	<h4>How do I get log4j2 to recognize my custom plugin?</h4>
	-->
	</subsection>
	</section>

	</body>
	</document>