| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/markdown/faq.md.vm at 2020-05-10 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <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.9.1" /> |
| <title>Log4j – Frequently Asked Questions</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.8.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.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-05-10<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.3</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="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</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" 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="javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</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="runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li> |
| <li class="active"><a href="#"><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="none"></span>Security</a></li> |
| <li><a href="support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></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/book.png" alt="Manual" 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/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="none"></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="manual/scala-api.html" 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/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="log4j-jpl/index.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.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/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <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> |
| </ul> |
| <p><a name="missing_core"></a></p><section><section><section> |
| <h4><a name="I.E2.80.99m_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> |
| <p><a name="which_jars"></a></p></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> |
| <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> |
| <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> |
| <p><a name="exclusions"></a></p></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 org.apache.logging.log4j), the following dependencies on the right can be safely excluded (given in the format groupId:artifactId).</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>[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>[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>[log4j-jcl](log4j-jcl)</td> |
| |
| <td>org.slf4j:jcl-over-slf4j</td> |
| |
| <td></td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>[log4j-jul](log4j-jul)</td> |
| |
| <td>org.slf4j:jul-to-slf4j</td> |
| |
| <td></td> |
| |
| <td></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>[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> |
| <div> |
| <pre class="source"><dependencies> |
| <dependency> |
| <groupId>log4j</groupId> |
| <artifactId>log4j</artifactId> |
| <version>1.2.17</version> |
| <scope>provided</scope> |
| </dependency> |
| </dependencies> |
| </pre></div></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> |
| <div> |
| <pre class="source"><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.13.3</version> |
| </dependency> |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>log4j-slf4j-impl</artifactId> |
| <version>2.13.3</version> |
| </dependency> |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>log4j-1.2-api</artifactId> |
| <version>2.13.3</version> |
| </dependency> |
| </dependencies> |
| </pre></div></div> |
| |
| <p>Dependencies can be globally excluded in Gradle like so:</p> |
| |
| <div> |
| <div> |
| <pre class="source">configurations { |
| all*.exclude group: 'log4j', module: 'log4j' |
| } |
| </pre></div></div> |
| |
| <p>The equivalent Gradle config for the above Maven exclusion would look like:</p> |
| |
| <div> |
| <div> |
| <pre class="source">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.13.3') |
| compile('org.apache.logging.log4j:log4j-slf4j-impl:2.13.3') |
| compile('org.apache.logging.log4j:log4j-1.2-api:2.13.3') |
| } |
| </pre></div></div> |
| |
| <p><a name="config_location"></a></p></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: -Dlog4j.configurationFile=path/to/log4j2.xml</p> |
| <p>That property can also be included in a classpath resource file named log4j2.component.properties.</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> |
| <p><a name="config_from_code"></a></p></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">ConfigurationBuilder 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> |
| <p><a name="reconfig_from_code"></a></p></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> |
| <div> |
| <pre class="source">// 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></div></div> |
| |
| <p><a name="shutdown"></a></p></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 LoggerContext registers a shutdown hook that takes care of releasing resources when the JVM exits (unless system property log4j.shutdownHookEnabled is set to false). 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 LoggerContext to shut down.</p> |
| |
| <div> |
| <div> |
| <pre class="source">import org.apache.logging.log4j.LogManager; |
| |
| // ... |
| |
| LogManager.shutdown(); |
| </pre></div></div> |
| |
| <p><a name="config_sep_appender_level"></a></p></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 AppenderRef element.</p> |
| |
| <div> |
| <div> |
| <pre class="source"><?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></div></div> |
| |
| <p><a name="troubleshooting"></a></p></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 log4j2.xml 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 log4j2.debug is defined (with any or no value).</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 <Configuration status="trace"> 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 -Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE.</p> |
| <p><a name="separate_log_files"></a></p></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 ThreadContext map that determine which log file subsequent events in this thread get logged to.</p> |
| <p>You can use the ThreadContext map value to determine the log file name.</p> |
| |
| <div> |
| <div> |
| <pre class="source"><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></div></div> |
| |
| <p><a name="reconfig_level_from_code"></a></p></section><section> |
| <h4><a name="How_do_I_set_a_logger.E2.80.99s_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">Configurator</a> from Log4j Core. Be aware that the Configurator class is not part of the public API.</p> |
| |
| <div> |
| <div> |
| <pre class="source">// 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></div></div> |
| |
| <p><a name="retention"></a></p></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 DefaultRolloverStrategy 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> |
| <p><a name="api-tradeoffs"></a></p></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> |
| <p><a name="gc-free-slf4j"></a></p></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 org.slf4j.Logger 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 java.lang.CharSequence or org.apache.logging.log4j.util.StringBuilderFormattable without creating garbage.</p> |
| <p>The [org.slf4j.spi.LocationAwareLogger::log]#log(org.slf4j.Marker, java.lang.String, int, java.lang.String, java.lang.Object(<a class="externalLink" href="http://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html">http://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html</a>[], java.lang.Throwable)) 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> |
| <p><a name="gc-free-domain-object"></a></p></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 org.apache.logging.log4j.util.StringBuilderFormattable interface. If an object is logged that implements this interface, its formatTo method is called instead of toString().</p> |
| |
| <div> |
| <div> |
| <pre class="source">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); |
| } |
| </pre></div></div> |
| |
| <p><a name="logger-wrapper"></a></p></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></section></section></section> |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2020 <a class="external" href="http://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> |
| </body> |
| </html> |
