Log4j Complete User Manual
Author's manuscript, November 20, 2000
CEKI Gülcü
This manual is suitable for LOG4J1.2.
The completion log4j manual
By CEKI Gülcü
Copyright? 2000-2002 CEKI GÜLCÜ, All Rights Reserved.
The Illustration of the Dromaeosaur (a feathered dinosaur) on the cover is copyright by Mick Ellison.
Reproduced with permission.
You are authorized to download one copy of the electrictric book entitled "The completion log4j manual"
And Associated Software Written by Ceki Gülcü, Hereafter Referred To As the Work. The Author GRANTS YOU
A NonexClusive, NonTransferable license to use this work accounting to the Terms and conditions herein.
This license permits you to install the work for your person.
You May Not (i) Modify or Translate All Or Part of The Work (ii) Create DeriVative Works of The
Work (III) SUBLICENSE, Publish, Loan, Lease, Rent, Distribute, Sell, Timeshare, or Transfer All or Part of
THE WORK OR Any Rights Grand Hereunder To Any Other Person Or Entity; (ii) Duplicate The Work,
Except for a single backup or archival copy; (iii) Alter or remove any Proprietary NOTIES (Including
Copyright Notices, Labels or Marks Appearing in The Work.
The Work Is Owned by ITS Author and IS Protected by International Copyright and other Intellectual Property
Laws. The Author RESERVES All Rights in the work not expressly granted herein. This license and your
Right to use the work terminate automaticly if you violate any part of this agreement. in the event of
Termination, You Must Destroy The Original and All Copies of the Work.
The Work Is Provided "As IS" without warranty of any kind, Either Express
OR IMPLIED, INCLUDING, But Not Limited to, The Implied Warranties of Merchantability,
Fitness for a Particular Purpose, or Non-Infringement. In Noevent Shall Ceki Gülcü or Any Other Contributor Be Liable for Any Claim,
Damages Or Other Liability, WHETER in An Action of Contract, Tort OR
Otherwise, Arising from, Out of or in Connection with the work or the us
Other dealings in the work.
The Work Could Include Technical Inaccuracies Or Typographical Errors.
Changes are periodically added to the information herein; these Changes, INFORMATION
Will Be Incorporated in New Editions of The Work. The Authors MAKE
IMPROVEMENTS AND / OR CHANGES in the publication (s) and / or the program (s)
Described in this work at any time.
Java and all java-based trademarks and logos are trademarks or registered trademarks of sun microsystems,
Inc., in The United States and Other Countries.
Table of contents directory
table of Contents............................ ..................... .................................. ............ .........................................
Foreword ............................................... .............................................. .......................................... iv
This book content ........................................... ................................................ ..... IV
Typographic convention ........................................... ..................................... V
Suggestions and comments ............................................. ................................................ Vi
Acknowledgment ............................................. ................................................ ......... VI
Handyed words ........................................... ................................................ .......... 1
installation................................................. ................................................ ........................ 2 Run example ..................... ................................................ .............................. 2
first step............................................... ................................................ ................ 3
Use log4j in your app ...................................... .......................... 4
2. log4j architecture .......................................... .............................................. 6
Log recorder level .......................................... ................................................ .............. 6
Creative and retrieval ....................................... .................................... 8
level................................................. ................................................ ............................... 9
Log level filter .......................................... ................................................ .........
Hierarchy-Wide Threshold filter ........................................... ................................. 14
Output source ................................................ ................................................ .............................
Format ................................................ ................................................ ........................... 19
Object Operation Object Rendering .......................................... ................................................ ............. 19
A peek Under the hood ............................................. ................................................ ..... 20
Log events ............................................. ................................................ ....... 22 performance ....................................... ................................................ .......................... twenty three
3. Configure scripting configuration scripts .......................................... ........................................ 28
Simple method using basic configuration .......................................... .................
Profile syntax of the property format .......................................... .. 32
Set the depth and breadth of the entrance ........................................ ........................... 37
Set the level of log recorder ........................................ ............................................ 38
Set an entry of an output source ........................................ ............................ 41
Multi-output source ............................................. ................................................ ......... 42
Use XML configuration file .......................................... ........................................... 45
XML script syntax .......................................... ................................................ .... 46
Set the depth and breadth entrance (XML) ....................................... ...................... 53
Set the level of log recorder (XML) ....................................... .................................. 54
Set an entry (XML) of an output source ....................................... ................... 57
Multi-output source (XML) .......................................... ............................................... 59
Reload the configuration file .......................................... ....................................... 62
Embedded Libraries in Log4j ........................................ .......................................... 64
II Table of Contents
By default initialization .............................................. ................................................ .. 66 initialize log4j by web configurator ....................................... ............................. 69
Default initialization under Tomcat .......................................... ............................. 70
Initializes sevlet ............................................ ................................................ ... 71
Initializing log4j ............................................. ................ 72
4. Output source ............................................ ................................................ ................. 75
Appenderskeleton ............................................... ................................................ ........ 76
Writerappender ............................................. ................................................ ............ 79
Consoleappender ............................................. ................................................ .......... 82
FileAppender ............................................. ................................................ ................. 83
Rollingfileappender ............................................. ................................................ ... 84
Daily RollingfileAppender ............................................. ......................................... 86
SocketAppender ............................................. ................................................ ............ 88
JMSAPpender ............................................... ................................................ ................. 91
SMTPAPPENDER ............................................. ................................................ ............. 101asyncappender .................................... ................................................ .............................105
Handling Error .............................................. ................................................ ........ 108
Write your own output source ........................................ ................................................ 110
5. Format .......................................... ................................................ ...................... 113
Write your own output source ........................................ ...................................................... 113
PatternLayout ............................................... ................................................ ............ 116
XMLLAYOUT ............................................. ................................................ .................. 120
HTMLLAYOUT ............................................. ................................................ ............... 121
6. Custom filter ........................................ ................................................ ..... 123
Write your own filter ........................................ ................................................ "
7. Diagnostic environment .......................................... ........................................ 128
Mapping diagnostic environment ............................................. ..................................... 128
Nested diagnostic environment .......................................... .....................................................................
8. Expansion log4j ............................................ ................................................ 138
Write your own level (Level) ........................................ ................................................ 139
Write your own log recorder (logger) ...................................... ......................................... 143
Packaging log recorder ........................................... ........................................... 144
Coaster context .......................................... ................................................ ......... 153
9. Changes ........................................... ................................................ .................. 163
In the version 1.1. Change between the Star River 1.2 ...................................... .................................................
Logger replacement category (category) .................................. .................................................
Compatibility with Category subclasses ....................................... ........... 164
Level replacement permissions (priority) ....................................... ................................................ ..... 164
10. Frequently asked Questions ........................................... .................. 166
Table of Contents III
11. Trouble shang Guide ........................................... .....................................................
12. Apache Software License (ARL) ....................................... ................................ 175
13. Vocabulary ............................................ ................................................ ............ 177
14. Index ........................................... ................................................ .................................
Foreword
Writing a book is more difficult to write a technical article, but the software is more difficult than writing a book.
Donald Knuth, "All Questions Answeled," October 5, 2001
Have you seen a system failure and waste a lot of time again? Frequent bugs are dangerous, and it costs to spend an amazing time, money and energy. If there is enough context, most of 1bug can be Soon fixes. Find these bugs is a daunting job. In theory, a group of careful test cases can find bugs in the early days of development cycles. However. Frankly, this is impossible, no matter how much Work hard, even in very small applications, you can only find out which. On the application failure, logs provide developers to develop more detailed context. On the other hand, test provides quality assurance and Confidence in the app. The logs and tests are not conflict. The two are complementary. The bigger your app is, you need more tests and log records. Just testing is not enough, of course only records the log is not enough. When the log is widely used, it can prove that it is a potential tool.
Book content
This manual describes the Log4J API, including its characteristics and design principles. This written written to those developers familiar with Java language, but there are not many experiences in using log4j. With the help of the content and examples of the presentation, the novice is very fast It will be skilled (COME UP TO SPEED). Experienced log4J users will also find a lot of fresh content that is not discussed elsewhere. Advanced content is also covered in detail so that readers can utilize Log4j's powerful features.
The first chapter briefly introduces log4j. Chapter 2 introduces the concept of log4j and the overall architecture of Log4j. Chapter III introduces configuration scripts, the first is the property file, then XML format. The first three chapters cover the basic characteristics of log4j The fourth, five, and six chapters discusses the LOG4J components, namely the output source, the Layout and Filter. Advanced themes such as diagnostic contexts and the default initialization process will be in the following chapters Introduce.
We encourage readers to refer to the Javadoc documentation included with Log4j. This can also be found online: http://jakarta.apache.org/log4j/docs/api/index.html.
Typographic
ITALICS:
? Path name, file name and application name
New definition terms
• such as an Email address, a domain name and URL
Bold:
? Etiente, especially configuration files
Wide-wide font (Constant Width):
All Java code
• The command line and all the options that need to be knocked on a display.
Anything that needs to be displayed in the Java program, including constants, classes, names, interface names, method names, variables
Constant Width Italic:
• Elements that can be replaced in the configuration file
? Attribute name in the XML configuration file
1 Most bugs are simple, but there are some need to modify the architecture.
Constant Width Bold:
System attribute
Tunga:
• Properties and options in the log4j component (such as an output source (Appender))
Suggestions and comments
Although I have made the biggest efforts, don't be doubtful, this book still has lengthy, wrong and mistakes. You can send email to log4j-user@jakarta.apache.org to help me improve this book quality. This is a dedicated to log4j Open email list of related topics,. Reporting errors, typography errors, misleading, or unclear statements will be highly appreciated.
With the log4j continue to develop and upgrade, this manual will also work hard with the upgrade, future versions will work hard to track the new log4j new features of the document. Has this book, even if you don't have a complete log4j document, you can continue the log4j development work. .Thank you.
Thank you
Thank you N. Dr. Asokan reviewed the early manuscript of this book. He is also one of the initiators of the Hierarchical Logger concept. The other is Dr. Michael Steiner. I thank Nelson Minar, (of jxta fame,) encourage me Write a short log4j manual and turn it in time to this book. Many readers report errors to help me improve the quality of this book. I sincerely thank them sincerely.
The quality of the project is very good for a Jakarta project called GUMP (http://jakarta.apache.org/gump). When the logger class is first introduced, it is a category Category class's superclass. This results in a fairly inexvodable incompatible BUG, this bug is detected by gump within 24 hours. Nicholas Wolff later recommends a relatively dependent transplantation strategy. No gump We will spend a few weeks or months to detect this problem. If you modify this bug that it may already be too late. Simply, there is no gump, log4j will not provide backward compatible guarantee. Life Like a box of chocolate, you never know what you will get. Log4j is the result of collective efforts. I want to thank all the authors who have contributed to this project. There is no exception, all of the latest features from the Log4j community. In April 1999, log4j became an open source project. Subsequently happened, and unique events: Patches Started to make their Appearance. Various comments and code in the world Various corner streams. I have almost unable to describe the pleasant feeling when I receive an original patch, especially those who have released shortly on the new version.
There are too many contributors of the log4j project, so that you can not list all. However, like the following developers, such as Oliver Burn, James P. Cakalic, Paul Glezen, Anders Kristensen, Jon Skeet, Kevin Steppe, Chris Taylor The contributions made by Mark Womack are particularly representative. How can I thank them again. I am very grateful to Tomcat's Costin Manolache allows me to use his code.
Log4j is attributed to a positive user group. In fact, the content of this manual itself is excited from the question and comments from log4j's mailing list. I hope those issues are in this manual. Can be resolved.
1
1.Intuction
The Morale Effects Are Startling. Enthusiasm Jumps When there is a running
System, Even A Simple One. Efforts Redouble When The First Picture from A
New Graphics Software System Appears on the screen, Even if it is only a rectangle.
One Always Has, At Every Stage In The Process, A Working System. I
Find that teams can result more complex entities in Four Months Than
The can build.
Frederic P. Brooks, Jr., The Mythical Man-Month
The impact of morale is starting. When there is a system running, even a simple system, the passion will jump. When the first picture from a new graphics system is displayed on the screen, even if it is just one Zhang Si-shaped shape, it also costs double effort. Every place in a process running system.
Almost Every Logging OR TRAING API. In Compliance
With this rule, the E.U. Semper Project Decided to Write ITS OWN TRACING API.
This Was in Early 1996.After Countness Enhancements, Several Incarnations and Much
Work That Api Evolved to Become log4j, a popular logging package for java. The apache software license, a full-fledged Open SOURCE
License Certified by the open source initiative (http://www.opensource.org). The Latest
Log4j Version, Including Full-Source Code, Class Files and Documentation Can Be Found
AT
http://jakarta.apache.org/log4j
Log4j Has Been Ported by Independent Authors to C, C , Python, Ruby, Eiffel and
The Much Maligned C #.
INSERTING LOG Statements Into code is a low-tech debugging method. 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
INDICAT THAT Logging is an an important component in the development cycle. IT
Offers Several Advantages. It can provide precise context about an execution of the
Application. Once INSERTED INTO The Code, The Generation of Logging Output IS Automatic.
MoreOver, log output can be be studied later in addition
To Its Use in The Development Cycle, A Sufficiently Rich Logging Package Can Also
Be viewed as an affinity.
2 Chapter 1: Introduction
AS Brian W. Kernigan and Rob Pike Put IT IIR 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 this 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 Harden 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 Todecide Where to Put Print Statements Toint Single-Step To The Critical Section
Of Code, Even Assuming We know where there 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
Cause Scrolling Blundness. To AlleViate There Concerns, Log4j Is Designed to Be Fast
And flexible. Since logging is rarely the main focus of an application, log4j API
Strives to be Simple to understand and use.
Installing
The Latest Version of Log4j Can Be Downloaded from
Http://jakarta.apache.org/log4j/docs/download.html
Releases Are Available In Two Formats: zip and tar.gz.After Unpacking the distribution,
You Should See the file log4j_home / dist / lib / log4j-version.jar WHERE
Log4j_home is the directory where you unpacked The log4j distribution and version
Is The Version of The Log4j Distribution You Downloaded. To Start Using Log4j
SIMPLY Add this Jar File to your classpath.
Running the example
This book comes with various example for hands-on example. The Source for
Code for the examples area available Under the manual_Home / Examples / Directory,
WHERE MANUAL_HOME IS The Directory Where You Unpacked this Manual. for Your
Convenience Compiled Classes Are Available Under the Manual_
Home / Examples / Classes / Directory. In Order to Compile Execute The Examples,
You Must Have The Log4j-Version.jar As Well as The Manual_
Home / Examples / Classes Directory in Your ClassPath. Note That Some Examples
Using The Domconfigurator Require The Presence of a Jaxp Compatible
Parser.
First Baby STEP 3
IF you wish to compile the example
Your Environment. Note That Apart from Jakarta-Ant, All Required Libraries Are Included
Under the lib / Directory.
