| <!-- 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. |
| --> |
| #set($h1='#') |
| #set($h2='##') |
| #set($h3='###') |
| |
| $h1 Apache Log4j 2 |
| |
| 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's architecture. |
| |
| $h2 Features |
| |
| $h3 API Separation |
| |
| 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. |
| |
| 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 [Messages](manual/messages.html) 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 "parameterized logging" format supported by SLF4J, the Log4j API also supports events using |
| the java.text.MessageFormat syntax as well printf-style 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. |
| |
| $h3 Improved Performance |
| |
| 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 [Asynchronous Logging Performance](manual/async.html#Performance) for details. Otherwise, Log4j 2 significantly |
| outperforms Log4j 1.x, Logback and java.util.logging, especially in multi-threaded applications. |
| See [Performance](performance.html) for more information. |
| |
| $h3 Support for multiple APIs |
| |
| 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. |
| |
| $h3 Avoid lock-in |
| |
| 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. |
| |
| $h3 Automatic Reloading of Configurations |
| |
| 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. |
| |
| $h3 Advanced Filtering |
| |
| 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. |
| |
| $h3 Plugin Architecture |
| |
| 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. |
| |
| $h3 Property Support |
| |
| 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 [Lookup](manual/lookups.html) Plugin. |
| |
| $h3 Java 8 Lambda Support |
| |
| 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's |
| [lambda support](manual/api.html#LambdaSupport). 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. |
| |
| $h3 Custom Log Levels |
| |
| In Log4j 2, [custom log levels](manual/customloglevels.html) can easily be defined in code or in configuration. No |
| subclassing is required. |
| |
| $h3 Log Builder API |
| In addition to using one of the many log methods in the Log4j API, log events can be constructed using a builder. See |
| [Log Builder][manual/logbuilder.html] for more information. |
| |
| $h3 Garbage-free |
| |
| During steady state logging, Log4j 2 is [garbage-free](manual/garbagefree.html) in stand-alone applications, and low |
| garbage in web applications. This reduces pressure on the garbage collector and can give better response time performance. |
| |
| $h3 Integrating with Application Servers |
| |
| Version 2.10.0 added the module log4j-appserver to improve integration with Apache Tomcat and Eclipse Jetty. |
| |
| $h3 Cloud Enabled |
| |
| Version 2.12.0 introduced support for accessing Docker container information via a Lookup and for accessing |
| and updating the Log4j configuration through Spring Cloud Configuration. This support was enhanced in |
| version 2.13.0 to add support for accessing Spring Boot properties as well as Kubernetes information. |
| See [Logging in the Cloud](manual/cloud.html) for details. |
| |
| $h3 Compatible with Log4j 1.x |
| |
| The Log4j-1.2-api module of Log4j 2 provides compatiblity for applications using the Log4j 1 logging methods. As |
| of Log4j 2.13.0 Log4j 2 also provides experimental support for Log4j 1.x configuration files. See |
| [Log4j 2 Compatiblity with Log4j 1](manual/compatibility.html) for more information. |
| |
| $h2 Documentation |
| |
| The Log4j 2 User's Guide is available on this [site](manual/index.html) or as a downloadable |
| [PDF](log4j-users-guide.pdf). |
| |
| $h2 Requirements |
| |
| Log4j 2.13.0 and greater require Java 8. Version 2.4 through 2.12.1 required Java 7. Some features require optional |
| dependencies; the documentation for these features will specify the required dependencies. |
| |
| $h2 News |
| |
| Log4j $Log4jReleaseVersion 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. |
| |
| Log4j $Log4jReleaseVersion is the latest release of Log4j. As of Log4j 2.13.0 Log4j 2 requires Java 8 or greater at |
| runtime. This release contains new features and fixes which can be found |
| in the latest [changes report](changes-report.html#a$Log4jReleaseVersion). |
| |
| Log4j 2.14.0 contains a new Layout, [JsonTemplateLayout](manual/json-template-layout.html), that is intended to |
| ultimately replace JsonLayout. As its name suggests it uses a template to define the elements to include in the JSON. |
| This Layout was contributed by the author of the log4j2-logstash-layout at GitHub, and who is now a member of the Log4j community. |
| |
| Log4j 2.14.0 adds support for MongoDB 4 and removes support for MongoDB 2. |
| |
| Log4j $Log4jReleaseVersion maintains binary compatibility with previous releases. |