Log4j完全使用手册(未完)

 

 

Log4j完全使用手册

 

作者的手稿,2000年11月20日

Ceki Gülcü

 

本手册适用于log4j1.2以后版本

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The complete 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 copyrighted by Mick Ellison.

Reproduced with permission.

You are authorized to download one copy of the electronic book entitled "The complete 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 according to the terms and conditions herein.

This License permits you to install the Work for your personal use only.

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 granted 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 notices (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 automatically 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 NO

EVENT SHALL CEKI GüLCü OR ANY OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM,

DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR

OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK OR THE USE

OR OTHER DEALINGS IN THE WORK.

THE WORK COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.

CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES

WILL BE INCORPORATED IN NEW EDITIONS OF THE WORK. THE AUTHORS MAY 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目录

目录............................ ......................................................... .......................................................I

前言......................................................... ....................................................................................IV

本书内容...................................................................................................... IV

排版约定....................................................................................... V

建议与评论................................................................................................. VI

致谢............................................................................................................ VI

1. 绪言........................................................................................................... 1

安装........................................................................................................................... 2

运行示例....................................................................................................... 2

第一步................................................................................................................... 3

在你的应用程序中使用log4j.................................................................. 4

2. log4j架构............................................................................................ 6

日志记录器层次.............................................................................................................. 6

日志创建与修补(CREATION AND RETRIEVAL)............................................................................. 8

级别.................................................................................................................................. 9

日志级别过滤器........................................................................................................ 13

HIERARCHY-WIDE THRESHOLD FILTER................................................................................ 14

输出源.......................................................................................................................... 16

布局器............................................................................................................................. 19

对象操作OBJECT RENDERING ............................................................................................................. 19

A PEEK UNDER THE HOOD.................................................................................................... 20

日志事件类 ........................................................................................................ 22

性能..................................................................................................................... 23

3. 配置脚本CONFIGURATION SCRIPTS.................................................................................... 28

使用基本配置的简单方法............................................................. 28

属性格式的配置文件语法.............................................. 32

设置深度和广度的入口....................................................................... 37

设置日志记录器的级别........................................................................................ 38

设置一个输出源的入口........................................................................ 41

多输出源.......................................................................................................... 42

用XML配置文件........................................................................................... 45

XML脚本的语法.................................................................................................... 46

设置深度和广度的入口 (XML)............................................................... 53

设置日志记录器的级别(XML) ........................................................................... 54

设置一个输出源的入口(XML)............................................................ 57

多输出源(XML)............................................................................................. 59

重新加载配置文件..................................................................................... 62

用log4j嵌入库(EMBEDDED LIBRARIES).................................................................................... 64

ii TABLE OF CONTENTS

默认初始化.................................................................................................... 66

用web配置器初始化log4j...................................................................... 69

在tomcat下的默认初始化......................................................................... 70

初始化sevlet..................................................................................................... 71

在应用服务器初始化log4j............................................................... 72

4. 输出源................................................................................................................. 75

APPENDERSKELETON ........................................................................................................... 76

WRITERAPPENDER............................................................................................................... 79

CONSOLEAPPENDER............................................................................................................. 82

FILEAPPENDER.................................................................................................................... 83

ROLLINGFILEAPPENDER ...................................................................................................... 84

DAILYROLLINGFILEAPPENDER............................................................................................ 86

SOCKETAPPENDER ............................................................................................................... 88

JMSAPPENDER.................................................................................................................... 91

SMTPAPPENDER................................................................................................................ 101

ASYNCAPPENDER............................................................................................................... 105

HANDLING ERRORS............................................................................................................ 108

写你自己的输出源........................................................................................ 110

5. 布局器...................................................................................................................... 113

写你自己的输出源............................................................................................ 113

PATTERNLAYOUT............................................................................................................... 116

XMLLAYOUT..................................................................................................................... 120

HTMLLAYOUT .................................................................................................................. 121

6. 自定义过滤器................................................................................................... 123

写你自己的过滤器............................................................................................... 126

7. 诊断环境...................................................................................... 128

映射诊断环境...................................................................................... 128

嵌套诊断环境....................................................................................... 135

8. 扩张log4j................................................................................................. 138

写你自己的级别(LEVEL) ............................................................................................. 139

写自己的日志记录器(LOGGER)类................................................................................. 143

包装日志记录器类.......................................................................................... 144

更广的上下文......................................................................................................... 153

9. 变化................................................................................................................... 163

在版本1.1.星河1.2之间的变化........................................................................... 163

日志记录器(LOGGER)取代范畴类(CATEGORY)......................................................................... 163

和CATEGORY的子类的兼容性问题.................................................... 164

级别(LEVEL)取代权限(PRIORITY)................................................................................................ 164

10. FREQUENTLY ASKED QUESTIONS ............................................................... 166

TABLE OF CONTENTS iii

11. TROUBLE SHOOTING GUIDE.......................................................................... 170

12. APACHE 软件许可证(ARL)....................................................................... 175

13. 词汇表 ............................................................................................................ 177

14. 索引...................................................................................................................... 178

 

 

前言

写一本书比写一篇技术文章要困难的多,但是编软件比写一本书更困难的多.

Donald Knuth, “All Questions Answered,” October 5, 2001

你曾经看到过一个系统失败并且浪费了大量的时间重头再来吗? 频繁的出现bug是危险的,而且要花费惊人的时间,金钱和精力. 假如有足够的上下文信息,大多的①bug都可以在很快得到修复. 查找这些bug是一件艰巨的工作.

理论上,一组考虑周密的测试用例可以在开发循环的早期找出bug.然而.坦白地讲,这是不可能地,无论你多么努力地工作,即使在非常小的应用程序中,也只能找出其中几个.在应用程序失败方面,日志给开发人员提供了更为详细的上下文.另一方面,测试提供了质量保证和在应用中的信心.日志和测试是不冲突的,两者是互补的.你的应用程序越大,你越需要更多的测试和日志记录.仅仅测试是不够的,当然仅仅记录日志也是不够的.当日志被广泛使用的时候,可以证明它是一个潜在的工具.

本书内容

本手册相当详细地描述了log4j API,包括它的特点和设计原理.本书面向那些熟悉java语言地开发者,但是没有很多使用log4j地经验.在介绍的内容和示例的帮助下,新手很快就会熟练的(come up to speed). 经验丰富的log4j使用者也将发现很多在别处没有讨论过的新鲜内容.高级内容也详细地涵盖了,以便读者可以利用log4j的强大功能.

第一章简单地介绍了log4j.第二章介绍了log4j的概念和log4j的整体架构.第三章介绍配置脚本,第一个是属性文件,然后XML格式.前三章覆盖了log4j的基本特色.第四﹑五﹑六章相当深地讨论log4j的组件,即输出源(Appender),布局器(Layout)和过滤器(Filter).诸如诊断上下文和默认初始化过程等高级主题将在后面几章介绍.

       我们鼓励读者经常参考log4j附带的javadoc文档.这份也可以在网上找到: http://jakarta.apache.org/log4j/docs/api/index.html.

排版约定

斜体(Italics):

? 路径名, 文件名和应用程序名

? 新定义术语

? 诸如email地址,域名与URL等因特网地址

黑体(Bold):

? 强调,特别是配置文件

等宽字体(Constant Width):

? 所有的java代码

? 命令行和所有需要逐字敲到显示屏的选项.

? 任何需要逐字显示在java程序中的东西,包括常量,类,名字,接口名字,方法名字,变量

等宽斜体(Constant Width Italic):

? 在配置文件中可以替换的元素

? XML配置文件中的属性名

 

①大多数的bug是简单的,但是有一些需要修改架构.

 

等宽黑体(Constant Width Bold):

? 系统属性

Tunga:

? log4j组件中的属性和可选项(例如输出源(appender))

建议与评论

尽管我做了最大努力,但勿庸置疑,本书还是有冗长,错误和失误.你可以发email到[e-mail]来帮助我改善本书质量.这是一个致力于log4j相关主题的开放电子邮件列表,.报告错误﹑排版错误﹑误导或者不清晰语句都将得到高度赞赏.

随着log4j继续发展和升级,本手册也会随着升级,未来版本将努力地跟踪文档重要的log4j新特性.拥有本书,即使你就没有完整的log4j文档,你也可以继续log4j的开发工作.谢谢.

致谢

谢谢N. Asokan博士审阅本书的早期手稿.他也是层次日志记录器(hierarchical logger)概念的发起者之一,另一位是Michael Steiner博士.我感谢Nelson Minar,( of JXTA fame,)鼓励我写简短的log4j手册并及时转变为这本书.许多读者报告错误,帮助我改善本书的质量.我真诚地谢谢他们.

项目的质量非常得益于一个不怎么为人所知的名叫Gump的Jakarta项目(http://jakarta.apache.org/gump). 当日志记录器类第一次被引入的时候,它是范畴(Category)类的超类.这导致一个相当微秒的不可预知地不兼容bug,这个bug大约在24小时之内被Gump检测到了.Nicholas Wolff后来建议一个比较有依赖性的移植策略.没有Gump,我们将花费数周或者数月才能检测到这个问题,到那时再修改这个bug可能已经为时已晚了.简单地说,没有Gump,log4j将不可能提供向后兼容的保证.生活就像一盒巧克力,你从来不会知道你将得到什么.

Log4j是集体努力的结果.我要特别感谢所有为这个项目作出贡献的作者.毫无例外,软件包中最新的特色全部来自log4j社区.在1999年四月log4j变为开源项目(publicly available).随后不久发生了让人吃惊,并且独一无二的事件:各种补丁开始出现了(patches started to make their appearance).各种评论与代码在世界的各个角落流串.我几乎无法描述那种收到有独创性补丁时的愉快感觉,特别是在新版本发布不久,就出现的那些.

Log4j项目的贡献者太多了,以至于无法在这全部列出.然而,像下面几个开发人员,如Oliver Burn, James P. Cakalic, Paul Glezen, Anders Kristensen, Jon Skeet, Kevin Steppe, Chris Taylor, Mark Womack作出的贡献特别有代表性.我再怎么感谢他们都不过份.我很感谢Tomcat的Costin Manolache允许我使用他的代码.

Log4j把它的成功归结于积极的用户群.事实上,这本手册的内容本身大多数是从log4j的邮件列表的问题与评论(questions and comments)中激发出来的.希望那些问题在本手册中可以得到解决.

 

 

 

 

 

 

 

 

1

1.Introduction绪言

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 grow much more complex entities in four months than

they can build.

Frederic P. Brooks, Jr., The Mythical Man-Month

士气的影响正在开始,当有一个系统正在运行时,即使是一个简单的系统,激情也会跳跃.当来自一个新的图形系统的第一张图片显示在屏幕上的时候,即使它仅仅是一张四边形,也要花费双倍的努力.在一个运行着的系统的进程的每一个地方都有.

Almost every large application includes its own logging or tracing API. In compliance

with this rule, the E.U. SEMPER project decided to write its own tracing API.

This was in early 1996. After countless enhancements, several incarnations and much

work that API evolved to become log4j, a popular logging package for Java. The

package is distributed under 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

indicates that logging is 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 made persistent so it can be studied later. In addition

to its use in the development cycle, a sufficiently rich logging package can also

be viewed as an auditing tool.

2 CHAPTER 1: INTRODUCTION

As Brian W. Kernigan and Rob Pike put it in their 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 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 Examples

This book comes with various examples for hands-on experience. The source for

code for the examples are 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 examples, change the current directory to MANUAL_

HOME/examples/ and invoke a recent version of jakarta-ant, as appropriate for

your environment. Note that apart from jakarta-ant, all required libraries are included

under the lib/ directory.