|
| 1 | +//// |
| 2 | + Licensed to the Apache Software Foundation (ASF) under one or more |
| 3 | + contributor license agreements. See the NOTICE file distributed with |
| 4 | + this work for additional information regarding copyright ownership. |
| 5 | + The ASF licenses this file to You under the Apache License, Version 2.0 |
| 6 | + (the "License"); you may not use this file except in compliance with |
| 7 | + the License. You may obtain a copy of the License at |
| 8 | + |
| 9 | + https://www.apache.org/licenses/LICENSE-2.0 |
| 10 | + |
| 11 | + Unless required by applicable law or agreed to in writing, software |
| 12 | + distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | + See the License for the specific language governing permissions and |
| 15 | + limitations under the License. |
| 16 | +//// |
| 17 | +
|
| 18 | += Apache Log4j |
| 19 | +
|
| 20 | +Apache Log4j is a versatile, industrial-grade Java logging framework composed of an API, its implementation, and components to assist the deployment for various use cases. |
| 21 | +Log4j is https://security.googleblog.com/2021/12/apache-log4j-vulnerability.html[used by 8% of the Maven ecosystem] and listed as one of https://docs.google.com/spreadsheets/d/1ONZ4qeMq8xmeCHX03lIgIYE4MEXVfVL6oj05lbuXTDM/edit#gid=1024997528[the top 100 critical open source software projects]. |
| 22 | +The project is actively maintained by a link:team.html[team] of several volunteers and xref:support.adoc[support]ed by a big community. |
| 23 | +
|
| 24 | +[#links] |
| 25 | +== Quick links |
| 26 | +- link:maven-artifacts.html[How can I add Log4j artifacts to my Maven/Ivy/Gradle project?] |
| 27 | +- link:manual/usage.html?[How can I use the Log4j API?] |
| 28 | +- link:manual/configuration.html[How can I configure my `log4j2.xml`?] |
| 29 | +- link:release-notes.html[Where are the release notes?] |
| 30 | +- link:support.html[**I need help!**] |
| 31 | +
|
| 32 | +[#features] |
| 33 | +== Features |
| 34 | +
|
| 35 | +We share below some highlights from Log4j features. |
| 36 | +
|
| 37 | +Batteries included:: |
| 38 | +Log4j bundles a rich set of components to assist various use cases. |
| 39 | +* link:manual/appenders.html[Appenders] targeting files, network sockets, databases, SMTP servers, etc. |
| 40 | +* link:manual/layouts.html[Layouts] that can render CSV, HTML, JSON, Syslog, etc. formatted outputs |
| 41 | +* link:manual/filters.html[Filters] that can be configured using log event rates, regular expressions, scripts, time, etc. |
| 42 | +* link:manual/lookups.html[Lookups] for accessing system properties, environment variables, log event fields, etc. |
| 43 | +
|
| 44 | +API separation:: |
| 45 | +The API for Log4j (i.e., `log4j-api`) is separate from the implementation (i.e., `log4j-core`) making it clear for application developers which classes and methods they can use while ensuring forward compatibility. |
| 46 | +(See link:manual/api-separation.html[API Separation] for details.) |
| 47 | +The Log4j API also provides the most feature rich logging facade in the market; support for various `Message` types (`Object`, `Map`, etc.) besides plain `String`, lambda expressions, parametrized logging, markers, levels, diagnostic contexts (aka. MDC/NDC), etc. |
| 48 | +Check out the link:manual/api.html[Java API], link:/log4j/kotlin[Kotlin API], and link:/log4j/scala[Scala API] pages for further information. |
| 49 | +
|
| 50 | +No vendor lock-in:: |
| 51 | +Even though the Log4j API is implemented by the Log4j at its fullest, users can choose to use another logging backend. |
| 52 | +This can be achieved by either using another backend implementing the Log4j API, or forwarding Log4j API calls to another logging facade (e.g., SLF4J) and using a backend for that particular facade. |
| 53 | +
|
| 54 | +Performance:: |
| 55 | +When configured correctly, Log4j can deliver excelling performance without almost any burden on the Java garbage collector. |
| 56 | +This is made possible via an asynchronous logger founded on the https://lmax-exchange.github.io/disruptor/[LMAX Disruptor] technology (having its roots in the demanding industry of financial trading) and the garbage-free features baked at hot paths. |
| 57 | +Check out the link:performance.html[Performance] page for details. |
| 58 | +
|
| 59 | +Extensibility:: |
| 60 | +Log4j contains a fully-fledged xref:manual/plugins.html[plugin support] that users can leverage to extend its functionality. |
| 61 | +You can easily add your own components (layouts, appenders, filters, etc.) or customizing existing ones (e.g., adding new directives to the link:manual/layouts.html#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]). |
| 62 | +Check out the link:manual/extending.html[Extending Log4j] page. |
| 63 | +
|
| 64 | +[#requirements] |
| 65 | +== Requirements |
| 66 | +
|
| 67 | +Log4j 3 runtime requires a minimum of Java 17. |
| 68 | +For support for older versions of Java see the link:http://logging.apache.org/2.x[Log4j 2 site]. |
| 69 | +
|
| 70 | +[#compat] |
| 71 | +== Compatibility |
| 72 | +
|
| 73 | +Application code written using the Log4j 2 API should be binary compatible with Log4j 3. |
| 74 | +Custom plugins written for Log4j 2 may need minor changes when compiling with Log4j 3 as some package names have changed. |
| 75 | +
|
| 76 | +The `log4j-1.2-api` module provides compatibility for applications using the Log4j 1 logging methods. |
| 77 | +Log4j 3, just like Log4j 2, also provides experimental support for Log4j 1 configuration files. |
| 78 | +See link:manual/log4j1-compat.html[Log4j 3 compatibility with Log4j 1] for more information. |
0 commit comments