You are viewing a plain text version of this content. The canonical link for it is here.

Posted to notifications@logging.apache.org by "grobmeier (via GitHub)" <gi...@apache.org> on 2024/05/14 22:46:06 UTC

[PR] Rewrote manual intro (logging-log4j2)

grobmeier opened a new pull request, #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581

   Rewriting of the manual intro.
   
   Please comment if you see any missing "fantastic" features that need to be included in the intro or if anything should be removed.
   
   closes #1468 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "grobmeier (via GitHub)" <gi...@apache.org>.

grobmeier commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1603126942


##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming Apache Log4j. 

Review Comment:
   Previously added links are dead. I suggest we are not adding them anymore, except we find other links



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#issuecomment-2115010393

   @grobmeier, I reused common content between `/index.adoc` and `manual/index.adoc` in 8d47758e5c3de70dc46b83dd2f2ee16e84eaaae0. I don't prefer pushing commits to other people's PR branches, but I couldn't think of a way to show the `include:partial$` concept I mentioned earlier. Feel free to revert it if you find the earlier version is better.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611575204


##########
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.

Review Comment:
   > I think this whole paragraph doesn't make sense at all on the benefits of API-vs-implementation separation. I will rewrite this.
   
   I believe it can make sense, but you're right that it's at best unclear. I would suggest something closer to:
   
   > In addition to the Log4j Core reference implementation, Log4j provides a stable facade (i.e., `log4j-api`) which is separate from that implementation, making it straightforward for developers to use Log4j while being confident on a high degree of API forward-compatibility.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611152274


##########
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].

Review Comment:
   I can swear that the 1st link, added by me both to here and to the main page, was correct. I checked via Wayback Machine every single snapshot, but couldn't find it again. :cry: I guess we need to remove it.
   
   I will massage the label of the 2nd link.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1604837045


##########
src/site/antora/modules/ROOT/partials/log4j-features.adoc:
##########
@@ -0,0 +1,43 @@
+////
+    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] that can be configured using log event rates, regular expressions, scripts, time, etc.

Review Comment:
   Fixed in 253e7a7aac1579fa1102489dccf3c77df2369716.



##########
src/site/antora/modules/ROOT/partials/log4j-features.adoc:
##########
@@ -0,0 +1,43 @@
+////
+    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] 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.

Review Comment:
   Fixed in 253e7a7aac1579fa1102489dccf3c77df2369716.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "grobmeier (via GitHub)" <gi...@apache.org>.

grobmeier commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1610609691


##########
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. 

Review Comment:
   No problem, I can work through the comments - thanks for adding them @Chealer 
   Whenever you want to get more involved, please let me or @ppkarwasz know, we are happy about everyone who wants to get their hands dirty :)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609806030


##########
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. 

Review Comment:
   I made a few remarks which require someone more involved (ideally the author) to intervene, but if I still notice simple issues after that's solved, thanks, I will consider.
   Thank you for the link @ppkarwasz !



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "swebb2066 (via GitHub)" <gi...@apache.org>.

swebb2066 commented on PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#issuecomment-2111425573

   > Please comment if you see any missing "fantastic" features that need to be included
   
   What about being able to activate additional logging output or disable some output for one or more modules of the running application by changing the configuration file?
   
   To me this is the super-power that a simpler logging solution misses.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "grobmeier (via GitHub)" <gi...@apache.org>.

grobmeier merged PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.

ppkarwasz commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1604454001


##########
src/site/antora/modules/ROOT/partials/log4j-features.adoc:
##########
@@ -0,0 +1,43 @@
+////
+    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] that can be configured using log event rates, regular expressions, scripts, time, etc.

Review Comment:
   I don't understand the "can be configured using" expression.
   
   Shouldn't it be "Filters based on log event rates, …"?



##########
src/site/antora/modules/ROOT/partials/log4j-features.adoc:
##########
@@ -0,0 +1,43 @@
+////
+    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] 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.

Review Comment:
   I would add a **Reliability** point above this and modify this point to take into account configurability and reliability.
   
   Do we offer the fastest Log4j API implementation possible, probably not: you can obtain a similar or _slightly_ better performance using components from two vendors (QOS.ch and [logfellow/logstash-logback-encoder](https://github.com/logfellow/logstash-logback-encoder)). If you use those solutions, however, you need to restart your application or risk losing log events if you need to make a configuration change (e.g. enable `DEBUG` logging for a single client).



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611152274


##########
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].

Review Comment:
   I can swear that the 1st link, added by me both to here and to the main page, was correct. I checked via Wayback Machine every single snapshot, but couldn't find it again. :cry: I guess we need to remove it.
   
   I will massage the label of the 2nd link.
   
   Thanks so much for the elaborate check @Chealer! :bow: 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609789697


##########
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].

Review Comment:
   The first link is visibly wrong.
   As for the second, the list actually contains 148 projects, which include for example COA(?!). In fact, these are projects which the OpenSSF deemed most critical **to secure**, so it doesn't support the statement as it stands.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609800039


##########
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.

Review Comment:
   Something is wrong in "making it straightforward for application developers which classes and methods to use while ensuring forward compatibility". Perhaps "straightforward to use in a correct and future-proof (forward-compatible) way"?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611160769


##########
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.

Review Comment:
   I think this whole paragraph doesn't make sense at all on the benefits of API-vs-implementation separation. I will rewrite this.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.

ppkarwasz commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611219014


##########
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.

Review Comment:
   Yes, I guess we should start with the advantages of Log4j API, followed by the advantages of Log4j Core. So in order:
   
   1. "No vendor lock-in": the Log4j API and its reference implementation are separate and Log4j API is in permanent LTS-mode. People can use a stable API without breaking changes, while at the same time profiting of major rewrites of the reference implementation.
   2. "A feature-rich API": the API provides 100+ **different** logging methods, even if we ignore the vararg expansions. These methods can even be repurposed to obtain different semantics, using the `Message` and `MessageFactory` abstractions.
   3. "Batteries included", "Reliability" and so on.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.

ppkarwasz commented on PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#issuecomment-2122393778

   @grobmeier, can you merge this?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "grobmeier (via GitHub)" <gi...@apache.org>.

grobmeier commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1603124193


##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########


Review Comment:
   I tried it, but it is a horrible mess and extremely hard for the author to write - at least for me. In my opinion, we should drop this convention. I prefer well formatted text instead of automatic linewrapping. We can talk about this on the mailing list



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.

ppkarwasz commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609288036


##########
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. 

Review Comment:
   @Chealer,
   
   You can follow our documentation rewrite on our [staging website](https://logging.staged.apache.org/log4j/2.x/index.html).
   If we there are typos, grammar or other problems, feel free to use the "Edit" button on the top right side of the page to modify the page in Github and submit a PR.
   
   **Note**: not all the pages have been rewritten yet. At this moment only the #2538 and #2539 pages are new. If you edit other pages, your changes might be lost, when we rewrite them.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1611226939


##########
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.

Review Comment:
   :+1: I will take care of this in #2604.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "grobmeier (via GitHub)" <gi...@apache.org>.

grobmeier commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609003822


##########
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. 

Review Comment:
   Thanks @Chealer . if you like, please create a PR and you can see your contribution in this file :-)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609002533


##########
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. 

Review Comment:
   s/which became Apache Log4j/becoming _Apache Log4j_/



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1602715319


##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming 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.
+
+== Benefits of Log4j
+
+Log4j offers numerous advantages, including:

Review Comment:
   To be coherent with the question-style headers preceding in the page.
   
   ```suggestion
   == What does Log4j offer?
   
   Log4j offers numerous features, including:
   ```



##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming 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.
+
+== Benefits of Log4j
+
+Log4j offers numerous advantages, including:
+
+1. **Easy to use**: Log4j is easy to use and configure. You can get started
+   with just a few lines of code.
+2. **Speed**: Log4j is fast and has a low overhead. For more information see: xref:manual/async.adoc[Asynchronous Loggers]
+3. **Reliable**: Log4j is reliable and has been used in many production applications.
+4. **Audit-ready**: Log4j is designed to be a reliable audit logging framework that 
+   does not lose any events, unlike some competing frameworks.
+5. **Small footprint**: Log4j has a small impact on the garbage collector. For details, see: xref:manual/garbagefree.adoc[garbage-free].
+6. **Extensible**: Log4j is designed to be easily extended using a xref:manual/plugins.adoc[plugin system], 
+   allowing users to customize it to xref:manual/extending.adoc[fit their specific needs].
+7. **Modern Syntax**: Log4j supports xref:manual/api.adoc#LambdaSupport[lambda expressions]
+8. **Integration**: Log4j integrates with numerous other frameworks and libraries.
+9. **ASF Standards**: Developed at the Apache Software Foundation, adhering to rigorous standards and best practices.
+
+== How to learn more?
+
+To get started, learn more about the xref:manual/api.adoc[Log4j API] and it's xref:manual/architecture.adoc[architecture.] 

Review Comment:
   Instead of just linking to API and Architecture pages, I think a question-answer style quick links (just like we have [in the front page](https://logging.apache.org/log4j/2.x/#links)) will be more convenient for users:
   
   ```suggestion
   * 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?]
   ```



##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming Apache Log4j. 

Review Comment:
   **Tip:** I think it would be sweet if we can provide some links to these historical facts.



##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########


Review Comment:
   While it is not strictly required, I'd appreciate it if you can follow [the one-sentence-per-line convention](https://www.google.com/search?q=one+sentence+per+line). @ppkarwasz, @jvz, and I already adhere to that.



##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming 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.
+
+== Benefits of Log4j
+
+Log4j offers numerous advantages, including:
+
+1. **Easy to use**: Log4j is easy to use and configure. You can get started
+   with just a few lines of code.
+2. **Speed**: Log4j is fast and has a low overhead. For more information see: xref:manual/async.adoc[Asynchronous Loggers]
+3. **Reliable**: Log4j is reliable and has been used in many production applications.
+4. **Audit-ready**: Log4j is designed to be a reliable audit logging framework that 
+   does not lose any events, unlike some competing frameworks.
+5. **Small footprint**: Log4j has a small impact on the garbage collector. For details, see: xref:manual/garbagefree.adoc[garbage-free].
+6. **Extensible**: Log4j is designed to be easily extended using a xref:manual/plugins.adoc[plugin system], 
+   allowing users to customize it to xref:manual/extending.adoc[fit their specific needs].
+7. **Modern Syntax**: Log4j supports xref:manual/api.adoc#LambdaSupport[lambda expressions]
+8. **Integration**: Log4j integrates with numerous other frameworks and libraries.
+9. **ASF Standards**: Developed at the Apache Software Foundation, adhering to rigorous standards and best practices.

Review Comment:
   I am sort of hesitant about this entire section, since it duplicates [what we already have in the front page](https://logging.apache.org/log4j/2.x/#features). I suggest moving that content to an Antora `partial` and re-using it both here and in the front page.
   
   ---
   
   I suggest:
   
   ```suggestion
   Easy to use::
   Log4j is easy to use and configure.
   You can xref:5min.adoc[get started] with just a few lines of code.
   
   Performance::
   When configured correctly, Log4j excels at speed.
   See the xref:manual/performance.adoc[Performance] page for details.
   
   Reliable::
   Log4j is reliable and has been used in many production applications.
   No messages will be lost even during reconfiguration.
   
   Extensible::
   Log4j is designed to be easily extended using a xref:manual/plugins.adoc[plugin system], allowing users to customize it to xref:manual/extending.adoc[fit their specific needs].
   
   Integration::
   Log4j integrates with numerous other frameworks and libraries.
   
   ASF Standards::
   Developed at the Apache Software Foundation, Log4j adheres to rigorous standards and best practices.
   ```
   
   Removed _small memory footprint_, since Log4j is the biggest logging API/implementation in the wild. Hence, it is not small by any means, AFAICT.
   
   I am also hesitant to advertise garbage-free in the very first page, since
   1. It is an advanced feature and we already indirectly share it in the performance page (which we reference above)
   1. As @ppkarwasz's recent benchmarks hint, it is not a relevant feature anymore as much as it was in the past thanks to the continuous improvements in the JVM's GC.
   
   I removed _modern syntax, lambda expressions_ too, since all popular logging APIs (SLF4J, Tinylog, etc.) support it. I don't think it qualifies as a selling point.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "vy (via GitHub)" <gi...@apache.org>.

vy commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1603176421


##########
src/site/antora/modules/ROOT/pages/manual/index.adoc:
##########
@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming Apache Log4j. 

Review Comment:
   I know, that is why I said _if we can_. :sweat_smile: I don't know of any, neither could find. :cry:



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Rewrote manual intro (logging-log4j2)

Posted by "Chealer (via GitHub)" <gi...@apache.org>.

Chealer commented on code in PR #2581:
URL: https://github.com/apache/logging-log4j2/pull/2581#discussion_r1609806030


##########
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. 

Review Comment:
   I made a few remarks which require someone more involved (ideally the author) to intervene. If someone can notice me once that's done and I still notice simple issues after that's solved, thanks, I will consider.
   Thank you for the link @ppkarwasz !



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org