diff --git a/src/site/antora/modules/ROOT/pages/index.adoc b/src/site/antora/modules/ROOT/pages/index.adoc index 2ccc92b10ca..e06af884540 100644 --- a/src/site/antora/modules/ROOT/pages/index.adoc +++ b/src/site/antora/modules/ROOT/pages/index.adoc @@ -33,31 +33,6 @@ The project is actively maintained by a {logging-services-url}/team-list.html[te [#features] == Features -We share below some highlights from Log4j features. - -Batteries included:: -Log4j bundles a rich set of components to assist various use cases. -* xref:manual/appenders.adoc[Appenders] targeting files, network sockets, databases, SMTP servers, etc. -* xref:manual/layouts.adoc[Layouts] that can render CSV, HTML, JSON, Syslog, etc. formatted outputs -* xref:manual/filters.adoc[Filters] that can be configured using log event rates, regular expressions, scripts, time, etc. -* xref:manual/lookups.adoc[Lookups] for accessing system properties, environment variables, log event fields, etc. - -API separation:: -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. -(See xref:manual/api-separation.adoc[API Separation] for details.) -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. -Check out the xref:manual/api.adoc[Java API], {logging-services-url}/log4j/kotlin[Kotlin API], and {logging-services-url}/log4j/scala[Scala API] pages for further information. - -No vendor lock-in:: -Even though the Log4j API is implemented by the Log4j at its fullest, users can choose to use another logging backend. -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. - -Performance:: -When configured correctly, Log4j can deliver excelling performance without almost any burden on the Java garbage collector. -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. -Check out the xref:manual/performance.adoc[Performance] page for details. - -Extensibility:: -Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend its functionality. -You can easily add your own components (layouts, appenders, filters, etc.) or customizing existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]). -Check out the xref:manual/extending.adoc[Extending Log4j] page. +Below, we share some highlights from Log4j features. + +include::partial$log4j-features.adoc[] \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/manual/index.adoc b/src/site/antora/modules/ROOT/pages/manual/index.adoc index 15f93a160b2..590bc6e5f86 100644 --- a/src/site/antora/modules/ROOT/pages/manual/index.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/index.adoc @@ -16,122 +16,52 @@ //// = Manual -== Welcome to Log4j! - -Almost every large application includes its own logging or tracing API. -In conformance with this rule, the E.U. http://www.semper.org[SEMPER] -project decided to write its own tracing API. This was in early 1996. -After countless enhancements, several incarnations and much work that -API has evolved to become log4j, a popular logging package for Java. The -package is distributed under the https://www.apache.org/licenses/LICENSE-2.0[Apache Software -License], a fully-fledged open source license certified by the -http://www.opensource.org[open source] initiative. The latest log4j -version, including full-source code, class files and documentation can -be found at -https://logging.apache.org/log4j/2.x/index.html[*https://logging.apache.org/log4j/2.x/index.html*]. - -Inserting log statements into code is a low-tech method for debugging -it. It may also be the only way because debuggers are not always -available or applicable. This is usually the case for multithreaded -applications and distributed applications at large. - -Experience indicates that logging was an important component of the -development cycle. It offers several advantages. It provides precise -_context_ about a run of the application. Once inserted into the code, -the generation of logging output requires no human intervention. -Moreover, log output can be saved in persistent medium to be studied at -a later time. In addition to its use in the development cycle, a -sufficiently rich logging package can also be viewed as an auditing -tool. - -As Brian W. Kernighan and Rob Pike put it in their truly excellent book -_"The Practice of Programming":_ - -____ -As personal choice, we tend not to use debuggers beyond getting a stack -trace or the value of a variable or two. One reason is that it is easy -to get lost in details of complicated data structures and control flow; -we find stepping through a program less productive than thinking harder -and adding output statements and self-checking code at critical places. -Clicking over statements takes longer than scanning the output of -judiciously-placed displays. It takes less time to decide where to put -print statements than to single-step to the critical section of code, -even assuming we know where that is. More important, debugging -statements stay with the program; debugging sessions are transient. -____ - -Logging does have its drawbacks. It can slow down an application. If too -verbose, it can cause scrolling blindness. To alleviate these concerns, -log4j is designed to be reliable, fast and extensible. Since logging is -rarely the main focus of an application, the log4j API strives to be -simple to understand and to use. - -== Log4j 2 - -Log4j 1 has been widely adopted and used in many applications. -However, through the years development on it has slowed down. It has -become more difficult to maintain due to its need to be compliant with -very old versions of Java and became -https://blogs.apache.org/foundation/entry/apache_logging_services_project_announces[End -of Life] in August 2015. Its alternative, SLF4J/Logback made many needed -improvements to the framework. So why bother with Log4j 2? Here are a -few of the reasons. - -1. Log4j 2 is designed to be usable as an audit logging framework. Both -Log4j 1.x and Logback will lose events while reconfiguring. Log4j 2 will -not. In Logback, exceptions in Appenders are never visible to the -application. In Log4j 2 Appenders can be configured to allow the -exception to percolate to the application. -2. Log4j 2 contains next-generation xref:manual/async.adoc[Asynchronous -Loggers] based on the https://lmax-exchange.github.io/disruptor/[LMAX -Disruptor library]. In multi-threaded scenarios Asynchronous Loggers -have 10 times higher throughput and orders of magnitude lower latency -than Log4j 1.x and Logback. -3. Log4j 2 is xref:manual/garbagefree.adoc[garbage free] for stand-alone -applications, and low garbage for web applications during steady state -logging. This reduces pressure on the garbage collector and can give -better response time performance. -4. Log4j 2 uses a xref:manual/plugins.adoc[Plugin system] that makes it -extremely easy to xref:manual/extending.adoc[extend the framework] by adding -new xref:manual/appenders.adoc[Appenders], xref:manual/filters.adoc[Filters], -xref:manual/layouts.adoc[Layouts], xref:manual/lookups.adoc[Lookups], and Pattern -Converters without requiring any changes to Log4j. -5. Due to the Plugin system configuration is simpler. Entries in the -configuration do not require a class name to be specified. -6. Support for xref:manual/customloglevels.adoc[custom log levels]. Custom log -levels can be defined in code or in configuration. -7. Support for xref:manual/api.adoc#LambdaSupport[lambda expressions]. Client -code running on Java 8 can use lambda expressions to lazily construct a -log message only if the requested log level is enabled. Explicit level -checks are not needed, resulting in cleaner code. -8. Support for xref:manual/messages.adoc[Message objects]. 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 xref:manual/layouts.adoc[Layouts], -xref:manual/filters.adoc[Filters] and xref:manual/lookups.adoc[Lookups] to manipulate -them. -9. Log4j 1.x supports Filters on Appenders. Logback added TurboFilters -to allow filtering of events before they are processed by a Logger. -Log4j 2 supports Filters that can be configured to process events before -they are handled by a Logger, as they are processed by a Logger or on an -Appender. -10. Many Logback Appenders do not accept a Layout and will only send -data in a fixed format. Most Log4j 2 Appenders accept a Layout, allowing -the data to be transported in any format desired. -11. Layouts in Log4j 1.x and Logback return a String. This resulted in -the problems discussed at -http://logback.qos.ch/manual/encoders.html[Logback Encoders]. Log4j 2 -takes the simpler approach that xref:manual/layouts.adoc[Layouts] always return -a byte array. This has the advantage that it means they can be used in -virtually any Appender, not just the ones that write to an OutputStream. -12. The xref:manual/appenders.adoc#SyslogAppender[Syslog Appender] supports -both TCP and UDP as well as support for the BSD syslog and the -http://tools.ietf.org/html/rfc5424[RFC 5424] formats. -13. Log4j 2 takes advantage of Java 5 concurrency support and performs -locking at the lowest level possible. Log4j 1.x has known deadlock -issues. Many of these are fixed in Logback but many Logback classes -still require synchronization at a fairly high level. -14. It is an Apache Software Foundation project following the community -and support model used by all ASF projects. If you want to contribute or -gain the right to commit changes just follow the path outlined at -http://jakarta.apache.org/site/contributing.html[Contributing]. +== Welcome to Apache Log4j! + +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. +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]. +The project is actively maintained by a {logging-services-url}/team-list.html[team] of several volunteers and {logging-services-url}/support[support]ed by a big community. + +Logging is an essential part of the software development process. +It provides a way to track the flow of execution in a program, allowing developers +to understand the application's behavior without needing a debugger. +This is particularly useful when tracking bugs or understanding why a particular code runs slowly. + +The original concept for Log4j was conceived in early 1996 when the +E.U. SEMPER project decided to develop its own tracing API. +In 2003, the project was donated to the Apache Software Foundation, which became Apache Log4j. + +Since then, Log4j has seen numerous releases and has become a widely adopted solution. + +== When should you use Log4j? + +Log4j is an excellent choice for any Java application that needs logging capabilities. +It is user-friendly, fast, and flexible. You can use it to log messages at +different levels of severity, from debug to fatal, and you can configure it to +log messages to various destinations, such as files, databases, or the console. + +== When not to use Log4j? + +While Log4j is a highly suitable choice for many applications, +it may be challenging to locate the information you require when +logging a high volume of messages. +Additionally, logging can impact your application's performance. + +Log4j offers solutions to address these concerns. However, if you are in +a unique situation where you are concerned about logging overhead or volume, you may wish +to consider not using logging at all. + +== What does Log4j offer? + +Log4j offers numerous features, including: + +include::partial$log4j-features.adoc[] + +== How to learn more? + +* xref:manual/installation.adoc[How can I install Log4j?] +* xref:manual/configuration.adoc[How can I configure Log4j?] +* xref:manual/api.adoc[How can I use Log4j API?] +* xref:manual/performance.adoc[How can I tune my Log4j setup for performance?] +* xref:manual/migration.adoc[How can I migrate from Log4j 1 to Log4j 2]? +* xref:manual/plugins.adoc[What are Log4j plugins] and xref:manual/extending.adoc[how can I use them to extend Log4j?] diff --git a/src/site/antora/modules/ROOT/partials/log4j-features.adoc b/src/site/antora/modules/ROOT/partials/log4j-features.adoc new file mode 100644 index 00000000000..f7289e93fe4 --- /dev/null +++ b/src/site/antora/modules/ROOT/partials/log4j-features.adoc @@ -0,0 +1,47 @@ +//// + 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. +//// + +Batteries included:: +Log4j bundles a rich set of components to assist various use cases. +* xref:manual/appenders.adoc[Appenders] targeting files, network sockets, databases, SMTP servers, etc. +* xref:manual/layouts.adoc[Layouts] that can render CSV, HTML, JSON, Syslog, etc. formatted outputs +* xref:manual/filters.adoc[Filters] based on log event rates, regular expressions, scripts, time, etc. +* xref:manual/lookups.adoc[Lookups] for accessing system properties, environment variables, log event fields, etc. + +API separation:: +The API for Log4j (i.e., `log4j-api`) is separate from the implementation (i.e., `log4j-core`), making it straightforward for application developers which classes and methods to use while ensuring forward compatibility. +(See xref:manual/api-separation.adoc[API Separation] for details.) +The Log4j API also provides the most feature-rich logging facade in the market; support for various `Message` types (such as `Object` or `Map`) besides plain `String`, lambda expressions, parametrized logging, markers, levels, diagnostic contexts (aka. MDC/NDC), etc. +Check out the xref:manual/api.adoc[Java API], {logging-services-url}/log4j/kotlin[Kotlin API], and {logging-services-url}/log4j/scala[Scala API] pages for further information. + +No vendor lock-in:: +Even though Log4j implements the Log4j API at its fullest, users can use another logging backend. +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. + +Reliability:: +Log4j is built with solid reliability in mind. +It can automatically reload its configuration upon modification and will do so without losing log events while reconfiguration occurs. + +Performance:: +When configured correctly, Log4j can deliver excelling performance without almost any burden on the Java garbage collector, and it will do so without sacrificing reliability. +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. +Check out the xref:manual/performance.adoc[Performance] page for details. + +Extensibility:: +Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend functionality. +You can easily add your components (layouts, appenders, filters, etc.) or customize existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]). +Check out the xref:manual/extending.adoc[Extending Log4j] page.