Google Git
Sign in
apache / logging-log4j-site / refs/heads/asf-site / . / 2.3.x / faq.html
blob: c87d5ce746f7502e905ff4f349516aedbfaea725 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
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.
-->
<!-- Generated by Apache Maven Doxia at 2021-12-29 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Log4j &#x2013; Frequently Asked Questions - Apache Log4j 2</title>
<link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="./css/site.css" type="text/css" />
<script type="text/javascript" src="./js/jquery.min.js"></script>
<script type="text/javascript" src="./js/bootstrap.min.js"></script>
<script type="text/javascript" src="./js/prettify.min.js"></script>
<script type="text/javascript" src="./js/site.js"></script>
<meta name="author" content="Remko Popma" />
<meta name="Date-Revision-yyyymmdd" content="20211229" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<img class="logo-left" src="./images/ls-logo.jpg" alt="Apache logging services logo" />
<img class="logo-right" src="./images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../" title="Logging Services">Logging Services</a>
</li>
<li>
<a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none">
<a href="index.html" title="About">About</a>
</li>
<li class="none">
<a href="download.html" title="Download">Download</a>
</li>
<li class="none">
<a href="maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a>
</li>
<li class="none">
<a href="build.html" title="Build">Build</a>
</li>
<li class="none">
<a href="guidelines.html" title="Guidelines">Guidelines</a>
</li>
<li class="none">
<a href="javastyle.html" title="Style Guide">Style Guide</a>
</li>
<li class="none">
<a href="changelog.html" title="Changelog">Changelog</a>
</li>
<li class="collapsed">
<a href="javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a>
</li>
<li class="none active">
<a href="faq.html" title="FAQ">FAQ</a>
</li>
<li class="none">
<a href="articles.html" title="Articles">Articles</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="manual/" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="collapsed">
<a href="manual/api.html" title="API">API</a>
</li>
<li class="collapsed">
<a href="manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="collapsed">
<a href="manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
</li>
<li class="collapsed">
<a href="manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="manual/lookups.html" title="Lookups">Lookups</a>
</li>
<li class="collapsed">
<a href="manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="collapsed">
<a href="manual/filters.html" title="Filters">Filters</a>
</li>
<li class="collapsed">
<a href="manual/async.html" title="Async Loggers">Async Loggers</a>
</li>
<li class="none">
<a href="manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
<li class="collapsed">
<a href="manual/customconfig.html" title="Extending Log4j Configuration">Extending Log4j Configuration</a>
</li>
<li class="collapsed">
<a href="manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="log4j-api/" title="API">API</a>
</li>
<li class="none">
<a href="log4j-core/" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="log4j-jcl/" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="log4j-1.2-api/" title="Log4j 1.2 API">Log4j 1.2 API</a>
</li>
<li class="none">
<a href="log4j-slf4j-impl/" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="log4j-jul/" title="JUL Adapter">JUL Adapter</a>
</li>
<li class="none">
<a href="log4j-to-slf4j/" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="log4j-flume-ng/" title="Apache Flume Appender">Apache Flume Appender</a>
</li>
<li class="none">
<a href="log4j-taglib/" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
<li class="none">
<a href="log4j-jmx-gui/" title="Log4j JMX GUI">Log4j JMX GUI</a>
</li>
<li class="none">
<a href="log4j-web/" title="Log4j Web Application Support">Log4j Web Application Support</a>
</li>
<li class="none">
<a href="log4j-nosql/" title="Log4j NoSQL support">Log4j NoSQL support</a>
</li>
<li class="none">
<a href="log4j-iostreams/" title="Log4j IO Streams">Log4j IO Streams</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="./images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- 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. -->
<div class="section">
<h2><a name="Frequently_Asked_Questions"></a>Frequently Asked Questions</h2>
<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>
<div class="section">
<h3><a name="null"></a></h3>
<a name="which_jars"></a>
<div class="section">
<h4><a name="Which_JAR_files_do_I_need"></a>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/">log4j-core component page</a>
has an outline of which log4j-core features have external dependencies.</p>
<a name="config_location"></a>
</div>
<div class="section">
<h4><a name="How_do_I_specify_the_configuration_file_location"></a>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 />
<tt>-Dlog4j.configurationFile=path/to/log4j2.xml</tt></p>
<a name="config_from_code"></a>
</div>
<div class="section">
<h4><a name="How_do_I_configure_log4j2_in_code_without_a_configuration_file"></a>How do I configure log4j2 in code without a configuration file?</h4>
<p>You could use the static method <tt>#initialize(String contextName, ClassLoader loader, String configLocation)</tt>
(see
<a href="log4j-core/xref/org/apache/logging/log4j/core/config/Configurator.html">source code</a>)
in <tt>org.apache.logging.log4j.core.config.Configurator</tt>.
(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"></a>
</div>
<div class="section">
<h4><a name="How_do_I_send_log_messages_with_different_levels_to_different_appenders"></a>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 <tt>AppenderRef</tt> element.
<div>
<pre class="prettyprint linenums">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;WARN&quot;&gt;
&lt;Appenders&gt;
&lt;File name=&quot;file&quot; fileName=&quot;app.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;Pattern&gt;%d %p %c{1.} [%t] %m %ex%n&lt;/Pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;
&lt;Console name=&quot;STDOUT&quot; target=&quot;SYSTEM_OUT&quot;&gt;
&lt;PatternLayout pattern=&quot;%m%n&quot;/&gt;
&lt;/Console&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;trace&quot;&gt;
&lt;AppenderRef ref=&quot;file&quot; level=&quot;DEBUG&quot;/&gt;
&lt;AppenderRef ref=&quot;STDOUT&quot; level=&quot;INFO&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
<a name="troubleshooting"></a>
</div>
<div class="section">
<h4><a name="How_do_I_debug_my_configuration"></a>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 <tt>log4j2.xml</tt> on the classpath. Note the &quot;2&quot; 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 <tt>&lt;Configuration status=&quot;trace&quot;&gt;</tt> 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
<tt>-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE</tt>.</p>
<a name="separate_log_files"></a>
</div>
<div class="section">
<h4><a name="How_do_I_dynamically_write_to_separate_log_files"></a>How do I dynamically write to separate log files?</h4>
<p>
Look at the
<a class="externalLink" href="/log4j/2.x/manual/appenders.html#RoutingAppender">RoutingAppender</a>.
You can define multiple routes in the configuration,
and put values in the <tt>ThreadContext</tt> map that determine
which log file subsequent events in this thread get logged to.</p>
<p>
You can use the <tt>ThreadContext</tt> map value to determine the log file name.
</p>
<div>
<pre class="prettyprint linenums">&lt;Routing name=&quot;Routing&quot;&gt;
&lt;Routes pattern=&quot;$${ctx:ROUTINGKEY}&quot;&gt;
&lt;!-- This route is chosen if ThreadContext has value 'special' for key ROUTINGKEY. --&gt;
&lt;Route key=&quot;special&quot;&gt;
&lt;RollingFile name=&quot;Rolling-${ctx:ROUTINGKEY}&quot; fileName=&quot;logs/special-${ctx:ROUTINGKEY}.log&quot;
filePattern=&quot;./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-special-%d{yyyy-MM-dd}-%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d{ISO8601} [%t] %p %c{3} - %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;Policies&gt;
&lt;TimeBasedTriggeringPolicy interval=&quot;6&quot; modulate=&quot;true&quot; /&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;10 MB&quot; /&gt;
&lt;/Policies&gt;
&lt;/RollingFile&gt;
&lt;/Route&gt;
&lt;!-- This route is chosen if ThreadContext has no value for key ROUTINGKEY. --&gt;
&lt;Route key=&quot;$${ctx:ROUTINGKEY}&quot;&gt;
&lt;RollingFile name=&quot;Rolling-default&quot; fileName=&quot;logs/default.log&quot;
filePattern=&quot;./logs/${date:yyyy-MM}/default-%d{yyyy-MM-dd}-%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d{ISO8601} [%t] %p %c{3} - %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;Policies&gt;
&lt;TimeBasedTriggeringPolicy interval=&quot;6&quot; modulate=&quot;true&quot; /&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;10 MB&quot; /&gt;
&lt;/Policies&gt;
&lt;/RollingFile&gt;
&lt;/Route&gt;
&lt;!-- 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. --&gt;
&lt;Route&gt;
&lt;RollingFile name=&quot;Rolling-${ctx:ROUTINGKEY}&quot; fileName=&quot;logs/other-${ctx:ROUTINGKEY}.log&quot;
filePattern=&quot;./logs/${date:yyyy-MM}/${ctx:ROUTINGKEY}-other-%d{yyyy-MM-dd}-%i.log.gz&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d{ISO8601} [%t] %p %c{3} - %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;Policies&gt;
&lt;TimeBasedTriggeringPolicy interval=&quot;6&quot; modulate=&quot;true&quot; /&gt;
&lt;SizeBasedTriggeringPolicy size=&quot;10 MB&quot; /&gt;
&lt;/Policies&gt;
&lt;/RollingFile&gt;
&lt;/Route&gt;
&lt;/Routes&gt;
&lt;/Routing&gt;</pre></div>
<!-- <a name="custom_plugin" />
<h4>How do I get log4j2 to recognize my custom plugin?</h4> -->
</div></div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2021 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>