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):

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