|
16 | 16 | //// |
17 | 17 | = Manual |
18 | 18 |
|
19 | | -== Welcome to Log4j! |
20 | | -
|
21 | | -Almost every large application includes its own logging or tracing API. |
22 | | -In conformance with this rule, the E.U. http://www.semper.org[SEMPER] |
23 | | -project decided to write its own tracing API. This was in early 1996. |
24 | | -After countless enhancements, several incarnations and much work that |
25 | | -API has evolved to become log4j, a popular logging package for Java. The |
26 | | -package is distributed under the https://www.apache.org/licenses/LICENSE-2.0[Apache Software |
27 | | -License], a fully-fledged open source license certified by the |
28 | | -http://www.opensource.org[open source] initiative. The latest log4j |
29 | | -version, including full-source code, class files and documentation can |
30 | | -be found at |
31 | | -https://logging.apache.org/log4j/2.x/index.html[*https://logging.apache.org/log4j/2.x/index.html*]. |
32 | | -
|
33 | | -Inserting log statements into code is a low-tech method for debugging |
34 | | -it. It may also be the only way because debuggers are not always |
35 | | -available or applicable. This is usually the case for multithreaded |
36 | | -applications and distributed applications at large. |
37 | | -
|
38 | | -Experience indicates that logging was an important component of the |
39 | | -development cycle. It offers several advantages. It provides precise |
40 | | -_context_ about a run of the application. Once inserted into the code, |
41 | | -the generation of logging output requires no human intervention. |
42 | | -Moreover, log output can be saved in persistent medium to be studied at |
43 | | -a later time. In addition to its use in the development cycle, a |
44 | | -sufficiently rich logging package can also be viewed as an auditing |
45 | | -tool. |
46 | | -
|
47 | | -As Brian W. Kernighan and Rob Pike put it in their truly excellent book |
48 | | -_"The Practice of Programming":_ |
49 | | -
|
50 | | -____ |
51 | | -As personal choice, we tend not to use debuggers beyond getting a stack |
52 | | -trace or the value of a variable or two. One reason is that it is easy |
53 | | -to get lost in details of complicated data structures and control flow; |
54 | | -we find stepping through a program less productive than thinking harder |
55 | | -and adding output statements and self-checking code at critical places. |
56 | | -Clicking over statements takes longer than scanning the output of |
57 | | -judiciously-placed displays. It takes less time to decide where to put |
58 | | -print statements than to single-step to the critical section of code, |
59 | | -even assuming we know where that is. More important, debugging |
60 | | -statements stay with the program; debugging sessions are transient. |
61 | | -____ |
62 | | -
|
63 | | -Logging does have its drawbacks. It can slow down an application. If too |
64 | | -verbose, it can cause scrolling blindness. To alleviate these concerns, |
65 | | -log4j is designed to be reliable, fast and extensible. Since logging is |
66 | | -rarely the main focus of an application, the log4j API strives to be |
67 | | -simple to understand and to use. |
68 | | -
|
69 | | -== Log4j 2 |
70 | | -
|
71 | | -Log4j 1 has been widely adopted and used in many applications. |
72 | | -However, through the years development on it has slowed down. It has |
73 | | -become more difficult to maintain due to its need to be compliant with |
74 | | -very old versions of Java and became |
75 | | -https://blogs.apache.org/foundation/entry/apache_logging_services_project_announces[End |
76 | | -of Life] in August 2015. Its alternative, SLF4J/Logback made many needed |
77 | | -improvements to the framework. So why bother with Log4j 2? Here are a |
78 | | -few of the reasons. |
79 | | -
|
80 | | -1. Log4j 2 is designed to be usable as an audit logging framework. Both |
81 | | -Log4j 1.x and Logback will lose events while reconfiguring. Log4j 2 will |
82 | | -not. In Logback, exceptions in Appenders are never visible to the |
83 | | -application. In Log4j 2 Appenders can be configured to allow the |
84 | | -exception to percolate to the application. |
85 | | -2. Log4j 2 contains next-generation xref:manual/async.adoc[Asynchronous |
86 | | -Loggers] based on the https://lmax-exchange.github.io/disruptor/[LMAX |
87 | | -Disruptor library]. In multi-threaded scenarios Asynchronous Loggers |
88 | | -have 10 times higher throughput and orders of magnitude lower latency |
89 | | -than Log4j 1.x and Logback. |
90 | | -3. Log4j 2 is xref:manual/garbagefree.adoc[garbage free] for stand-alone |
91 | | -applications, and low garbage for web applications during steady state |
92 | | -logging. This reduces pressure on the garbage collector and can give |
93 | | -better response time performance. |
94 | | -4. Log4j 2 uses a xref:manual/plugins.adoc[Plugin system] that makes it |
95 | | -extremely easy to xref:manual/extending.adoc[extend the framework] by adding |
96 | | -new xref:manual/appenders.adoc[Appenders], xref:manual/filters.adoc[Filters], |
97 | | -xref:manual/layouts.adoc[Layouts], xref:manual/lookups.adoc[Lookups], and Pattern |
98 | | -Converters without requiring any changes to Log4j. |
99 | | -5. Due to the Plugin system configuration is simpler. Entries in the |
100 | | -configuration do not require a class name to be specified. |
101 | | -6. Support for xref:manual/customloglevels.adoc[custom log levels]. Custom log |
102 | | -levels can be defined in code or in configuration. |
103 | | -7. Support for xref:manual/api.adoc#LambdaSupport[lambda expressions]. Client |
104 | | -code running on Java 8 can use lambda expressions to lazily construct a |
105 | | -log message only if the requested log level is enabled. Explicit level |
106 | | -checks are not needed, resulting in cleaner code. |
107 | | -8. Support for xref:manual/messages.adoc[Message objects]. Messages allow |
108 | | -support for interesting and complex constructs to be passed through the |
109 | | -logging system and be efficiently manipulated. Users are free to create |
110 | | -their own `Message` types and write custom xref:manual/layouts.adoc[Layouts], |
111 | | -xref:manual/filters.adoc[Filters] and xref:manual/lookups.adoc[Lookups] to manipulate |
112 | | -them. |
113 | | -9. Log4j 1.x supports Filters on Appenders. Logback added TurboFilters |
114 | | -to allow filtering of events before they are processed by a Logger. |
115 | | -Log4j 2 supports Filters that can be configured to process events before |
116 | | -they are handled by a Logger, as they are processed by a Logger or on an |
117 | | -Appender. |
118 | | -10. Many Logback Appenders do not accept a Layout and will only send |
119 | | -data in a fixed format. Most Log4j 2 Appenders accept a Layout, allowing |
120 | | -the data to be transported in any format desired. |
121 | | -11. Layouts in Log4j 1.x and Logback return a String. This resulted in |
122 | | -the problems discussed at |
123 | | -http://logback.qos.ch/manual/encoders.html[Logback Encoders]. Log4j 2 |
124 | | -takes the simpler approach that xref:manual/layouts.adoc[Layouts] always return |
125 | | -a byte array. This has the advantage that it means they can be used in |
126 | | -virtually any Appender, not just the ones that write to an OutputStream. |
127 | | -12. The xref:manual/appenders.adoc#SyslogAppender[Syslog Appender] supports |
128 | | -both TCP and UDP as well as support for the BSD syslog and the |
129 | | -http://tools.ietf.org/html/rfc5424[RFC 5424] formats. |
130 | | -13. Log4j 2 takes advantage of Java 5 concurrency support and performs |
131 | | -locking at the lowest level possible. Log4j 1.x has known deadlock |
132 | | -issues. Many of these are fixed in Logback but many Logback classes |
133 | | -still require synchronization at a fairly high level. |
134 | | -14. It is an Apache Software Foundation project following the community |
135 | | -and support model used by all ASF projects. If you want to contribute or |
136 | | -gain the right to commit changes just follow the path outlined at |
137 | | -http://jakarta.apache.org/site/contributing.html[Contributing]. |
| 19 | +== Welcome to Apache Log4j! |
| 20 | +
|
| 21 | +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. |
| 22 | +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]. |
| 23 | +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. |
| 24 | +
|
| 25 | +Logging is an essential part of the software development process. |
| 26 | +It provides a way to track the flow of execution in a program, allowing developers |
| 27 | +to understand the application's behavior without needing a debugger. |
| 28 | +This is particularly useful when tracking bugs or understanding why a particular code runs slowly. |
| 29 | +
|
| 30 | +The original concept for Log4j was conceived in early 1996 when the |
| 31 | +E.U. SEMPER project decided to develop its own tracing API. |
| 32 | +In 2003, the project was donated to the Apache Software Foundation, which became Apache Log4j. |
| 33 | +
|
| 34 | +Since then, Log4j has seen numerous releases and has become a widely adopted solution. |
| 35 | +
|
| 36 | +== When should you use Log4j? |
| 37 | +
|
| 38 | +Log4j is an excellent choice for any Java application that needs logging capabilities. |
| 39 | +It is user-friendly, fast, and flexible. You can use it to log messages at |
| 40 | +different levels of severity, from debug to fatal, and you can configure it to |
| 41 | +log messages to various destinations, such as files, databases, or the console. |
| 42 | +
|
| 43 | +== When not to use Log4j? |
| 44 | +
|
| 45 | +While Log4j is a highly suitable choice for many applications, |
| 46 | +it may be challenging to locate the information you require when |
| 47 | +logging a high volume of messages. |
| 48 | +Additionally, logging can impact your application's performance. |
| 49 | +
|
| 50 | +Log4j offers solutions to address these concerns. However, if you are in |
| 51 | +a unique situation where you are concerned about logging overhead or volume, you may wish |
| 52 | +to consider not using logging at all. |
| 53 | +
|
| 54 | +== What does Log4j offer? |
| 55 | +
|
| 56 | +Log4j offers numerous features, including: |
| 57 | +
|
| 58 | +include::partial$log4j-features.adoc[] |
| 59 | +
|
| 60 | +== How to learn more? |
| 61 | +
|
| 62 | +* xref:manual/installation.adoc[How can I install Log4j?] |
| 63 | +* xref:manual/configuration.adoc[How can I configure Log4j?] |
| 64 | +* xref:manual/api.adoc[How can I use Log4j API?] |
| 65 | +* xref:manual/performance.adoc[How can I tune my Log4j setup for performance?] |
| 66 | +* xref:manual/migration.adoc[How can I migrate from Log4j 1 to Log4j 2]? |
| 67 | +* xref:manual/plugins.adoc[What are Log4j plugins] and xref:manual/extending.adoc[how can I use them to extend Log4j?] |
0 commit comments