| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/markdown/faq.md.vm at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <title>Log4j – Frequently Asked Questions</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.11.2.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| <script src="./js/apache-maven-fluido-1.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../.." id="bannerLeft"><img src="images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href="./" id="bannerRight"><img src="images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/home.png" alt="Apache Log4j™ 2" style="border: 0;" /> Apache Log4j™ 2</li> |
| <li><a href="index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li> |
| <li class="active"><a><span class="none"></span>FAQ</a></li> |
| <li><a href="performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/book.png" alt="Manual" style="border: 0;" /> Manual</li> |
| <li><a href="manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li> |
| <li><a href="manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</li> |
| <li><a href="guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="log4j-spring-cloud-config-client.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| <!-- vim: set syn=markdown : --> |
| <!-- |
| 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. |
| --> |
| <h1>Frequently Asked Questions</h1> |
| <ul> |
| |
| <li><a href="#missing_core">I'm seeing this error “Unable to locate a logging implementation, using SimpleLogger”. What is wrong?</a></li> |
| <li><a href="#which_jars">Which JAR files do I need?</a></li> |
| <li><a href="#exclusions">How do I exclude conflicting dependencies?</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="#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="#retention">How do I set my log archive retention policy? How do I delete old log archives?</a></li> |
| <li><a href="#api-tradeoffs">What are the trade-offs of using the Log4j 2 API versus the SLF4J API?</a></li> |
| <li><a href="#gc-free-slf4j">Is Log4j 2 still garbage-free when I use the SLF4J API?</a></li> |
| <li><a href="#gc-free-domain-object">How do I log my domain object without creating garbage?</a></li> |
| <li><a href="#logger-wrapper">How do I create a custom logger wrapper that shows the correct class, method and line number?</a></li> |
| <li><a href="#proguard-rules">Which rules do I need to add when minification is enabled?</a></li> |
| </ul> |
| <a name="missing_core"></a> |
| <section><section><section> |
| <h4><a name="I.27m_seeing_this_error_.E2.80.9CUnable_to_locate_a_logging_implementation.2C_using_SimpleLogger.E2.80.9D._What_is_wrong.3F"></a>I'm seeing this error “Unable to locate a logging implementation, using SimpleLogger”. What is wrong?</h4> |
| <p>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.)</p> |
| <a name="which_jars"></a> |
| </section><section> |
| <h4><a name="Which_JAR_files_do_I_need.3F"></a>Which JAR files do I need?</h4> |
| <p>You need at least the log4j-api-2.x and the log4j-core-2.x 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.x.png" alt="Diagram showing which JARs correspond to which systems" /></p> |
| <a name="which_jars_log4j-to-slf4j"></a> |
| 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><img src="images/whichjar-slf4j-2.x.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="exclusions"></a> |
| </section><section> |
| <h4><a name="How_do_I_exclude_conflicting_dependencies.3F"></a>How do I exclude conflicting dependencies?</h4> |
| <p>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 |
| <code>org.apache.logging.log4j</code>), the following dependencies on the right can be safely excluded |
| (given in the format <code>groupId:artifactId</code>).</p> |
| |
| <table border="0" class="table table-bordered"> |
| |
| <tr class="a"> |
| |
| <th>Log4j Dependency</th> |
| |
| <th colspan="3">Dependencies to Exclude</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">[log4j-1.2-api](log4j-1.2-api)</td> |
| |
| <td>log4j:log4j</td> |
| |
| <td>org.slf4j:log4j-over-slf4j</td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">[log4j-core](log4j-core)</td> |
| |
| <td>log4j:log4j</td> |
| |
| <td>ch.qos.logback:logback-core</td> |
| |
| <td>org.apache.logging.log4j:log4j-to-slf4j</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">[log4j-jcl](log4j-jcl)</td> |
| |
| <td>org.slf4j:jcl-over-slf4j</td> |
| |
| <td></td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">[log4j-jul](log4j-jul)</td> |
| |
| <td>org.slf4j:jul-to-slf4j</td> |
| |
| <td></td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">[log4j-slf4j-impl](log4j-slf4j-impl)</td> |
| |
| <td>org.apache.logging.log4j:log4j-to-slf4j</td> |
| |
| <td>ch.qos.logback:logback-core</td> |
| |
| <td></td> |
| </tr> |
| </table> |
| |
| <p>Using Apache Maven, dependencies can be globally excluded in your project like so:</p> |
| |
| <div class="source"><pre class="prettyprint"><code><dependencies> |
| <dependency> |
| <groupId>log4j</groupId> |
| <artifactId>log4j</artifactId> |
| <version>1.2.17</version> |
| <scope>provided</scope> |
| </dependency> |
| </dependencies> |
| </code></pre></div> |
| <p>Dependencies can be explicitly excluded for specific dependencies as well. For example, to use a project |
| with Log4j 2 instead of Log4j 1.x:</p> |
| |
| <div class="source"><pre class="prettyprint"><code><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>2.23.1</version> |
| </dependency> |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>log4j-slf4j-impl</artifactId> |
| <version>2.23.1</version> |
| </dependency> |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>log4j-1.2-api</artifactId> |
| <version>2.23.1</version> |
| </dependency> |
| </dependencies> |
| </code></pre></div> |
| <p>Dependencies can be globally excluded in Gradle like so:</p> |
| |
| <div class="source"><pre class="prettyprint"><code>configurations { |
| all*.exclude group: 'log4j', module: 'log4j' |
| } |
| </code></pre></div> |
| <p>The equivalent Gradle config for the above Maven exclusion would look like:</p> |
| |
| <div class="source"><pre class="prettyprint"><code>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:2.23.1') |
| compile('org.apache.logging.log4j:log4j-slf4j-impl:2.23.1') |
| compile('org.apache.logging.log4j:log4j-1.2-api:2.23.1') |
| } |
| </code></pre></div> |
| <a name="config_location"></a> |
| </section><section> |
| <h4><a name="How_do_I_specify_the_configuration_file_location.3F"></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: |
| <code>-Dlog4j.configurationFile=path/to/log4j2.xml</code></p> |
| <p>That property can also be included in a classpath resource file named <code>log4j2.component.properties</code>.</p> |
| <p>Web applications can specify the Log4j configuration file location with a servlet context parameter. |
| See <a class="externalLink" href="http://logging.apache.org/log4j/2.x/manual/webapp.html#ContextParams">this section</a> |
| of the Using Log4j 2 in Web Applications manual page.</p> |
| <a name="config_from_code"></a> |
| </section><section> |
| <h4><a name="How_do_I_configure_log4j2_in_code_without_a_configuration_file.3F"></a>How do I configure log4j2 in code without a configuration file?</h4> |
| <p>Starting with version 2.4, Log4j 2 provides an <a href="manual/customconfig.html">API for programmatic configuration</a> |
| The new |
| <a href="log4j-core/apidocs/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html"><code>ConfigurationBuilder</code> API</a> |
| 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.</p> |
| <a name="reconfig_from_code"></a> |
| </section><section> |
| <h4><a name="How_do_I_reconfigure_log4j2_in_code_with_a_specific_configuration_file.3F"></a>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> |
| |
| <div class="source"><pre class="prettyprint"><code>// 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()); |
| </code></pre></div> |
| <a name="shutdown"></a> |
| </section><section> |
| <h4><a name="How_do_I_shut_down_log4j2_in_code.3F"></a>How do I shut down log4j2 in code?</h4> |
| <p>Normally there is no need to do this manually. |
| Each <code>LoggerContext</code> 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. |
| Note that there is an optional parameter for specifying which <code>LoggerContext</code> to |
| shut down.</p> |
| |
| <div class="source"><pre class="prettyprint"><code>import org.apache.logging.log4j.LogManager; |
| |
| // ... |
| |
| LogManager.shutdown(); |
| </code></pre></div> |
| <a name="config_sep_appender_level"></a> |
| </section><section> |
| <h4><a name="How_do_I_send_log_messages_with_different_levels_to_different_appenders.3F"></a>How do I send log messages with different levels to different appenders?</h4> |
| <p>You don't need to declare separate loggers to achieve this. |
| You can set the logging level on the <code>AppenderRef</code> element.</p> |
| |
| <div class="source"><pre class="prettyprint"><code><?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> |
| </code></pre></div> |
| <a name="troubleshooting"></a> |
| </section><section> |
| <h4><a name="How_do_I_debug_my_configuration.3F"></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 <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><b>From log4j-2.9 onward</b></p> |
| <p>From log4j-2.9 onward, log4j2 will print all internal logging to the console if system property <code>log4j2.debug</code> |
| is either defined empty or its value equals to <code>true</code> (ignoring case).</p> |
| <p><b>Prior to log4j-2.9</b></p> |
| <p>Prior to log4j-2.9, there are two places where internal logging can be controlled:</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"></a> |
| </section><section> |
| <h4><a name="How_do_I_dynamically_write_to_separate_log_files.3F"></a>How do I dynamically write to separate log files?</h4> |
| <p>Look at the <a class="externalLink" 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> |
| |
| <div class="source"><pre class="prettyprint"><code><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> |
| </code></pre></div> |
| <a name="reconfig_level_from_code"></a> |
| </section><section> |
| <h4><a name="How_do_I_set_a_logger.27s_level_programmatically.3F"></a>How do I set a logger's level programmatically?</h4> |
| <p>You can set a logger's level with the class |
| <a href="log4j-core/apidocs/org/apache/logging/log4j/core/config/Configurator.html"><code>Configurator</code></a> |
| from Log4j Core. Be aware that the <code>Configurator</code> class is not part of the public API.</p> |
| |
| <div class="source"><pre class="prettyprint"><code>// 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); |
| </code></pre></div> |
| <a name="retention"></a> |
| </section><section> |
| <h4><a name="How_do_I_set_my_log_archive_retention_policy.3F_How_do_I_delete_old_log_archives.3F"></a>How do I set my log archive retention policy? How do I delete old log archives?</h4> |
| <p>The <code>DefaultRolloverStrategy</code> of the Rolling File appender (and Rolling Random Access File |
| appender) supports a <a href="manual/appenders.html#CustomDeleteOnRollover">Delete</a> element.</p> |
| <p>Starting at a specified base directory, you can delete all files for which some condition |
| holds true, for example all files that match a given file name pattern and are older |
| than some number of days. More complex conditions are possible, and if the built-in |
| conditions are not sufficient, users can provide custom conditions by creating |
| <a href="manual/appenders.html#DeletePathCondition">plugin conditions</a> or by writing a |
| <a href="manual/appenders.html#ScriptCondition">script condition</a>.</p> |
| <a name="api-tradeoffs"></a> |
| </section><section> |
| <h4><a name="What_are_the_trade-offs_of_using_the_Log4j_2_API_versus_the_SLF4J_API.3F"></a>What are the trade-offs of using the Log4j 2 API versus the SLF4J API?</h4> |
| <p>The Log4j 2 API and SLF4J have a lot in common. |
| They both share the objective of cleanly separating the logging API from the implementation. |
| We believe that the Log4j 2 API can help make your application more performant |
| while offering more functionality and more flexibility.</p> |
| <p>There may be a concern that using the Log4j 2 API will tightly couple your application to Log4j 2. |
| This is not the case: applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant |
| library as their logging implementation with the log4j-to-slf4j adapter. |
| See the <a href="#which_jars_log4j-to-slf4j">which jars</a> FAQ entry for details.</p> |
| <p>There are several advantages to using the Log4j 2 API:</p> |
| <ul> |
| |
| <li>SLF4J forces your application to log Strings. |
| The Log4j 2 API supports logging any CharSequence if you want to log text, but also |
| supports logging any Object as is. |
| It is the responsibility of the logging <i>implementation</i> to handle this object, |
| and we consider it a design mistake to limit applications to logging Strings.</li> |
| <li>The Log4j 2 API offers support for logging <a href="manual/messages.html">Message objects</a>. |
| Messages allow support for interesting and complex constructs to be passed |
| through the logging system and be efficiently manipulated. |
| Users are free to create their own Message types and write custom Layouts, |
| Filters and Lookups to manipulate them.</li> |
| <li>The Log4j 2 API has support for Java 8 <a href="manual/api.html#LambdaSupport">lambda expressions</a>.</li> |
| <li>The Log4j 2 API has better support for <a href="manual/garbagefree.html">garbage-free logging</a>: |
| it avoids creating vararg arrays and avoids creating Strings when logging CharSequence objects.</li> |
| </ul> |
| <a name="gc-free-slf4j"></a> |
| </section><section> |
| <h4><a name="Is_Log4j_2_still_garbage-free_when_I_use_the_SLF4J_API.3F"></a>Is Log4j 2 still garbage-free when I use the SLF4J API?</h4> |
| <p>Yes, the log4j-slf4j-impl binding (together with log4j-core) implements the |
| <code>org.slf4j.Logger</code> methods to be GC-free. |
| However, bear in mind that there are some limitations:</p> |
| <p>The SLF4J API only offers up to two parameters for a parameterized message. |
| More than that uses varargs which creates a temporary object for the parameter array. |
| The Log4j 2.6 API has methods for up to ten unrolled parameters.</p> |
| <p>Another consideration is that the SLF4J API forces your application to log Strings. |
| Log4j 2 API lets you log any java.lang.CharSequence, and even any Objects. |
| Log4j can log any Object that implements <code>java.lang.CharSequence</code> |
| or <code>org.apache.logging.log4j.util.StringBuilderFormattable</code> without creating garbage.</p> |
| <p>The <a class="externalLink" href="https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log-org.slf4j.Marker-java.lang.String-int-java.lang.String-java.lang.Object:A-java.lang.Throwable-"><code>org.slf4j.spi.LocationAwareLogger::log</code></a> |
| method is not yet implemented |
| in a garbage-free manner in the log4j-slf4j-impl binding. It creates a new message object for each call.</p> |
| <a name="gc-free-domain-object"></a> |
| </section><section> |
| <h4><a name="How_do_I_log_my_domain_object_without_creating_garbage.3F"></a>How do I log my domain object without creating garbage?</h4> |
| <p>One option is to let the domain object implement java.lang.CharSequence. |
| However, for many domain objects it may not be trivial to implement this without allocating temporary |
| objects.</p> |
| <p>An alternative is to implement the <code>org.apache.logging.log4j.util.StringBuilderFormattable</code> interface. |
| If an object is logged that implements this interface, its <code>formatTo</code> method is called instead of |
| <code>toString()</code>.</p> |
| |
| <div class="source"><pre class="prettyprint"><code>package org.apache.logging.log4j.util; |
| public interface StringBuilderFormattable { |
| /** |
| * Writes a text representation of this object into the specified {@code StringBuilder}, |
| * ideally without allocating temporary objects. |
| * |
| * @param buffer the StringBuilder to write into |
| */ |
| void formatTo(StringBuilder buffer); |
| } |
| </code></pre></div> |
| <a name="logger-wrapper"></a> |
| </section><section> |
| <h4><a name="How_do_I_create_a_custom_logger_wrapper_that_shows_the_correct_class.2C_method_and_line_number.3F"></a>How do I create a custom logger wrapper that shows the correct class, method and line number?</h4> |
| <p>Log4j remembers the fully qualified class name (FQCN) of the logger and uses this to walk the stack trace |
| for every log event when configured to print location. |
| (Be aware that logging with location is slow and may impact the performance of your application.)</p> |
| <p>The problem with custom logger wrappers is that they have a different FQCN than the actual logger, |
| so Log4j can't find the place where your custom logger was called.</p> |
| <p>The solution is to provide the correct FQCN. The easiest way to do this is to let Log4j generate |
| the logger wrapper for you. Log4j comes with a Logger wrapper generator tool. |
| This tool was originally meant to support custom log levels and is documented |
| <a class="externalLink" href="https://logging.apache.org/log4j/2.x/manual/customloglevels.html#CustomLoggers">here</a>.</p> |
| <p>The generated logger code will take care of the FQCN.</p> |
| <a name="proguard-rules"></a> |
| </section><section> |
| <h4><a name="Which_rules_do_I_need_to_add_when_ProGuard_minification_is_enabled.3F"></a>Which rules do I need to add when ProGuard minification is enabled?</h4> |
| <p>When you are using Log4j with ProGuard/R8 enabled, you need to add the following rules to your configuration file:</p> |
| |
| <div class="source"><pre class="prettyprint"><code>-keep,allowoptimization class org.apache.logging.log4j.** { *; } |
| </code></pre></div></section></section></section> |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |
