| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/markdown/manual/migration.md 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 – Migrating from Log4j 1.x to 2.x</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><a href="../faq.html" title="FAQ"><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 class="active"><a><span class="icon-chevron-down"></span>Log4j 1.x Migration</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/migration.html#Log4j1.2Bridge" title="Log4j 1.x Bridge"><span class="none"></span>Log4j 1.x Bridge</a></li> |
| <li><a href="../manual/migration.html#EnablingLog4j1.2Bridge" title="Enabling the Bridge"><span class="none"></span>Enabling the Bridge</a></li> |
| <li><a href="../manual/migration.html#APICompatibility" title="API Compatibility"><span class="none"></span>API Compatibility</a></li> |
| <li><a href="../manual/migration.html#ConfigurationCompatibility" title="Configuration Compatibility"><span class="none"></span>Configuration Compatibility</a></li> |
| <li><a href="../manual/migration.html#Log4j1.2BridgeLimitations" title="Bridge Limitations"><span class="none"></span>Bridge Limitations</a></li> |
| <li><a href="../manual/migration.html#Log4j2API" title="Migrating to the Log4j 2 API"><span class="none"></span>Migrating to the Log4j 2 API</a></li> |
| <li><a href="../manual/migration.html#Log4j2ConfigurationFormat" title="Migrating to the Log4j 2 Configuration"><span class="none"></span>Migrating to the Log4j 2 Configuration</a></li> |
| </ul></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. |
| --> |
| <section> |
| <h2><a name="Migrating_from_Log4j_1.x_to_2.x"></a>Migrating from Log4j 1.x to 2.x</h2> |
| <p><a class="externalLink" href="http://logging.apache.org/log4j/1.2/">Log4j 1.x</a> has |
| <a class="externalLink" href="https://blogs.apache.org/foundation/entry/apache_logging_services_project_announces">reached End of Life</a> |
| in 2015 and is no longer supported.</p> |
| <p>This page explains how to migrate applications or libraries currently using the Log4j 1.x API |
| to use Log4j v2 as their main logging framework.</p> |
| <a name="Log4j1.2Bridge"></a> |
| <section> |
| <h3><a name="Option_1:_use_the_Log4j_1.x_bridge_.28log4j-1.2-api.29"></a>Option 1: use the Log4j 1.x bridge (log4j-1.2-api)</h3> |
| <p>You may be able to convert an application to Log4j 2 <i>without any code changes</i> |
| by replacing the Log4j 1.x jar file with Log4j 2's <code>log4j-1.2-api.jar</code>.</p> |
| <p>The Log4j 1.x bridge is useful when:</p> |
| <ul> |
| |
| <li>the application itself is (maybe partly) still using the Log4j 1.x API, or if</li> |
| <li>the application depends on a library which depends on the Log 1.x API, or</li> |
| <li>the application needs to support logging configurations in the old Log4j 1.x format.</li> |
| </ul> |
| <p>To use this option, applications need to use the following three jar files: |
| the Log4j 2 API jar (<code>log4j-api.jar</code>), |
| the Log4j 2 implementation jar (<code>log4j-core.jar</code>) and |
| the Log4j 1.x bridge jar (<code>log4j-1.2-api.jar</code>).</p> |
| <p><img src="../images/whichjar-log4j-1.2-api.png" alt="Using log4j 2 via the log4j 1.x API" /></p> |
| <p>For most applications this is sufficient. |
| This is a low-effort way to migrate, and may also allow for migration to proceed gradually over time.</p> |
| <a name="EnablingLog4j1.2Bridge"></a> |
| <section> |
| <h4><a name="Enabling_the_Log4j_1.x_bridge"></a>Enabling the Log4j 1.x bridge</h4> |
| <p>Enable the Log4j 1.x bridge via one of the following steps:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>Set the system property “log4j1.compatibility” to a value of “true”. Log4j 2 will then add log4j.properties, |
| log4j-test.properties, log4j.xml and log4j-test.xml to the |
| <a href="configuration.html#AutomaticConfiguration">configuration files</a> it searches for on the class path.</li> |
| <li>Set the Log4j 1 system property “log4j.configuration” to the location of the log4j 1 configuration file. The |
| files must have a file extension of either “.properties” or “.xml”.</li> |
| </ol> |
| <a name="APICompatibility"></a> |
| </section><section> |
| <h4><a name="API_Compatibility"></a>API Compatibility</h4> |
| <p>Log4j 2 provides support for the Log4j 1 logging methods by providing alternate implementations |
| of the classes containing those methods. These classes may be found in the log4j-1.2-api jar |
| distributed with the project. All calls to perform logging will result in the data passed to the logging methods |
| to be forwarded to the Log4j2 API where they can be processed by implementations of the Log4j 2 API.</p> |
| <a name="ConfigurationCompatibility"></a> |
| </section><section> |
| <h4><a name="Configuration_Compatibility"></a>Configuration Compatibility</h4> |
| <p>Log4j 2 provides support for Log4j 1 configuration files. Configuration of the Appenders, Layouts |
| and Filters that were provided in the Log4j 1 distribution will be redirected to their Log4j 2 counterparts - |
| with the exception of the implemented Rewrite Policies. This means that although the behavior of these |
| components will be similar, they may not be exactly the same. |
| For example, the XML generated by the XMLLayout may |
| not exactly match the XML generated by the Log4j1XMLLayout.</p> |
| <p>In addition, Log4j 2 supports custom Log4j 1 Appenders, Filters, and Layouts with some constraints. Since the |
| original Log4j 1 components may not be present in Log4j 2, custom components that extend them will fail.</p><section> |
| <h5><a name="Supported_Components"></a>Supported Components</h5> |
| <p>Supported Appenders include: AsyncAppender, ConsoleAppender, DailyRollingFileAppender, FileAppender, NullAppender, RewriteAppender (limited), RollingFileAppender, SyslogAppender.</p> |
| <p>Supported Filters include: DenyAllFilter, LevelMatchFilter, LevelRangeFilter, StringMatchFilter.</p> |
| <p>Supported Layouts include: HtmlLayout, PatternLayout, SimpleLayout, TTCCLayout , XmlLayout.</p> |
| <p>Supported Rewrite Policies include: MapRewritePolicy, PropertyRewritePolicy.</p></section><section> |
| <h5><a name="Unsupported_or_Unimplemented_Components"></a>Unsupported or Unimplemented Components</h5> |
| <p>If your configuration contains any of the below components, |
| consider <a href="migration.html#Log4j2ConfigurationFormat">migrating your configuration</a> to the Log4j 2 format.</p><section> |
| <h6><a name="Appenders"></a>Appenders</h6> |
| <ul> |
| |
| <li>JDBCAppender (cannot be mapped to Log4j 2's JdbcAppender)</li> |
| <li>JMSAppender</li> |
| <li>SMTPAppender</li> |
| <li>SocketAppender (Requires the use of the SerializedLayout which is a security risk)</li> |
| <li>SocketHubAppender (Requires the use of the SerializedLayout which is a security risk)</li> |
| <li>TelnetAppender (Security risk)</li> |
| </ul></section><section> |
| <h6><a name="Rewrite_Policies"></a>Rewrite Policies</h6> |
| <ul> |
| |
| <li>ReflectionRewritePolicy</li> |
| <li>Custom rewrite policies since LoggingEvent is currently a no-op.</li> |
| </ul></section><section> |
| <h6><a name="Renderers"></a>Renderers</h6> |
| <p>Log4j 2 currently ignores renderers.</p> |
| <a name="Log4j1.2BridgeLimitations"></a> |
| </section></section></section><section> |
| <h4><a name="Limitations_of_the_Log4j_1.x_bridge"></a>Limitations of the Log4j 1.x bridge</h4> |
| <p>Applications can migrate by just using the bridge without further code changes, |
| if they meet the following requirements:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>They must not access methods and classes internal to the Log4j 1.x implementation such |
| as <code>Appender</code>s, <code>LoggerRepository</code> or <code>Category</code>'s <code>callAppenders</code> method.</li> |
| <li>They must not programmatically configure Log4j.</li> |
| <li>They must not configure by calling the Log4j 1.x classes <code>DOMConfigurator</code> or <code>PropertyConfigurator</code>.</li> |
| </ol></section><section> |
| <h4><a name="When_to_stop_using_the_Log4j_1.x_bridge"></a>When to stop using the Log4j 1.x bridge</h4> |
| <p>Once you have migrated all of your own application and library code under your control, you may not need the bridge anymore. |
| Note that when you use a library/framework that can be configured to use several logging frameworks, |
| then you typically don't need the log4j-1.2-api bridge either, |
| as you may be able to directly configure it to use Log4j v2 instead v1. |
| Some libraries/frameworks even auto-detect the presence of certain logging framework implementations on their classpath, |
| and automagically switch their internal logging delegation accordingly; |
| try simple removing the Log4j v1 dependency instead of replacing it with this bridge, |
| and test if logging from all of your dependencies still work.</p> |
| <p>If you own or can contribute open source to the library you depend on, consider replacing its use of the Log4j v1 API with the v2 API.</p> |
| <p>While the Log4j 1.x bridge supports logging configurations that use the Log4j 1.x properties or XML format, |
| migrating to the new 2.x format is not difficult. |
| The Log4j 2 website contains extensive documentation on the 2.x configuration format. |
| Examples for migrating logging configurations from the v1 format to the v2 format are below.</p> |
| <a name="Log4j2API"></a> |
| </section></section><section> |
| <h3><a name="Option_2:_convert_your_application_to_the_Log4j_2_API_.28log4j-api.29"></a>Option 2: convert your application to the Log4j 2 API (log4j-api)</h3> |
| <p>The other migration option involves changing your application code to use the Log4j 2 API. |
| For the most part, converting from the Log4j 1.x API to Log4j 2 should be fairly simple. Many |
| of the log statements will require no modification. However, where necessary the following changes must be |
| made.</p> |
| <p><img src="../images/whichjar-log4j-api.png" alt="Using log4j 2 via the log4j 2.x API" /></p> |
| <table border="0" class="table table-striped"> |
| <thead> |
| |
| <tr class="a"> |
| <th>Log4j 1.x</th> |
| <th>Log4j 2.x</th></tr> |
| </thead><tbody> |
| |
| <tr class="b"> |
| <td align="left">Package name: <code>org.apache.log4j</code></td> |
| <td><code>org.apache.logging.log4j</code></td></tr> |
| <tr class="a"> |
| <td align="left">Calls to <code>org.apache.log4j.Logger.getLogger()</code></td> |
| <td><code>org.apache.logging.log4j.LogManager.getLogger()</code></td></tr> |
| <tr class="b"> |
| <td align="left">Calls to <code>org.apache.log4j.Logger.getRootLogger()</code> or <code>org.apache.log4j.LogManager.getRootLogger()</code></td> |
| <td><code>org.apache.logging.log4j.LogManager.getRootLogger()</code></td></tr> |
| <tr class="a"> |
| <td align="left">Calls to <code>org.apache.log4j.Logger.getLogger</code> that accept a <code>LoggerFactory</code></td> |
| <td>Remove the <code>org.apache.log4j.spi.LoggerFactory</code> and use one of Log4j 2's other extension mechanisms</td></tr> |
| <tr class="b"> |
| <td align="left">Calls to <code>org.apache.log4j.Logger.getEffectiveLevel()</code></td> |
| <td><code>org.apache.logging.log4j.Logger.getLevel()</code></td></tr> |
| <tr class="a"> |
| <td align="left">Calls to <code>org.apache.log4j.LogManager.shutdown()</code></td> |
| <td>Not needed in version 2 because the Log4j Core now automatically adds a JVM shutdown hook on start up to perform any Core clean ups. Starting in Log4j 2.1, you can specify a custom <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html">ShutdownCallbackRegistry</a> to override the default JVM shutdown hook strategy. Starting in Log4j 2.6, you can use <code>org.apache.logging.log4j.LogManager.shutdown()</code> to initiate shutdown manually.</td></tr> |
| <tr class="b"> |
| <td align="left">Calls to <code>org.apache.log4j.Logger.setLevel()</code> or similar methods</td> |
| <td>Not supported at API level. Equivalent functionality is provided in the Log4j 2 implementation classes, see <code>org.apache.logging.log4j.core.config.Configurator.setLevel()</code>, but this may leave the application susceptible to changes in Log4j 2 internals.</td></tr> |
| <tr class="a"> |
| <td align="left">String concatenation like <code>logger.info("hi " + userName)</code></td> |
| <td>Parameterized messages like <code>logger.info("hi {}", userName)</code></td></tr> |
| <tr class="b"> |
| <td align="left"><a class="externalLink" href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html"><code>org.apache.log4j.MDC</code></a> and <a class="externalLink" href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html"><code>org.apache.log4j.NDC</code></a></td> |
| <td><a href="thread-context.html">Thread Context</a></td></tr> |
| </tbody> |
| </table> |
| <a name="Log4j2ConfigurationFormat"></a> |
| </section><section> |
| <h3><a name="Migrating_logging_configurations_to_the_Log4j_2_format"></a>Migrating logging configurations to the Log4j 2 format</h3> |
| <p>Although the Log4j 2 configuration syntax is different from that of Log4j 1.x, most, if not all, of |
| the same functionality is available.</p><section> |
| <h4><a name="Interpolation"></a>Interpolation</h4> |
| <p>Note that system property interpolation via the <code>${foo}</code> syntax has been extended to allow |
| property lookups from many different sources. See the <a href="lookups.html">Lookups</a> documentation |
| for more details. For example, using a lookup for the system property named <code>catalina.base</code>, |
| in Log4j 1.x, the syntax would be <code>${catalina.base}</code>. In Log4j 2, the syntax would be |
| <code>${sys:catalina.base}</code>.</p></section><section> |
| <h4><a name="Layouts"></a>Layouts</h4> |
| <p>Log4j 1.x has a XMLLayout which is different from the XmlLayout in Log4j 2. The log4j-1.2-api module |
| contains a <code>Log4j1XmlLayout</code> that produces output in the Log4j 1.x format.</p> |
| <p>The Log4j 1.x <code>SimpleLayout</code> can be emulated with PatternLayout “%level - %m%n”.</p> |
| <p>The Log4j 1.x <code>TTCCLayout</code> can be emulated with PatternLayout “%r [%t] %p %c %notEmpty{%ndc }- %m%n”.</p> |
| <p>Both <code>PatternLayout</code> and <code>EnhancedPatternLayout</code> in Log4j 1.x can be replaced with |
| <code>PatternLayout</code> in Log4j 2. The log4j-1.2-api module contains two pattern conversions “%ndc” and “%properties” which |
| can be used to emulate “%x” and “%X” in Log4j 1.x PatternLayout (“%x” and %X" in Log4j 2 have a slightly different format).</p> |
| <p>Below are some example configurations for Log4j 1.x and their counterparts in Log4j 2.</p></section><section> |
| <h4><a name="Sample_1_-_Migrating_a_simple_Console_Appender_configuration"></a>Sample 1 - Migrating a simple Console Appender configuration</h4> |
| <p>Log4j 1.x XML configuration</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd"> |
| <log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'> |
| <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender"> |
| <layout class="org.apache.log4j.PatternLayout"> |
| <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </layout> |
| </appender> |
| <category name="org.apache.log4j.xml"> |
| <priority value="info" /> |
| </category> |
| <Root> |
| <priority value ="debug" /> |
| <appender-ref ref="STDOUT" /> |
| </Root> |
| </log4j:configuration> |
| </code></pre></div> |
| <p>Log4j 2 XML configuration</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><Configuration> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.log4j.xml" level="info"/> |
| <Root level="debug"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </code></pre></div></section><section> |
| <h4><a name="Sample_2_-_Migrating_a_simple_File_Appender.2C_XMLLayout_and_SimpleLayout_configuration"></a>Sample 2 - Migrating a simple File Appender, XMLLayout and SimpleLayout configuration</h4> |
| <p>Log4j 1.x XML configuration</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd"> |
| <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"> |
| <appender name="A1" class="org.apache.log4j.FileAppender"> |
| <param name="File" value="A1.log" /> |
| <param name="Append" value="false" /> |
| <layout class="org.apache.log4j.xml.XMLLayout" /> |
| </appender> |
| <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender"> |
| <layout class="org.apache.log4j.SimpleLayout" /> |
| </appender> |
| <category name="org.apache.log4j.xml"> |
| <priority value="debug" /> |
| <appender-ref ref="A1" /> |
| </category> |
| <root> |
| <priority value ="debug" /> |
| <appender-ref ref="STDOUT" /> |
| </Root> |
| </log4j:configuration> |
| </code></pre></div> |
| <p>Log4j 2 XML configuration</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><Configuration> |
| <Appenders> |
| <File name="A1" fileName="A1.log" append="false"> |
| <Log4j1XmlLayout /> |
| </File> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%level - %m%n"/> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.log4j.xml" level="debug"> |
| <AppenderRef ref="A1"/> |
| </Logger> |
| <Root level="debug"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </code></pre></div></section><section> |
| <h4><a name="Sample_3_-_Migrating_a_SocketAppender_configuration"></a>Sample 3 - Migrating a SocketAppender configuration</h4> |
| <p>Log4j 1.x XML configuration. This example from Log4j 1.x is misleading. The SocketAppender does not |
| actually use a Layout. Configuring one will have no effect.</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd"> |
| <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"> |
| <appender name="A1" class="org.apache.log4j.net.SocketAppender"> |
| <param name="RemoteHost" value="localhost"/> |
| <param name="Port" value="5000"/> |
| <param name="LocationInfo" value="true"/> |
| <layout class="org.apache.log4j.PatternLayout"> |
| <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/> |
| </layout> |
| </appender> |
| <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender"> |
| <layout class="org.apache.log4j.PatternLayout"> |
| <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </layout> |
| </appender> |
| <category name="org.apache.log4j.xml"> |
| <priority value="debug"/> |
| <appender-ref ref="A1"/> |
| </category> |
| <root> |
| <priority value="debug"/> |
| <appender-ref ref="STDOUT"/> |
| </Root> |
| </log4j:configuration> |
| </code></pre></div> |
| <p>Log4j 2 XML configuration</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><Configuration> |
| <Appenders> |
| <Socket name="A1" host="localHost" port="5000"> |
| <PatternLayout pattern="%t %-5p %c{2} - %m%n"/> |
| </Socket> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.log4j.xml" level="debug"> |
| <AppenderRef ref="A1"/> |
| </Logger> |
| <Root level="debug"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </code></pre></div></section><section> |
| <h4><a name="Sample_4_-_Migrating_an_AsyncAppender_and_TTCCLayout_configuration"></a>Sample 4 - Migrating an AsyncAppender and TTCCLayout configuration</h4> |
| <p>Log4j 1.x XML configuration using the AsyncAppender.</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd"> |
| <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true"> |
| <appender name="ASYNC" class="org.apache.log4j.AsyncAppender"> |
| <appender-ref ref="TEMP"/> |
| </appender> |
| <appender name="TEMP" class="org.apache.log4j.FileAppender"> |
| <param name="File" value="temp"/> |
| <layout class="org.apache.log4j.TTCCLayout"> |
| <param name="ThreadPrinting" value="true"/> |
| <param name="CategoryPrefixing" value="true"/> |
| <param name="ContextPrinting" value="true"/> |
| </layout> |
| </appender> |
| <root> |
| <priority value="debug"/> |
| <appender-ref ref="ASYNC"/> |
| </Root> |
| </log4j:configuration> |
| </code></pre></div> |
| <p>Log4j 2 XML configuration.</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><Configuration status="debug"> |
| <Appenders> |
| <File name="TEMP" fileName="temp"> |
| <PatternLayout pattern="%r [%t] %p %c %notEmpty{%ndc }- %m%n"/> |
| </File> |
| <Async name="ASYNC"> |
| <AppenderRef ref="TEMP"/> |
| </Async> |
| </Appenders> |
| <Loggers> |
| <Root level="debug"> |
| <AppenderRef ref="ASYNC"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </code></pre></div></section><section> |
| <h4><a name="Sample_5_-_Migrating_a_configuration_using_AsyncAppender_with_Console_and_File"></a>Sample 5 - Migrating a configuration using AsyncAppender with Console and File</h4> |
| <p>Log4j 1.x XML configuration using the AsyncAppender.</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd"> |
| <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true"> |
| <appender name="ASYNC" class="org.apache.log4j.AsyncAppender"> |
| <appender-ref ref="TEMP"/> |
| <appender-ref ref="CONSOLE"/> |
| </appender> |
| <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender"> |
| <layout class="org.apache.log4j.PatternLayout"> |
| <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </layout> |
| </appender> |
| <appender name="TEMP" class="org.apache.log4j.FileAppender"> |
| <param name="File" value="temp"/> |
| <layout class="org.apache.log4j.PatternLayout"> |
| <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </layout> |
| </appender> |
| <root> |
| <priority value="debug"/> |
| <appender-ref ref="ASYNC"/> |
| </Root> |
| </log4j:configuration> |
| </code></pre></div> |
| <p>Log4j 2 XML configuration. Note that the Async Appender should be configured after the appenders it |
| references. This will allow it to shut down properly.</p> |
| |
| <div class="source"><pre class="prettyprint"><code class="language-xml"><Configuration status="debug"> |
| <Appenders> |
| <Console name="CONSOLE" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </Console> |
| <File name="TEMP" fileName="temp"> |
| <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/> |
| </File> |
| <Async name="ASYNC"> |
| <AppenderRef ref="TEMP"/> |
| <AppenderRef ref="CONSOLE"/> |
| </Async> |
| </Appenders> |
| <Loggers> |
| <Root level="debug"> |
| <AppenderRef ref="ASYNC"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </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> |
