Google Git
Sign in
apache / logging-log4j-site / ac1db7db1c543d59f5028116b17c5a47140bccc2 / . / log4j-2.12.0 / index.html
blob: 1a651fbfc92d0744722e36cc150e8f89bc70709f [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Generated by Apache Maven Doxia at 2019-06-23 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Log4j &#x2013; Apache Log4j 2 - Apache Log4j 2</title>
<link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="./css/site.css" type="text/css" />
<script type="text/javascript" src="./js/jquery.min.js"></script>
<script type="text/javascript" src="./js/bootstrap.min.js"></script>
<script type="text/javascript" src="./js/prettify.min.js"></script>
<script type="text/javascript" src="./js/site.js"></script>
<meta name="Date-Revision-yyyymmdd" content="20190623" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<a href="https://logging.apache.org/">
<img class="logo-left" src="./images/ls-logo.jpg" alt="Apache logging services logo" />
</a>
<img class="logo-right" src="./images/logo.png" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="https://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="https://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../" title="Logging Services">Logging Services</a>
</li>
<li>
<a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a>
</li>
<li>
<a href="https://github.com/apache/logging-log4j2" class="external" target="_blank" title="GitHub">GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none active">
<a href="index.html" title="About">About</a>
</li>
<li class="none">
<a href="download.html" title="Download">Download</a>
</li>
<li class="collapsed">
<a href="javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="collapsed">
<a href="maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts">Maven, Ivy, Gradle Artifacts</a>
</li>
<li class="none">
<a href="runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a>
</li>
<li class="none">
<a href="changelog.html" title="Changelog">Changelog</a>
</li>
<li class="none">
<a href="faq.html" title="FAQ">FAQ</a>
</li>
<li class="collapsed">
<a href="performance.html" title="Performance">Performance</a>
</li>
<li class="none">
<a href="articles.html" title="Articles and Tutorials">Articles and Tutorials</a>
</li>
<li class="none">
<a href="thanks.html" title="Thanks">Thanks</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-pencil"></i>For Contributors</li>
<li class="none">
<a href="build.html" title="Building Log4j from Source">Building Log4j from Source</a>
</li>
<li class="none">
<a href="guidelines.html" title="Guidelines">Guidelines</a>
</li>
<li class="none">
<a href="javastyle.html" title="Style Guide">Style Guide</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="manual/index.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="collapsed">
<a href="manual/api.html" title="Java API">Java API</a>
</li>
<li class="none">
<a href="manual/scala-api.html" title="Scala API">Scala API</a>
</li>
<li class="collapsed">
<a href="manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="collapsed">
<a href="manual/usage.html" title="Usage">Usage</a>
</li>
<li class="collapsed">
<a href="manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
</li>
<li class="collapsed">
<a href="manual/lookups.html" title="Lookups">Lookups</a>
</li>
<li class="collapsed">
<a href="manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="collapsed">
<a href="manual/filters.html" title="Filters">Filters</a>
</li>
<li class="collapsed">
<a href="manual/async.html" title="Async Loggers">Async Loggers</a>
</li>
<li class="collapsed">
<a href="manual/garbagefree.html" title="Garbage-free Logging">Garbage-free Logging</a>
</li>
<li class="none">
<a href="manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
<li class="collapsed">
<a href="manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="manual/customconfig.html" title="Programmatic Log4j Configuration">Programmatic Log4j Configuration</a>
</li>
<li class="collapsed">
<a href="manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-tags"></i>Related Projects</li>
<li class="none">
<a href="http://logging.apache.org/log4j/scala/index.html" class="external" target="_blank" title="Log4j-Scala">Log4j-Scala</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-tags"></i>Legacy</li>
<li class="none">
<a href="http://logging.apache.org/log4j/1.2/" class="external" target="_blank" title="Log4j 1.2">Log4j 1.2</a>
</li>
<li class="none">
<a href="http://logging.apache.org/log4j/log4j-2.3/" class="external" target="_blank" title="Log4j 2.3">Log4j 2.3</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="log4j-core/index.html" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a>
</li>
<li class="none">
<a href="log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="log4j-jul/index.html" title="JUL Adapter">JUL Adapter</a>
</li>
<li class="none">
<a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="log4j-flume-ng/index.html" title="Apache Flume Appender">Apache Flume Appender</a>
</li>
<li class="none">
<a href="log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
<li class="none">
<a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a>
</li>
<li class="none">
<a href="log4j-web/index.html" title="Log4j Web Application Support">Log4j Web Application Support</a>
</li>
<li class="none">
<a href="log4j-appserver/index.html" title="Log4j Application Server Integration">Log4j Application Server Integration</a>
</li>
<li class="none">
<a href="log4j-couchdb/index.html" title="Log4j CouchDB appender">Log4j CouchDB appender</a>
</li>
<li class="none">
<a href="log4j-mongodb2/index.html" title="Log4j MongoDB2 appender">Log4j MongoDB2 appender</a>
</li>
<li class="none">
<a href="log4j-mongodb3/index.html" title="Log4j MongoDB3 appender">Log4j MongoDB3 appender</a>
</li>
<li class="none">
<a href="log4j-cassandra/index.html" title="Log4j Cassandra appender">Log4j Cassandra appender</a>
</li>
<li class="none">
<a href="log4j-iostreams/index.html" title="Log4j IO Streams">Log4j IO Streams</a>
</li>
<li class="none">
<a href="log4j-liquibase/index.html" title="Log4j Liquibase Binding">Log4j Liquibase Binding</a>
</li>
<li class="none">
<a href="log4j-docker/index.html" title="Log4j Docker Support">Log4j Docker Support</a>
</li>
<li class="none">
<a href="log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client">Log4j Spring Cloud Config Client</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="./images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- 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>Apache Log4j 2</h1>
<p>Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j 1.x, and provides many of the improvements available in Logback while fixing some inherent problems in Logback&#x2019;s architecture.</p>
<div class="section">
<h2><a name="Features"></a>Features</h2>
<div class="section">
<h3><a name="API_Separation"></a>API Separation</h3>
<p>The API for Log4j is separate from the implementation making it clear for application developers which classes and methods they can use while ensuring forward compatibility. This allows the Log4j team to improve the implementation safely and in a compatible manner.</p>
<p>The Log4j API is a logging facade that may, of course, be used with the Log4j implementation, but may also be used in front of other logging implementations such as Logback. The Log4j API has several advantages over SLF4J: 1. The Log4j API supports logging <a href="manual/messages.html">Messages</a> instead of just Strings. 2. The Log4j API supports lambda expressions. 3. The Log4j API provides many more logging methods than SLF4J. 4. In addition to the &#x201c;parameterized logging&#x201d; format supported by SLF4J, the Log4j API also supports events using the java.text.MessageFormat syntax as well printf-sytle messages. 5. The Log4j API provides a LogManager.shutdown() method. The underlying logging implementation must implement the Terminable interface for the method to have effect. 6. Other constructs such as Markers, log Levels, and ThreadContext (aka MDC) are fully supported.</p></div>
<div class="section">
<h3><a name="Improved_Performance"></a>Improved Performance</h3>
<p>Log4j 2 contains next-generation Asynchronous Loggers based on the LMAX Disruptor library. In multi-threaded scenarios Asynchronous Loggers have 18 times higher throughput and orders of magnitude lower latency than Log4j 1.x and Logback. See <a href="manual/async.html#Performance">Asynchronous Logging Performance</a> for details. Otherwise, Log4j 2 significantly outperforms Log4j 1.x, Logback and java.util.logging, especially in multi-threaded applications. See <a href="performance.html">Performance</a> for more information.</p></div>
<div class="section">
<h3><a name="Support_for_multiple_APIs"></a>Support for multiple APIs</h3>
<p>While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the Log4j 1.2, SLF4J, Commons Logging and java.util.logging (JUL) APIs.</p></div>
<div class="section">
<h3><a name="Avoid_lock-in"></a>Avoid lock-in</h3>
<p>Applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant library as their logger implementation with the log4j-to-slf4j adapter.</p></div>
<div class="section">
<h3><a name="Automatic_Reloading_of_Configurations"></a>Automatic Reloading of Configurations</h3>
<p>Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, it will do so without losing log events while reconfiguration is taking place.</p></div>
<div class="section">
<h3><a name="Advanced_Filtering"></a>Advanced Filtering</h3>
<p>Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, and other components in the Log event. Filtering can be specified to apply to all events before being passed to Loggers or as they pass through Appenders. In addition, filters can also be associated with Loggers. Unlike Logback, you can use a common Filter class in any of these circumstances.</p></div>
<div class="section">
<h3><a name="Plugin_Architecture"></a>Plugin Architecture</h3>
<p>Log4j uses the plugin pattern to configure components. As such, you do not need to write code to create and configure an Appender, Layout, Pattern Converter, and so on. Log4j automatically recognizes plugins and uses them when a configuration references them.</p></div>
<div class="section">
<h3><a name="Property_Support"></a>Property Support</h3>
<p>You can reference properties in a configuration, Log4j will directly replace them, or Log4j will pass them to an underlying component that will dynamically resolve them. Properties come from values defined in the configuration file, system properties, environment variables, the ThreadContext Map, and data present in the event. Users can further customize the property providers by adding their own <a href="manual/lookups.html">Lookup</a> Plugin.</p></div>
<div class="section">
<h3><a name="Java_8_Lambda_Support"></a>Java 8 Lambda Support</h3>
<p>Previously, if a log message was expensive to construct, you would often explicitly check if the requested log level is enabled before constructing the message. Client code running on Java 8 can benefit from Log4j&#x2019;s <a href="manual/api.html#LambdaSupport">lambda support</a>. Since Log4j will not evaluate a lambda expression if the requested log level is not enabled, the same effect can be achieved with less code.</p></div>
<div class="section">
<h3><a name="Custom_Log_Levels"></a>Custom Log Levels</h3>
<p>In Log4j 2, <a href="manual/customloglevels.html">custom log levels</a> can easily be defined in code or in configuration. No subclassing is required.</p></div>
<div class="section">
<h3><a name="Garbage-free"></a>Garbage-free</h3>
<p>During steady state logging, Log4j 2 is <a href="manual/garbagefree.html">garbage-free</a> in stand-alone applications, and low garbage in web applications. This reduces pressure on the garbage collector and can give better response time performance.</p></div>
<div class="section">
<h3><a name="Integrating_with_Application_Servers"></a>Integrating with Application Servers</h3>
<p>Version 2.10.0 introduces a the module log4j-appserver to improve integration with Apache Tomcat and Eclipse Jetty.</p></div>
<div class="section">
<h3><a name="Cloud_Enabled"></a>Cloud Enabled</h3>
<p>Version 2.12.0 introduces support for accessing Dcoker container information via a Lookup and for accessing and updating the Log4j configuration through Spring Clooud Configuration. See <a href="manual/cloud.html">Logging in the Cloud</a> for details.</p></div></div>
<div class="section">
<h2><a name="Documentation"></a>Documentation</h2>
<p>The Log4j 2 User&#x2019;s Guide is available on this <a href="manual/index.html">site</a> or as a downloadable <a href="log4j-users-guide.pdf">PDF</a>.</p></div>
<div class="section">
<h2><a name="Requirements"></a>Requirements</h2>
<p>Log4j 2.4 and greater requires Java 7, versions 2.0-alpha1 to 2.3 required Java 6. Some features require optional dependencies; the documentation for these features specifies the dependencies.</p></div>
<div class="section">
<h2><a name="News"></a>News</h2>
<p>Log4j 2.12.0 is now available for production. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter is available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for Apache Commons Logging, SLF4J, and java.util.logging.</p>
<p>Log4j 2.12.0 is the latest release of Log4j and contains several bug fixes that were found after the release of Log4j 2.6. The list of fixes can be found in the latest <a href="changes-report.html#a2.12.0">changes report</a>.</p>
<p>Note that subsequent to the release of Log4j 2.6 a minor source incompatibility with prior release was found due to the addition of new methods to the Logger interface. If you have code that does:</p>
<div class="source">
<div class="source">
<pre>logger.error(null, &quot;This is the log message&quot;, throwable);
</pre></div></div>
<p>or similar with any log level you will get a compiler error saying the reference is ambiguous. To correct this either do:</p>
<div class="source">
<div class="source">
<pre>logger.error(&quot;This is the log message&quot;, throwable);
</pre></div></div>
<p>or</p>
<div class="source">
<div class="source">
<pre>logger.error((Marker) null, &quot;This is the log message&quot;, throwable);
</pre></div></div>
<p>Log4j 2.12.0 maintains binary compatibility with previous releases.</p></div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2019 <a class="external" href="https://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>