Logging in Java with the JDK 1.4 Logging API

and Apache log4j SAMUDRA GUPTA

APress Media, LLC

Logging in Java with the JDK 1.4 Logging API and Apache log4j Copyright ©2003 by Samudra Gupta Originally published by Springer-Verlag New York, Inc. in 2003 Softcover reprint of the hardcover 1st edition 2003

All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher.

Printed and bound in the United States of America 12345678910

Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.

library of Congress Cataloging-in-Publication Data

Gupta, Samudra,l974-

Logging in Java with the JDK l.4logging API and Apache log4j I Samudra Gupta.

p.cm.

ISBN 978-1-4302-5398-3 ISBN 978-1-4302-0765-8 (eBook) DOI 10.1007/978-1-4302-0765-8

l. Java (Computer program language) 2. Apache (Computer file : Apache Group) 3. Application logging (Computer science) 4. Application software--Development-­Management. 5. Debugging in computer science. I. Title.

QA76.73.J38G86 2003

005.13'3--dc21

2003005480

Technical Reviewer: Jeff Heaton

Editorial Directors: Dan Appleman, Gary Cornell, Simon Hayes, Martin Streicher, Karen Watterson, John Zukowski

Assistant Publisher: Grace Wong

Developmental Editors: Tracy Brown Collins, Ami Knox

Copy Editor: Ami Knox

Production Manager: Karl Brooks

Compositor: Susan Glinert Stevens

Proofreader: Lori Bring

Indexer: Ann Rogers

Artist and Cover Designer: Kurt Krames

Manufacturing Manager: Tom Debolski

The information in this book is distributed on an "as is" basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work.

To the lotus feet of Bhagavan Sri Ramakrishna

Contents at a Glance

About the Author and Technical Reviewer ............................................. viii

Acknowledgments ................................................................................................... ix

Preface ...................................................................................................................... x

Chapter 1 Introduction to Application Logging ................................ 1

Chapter 2 JDK 1.4 Logging API ................................................................. 11

Chapter 3 Formatting JDK 1.4 Logging Information ........................ 59

Chapter 4 Extending the Logging Framework ....................................... 73

Chapter 5 Understanding Apache log4j ................................................ 121

Chapter 6 Formatting Logging Information in log4j .................... 177

Chapter 7 Advanced Logging with log4j .............................................. 199

Chapter 8 Extending log4j to Create Custom Logging Components .................................................................... 235

Chapter 9 Using the Apache Log Tag Library ................................... 285

Chapter 10 Best Practices ........................................................................ 299

Index ...................................................................................................................... 315

iv

Contents

About the Author and Technical Reviewer ............................. viii

Acknowledgments ............................................................................................. ix

Preface ...................................................................................................................... x

Chapter 1 Introduction to Application Logging ............. 1

What Is Logging? .................................................................................................. 1 Benefits of Logging ........................................................................................... 3 Disadvantages of Logging ................................................................................ 4 How Logging Works ................................................................................................ 5 Evaluating a Logging Package ........................................................................ 7 Popular Java-Based Logging APis ................................................................. 7 The Road Ahead ...................................................................................................... 9

Chapter 2 JDK 1. 4 Logging API .................................................... 11

JDK 1.4 Logging API Overview ...................................................................... 11 LogManager Object .............................................................................................. 15 LogRecord Object ................................................................................................ 17 Logger Object ...................................................................................................... 18 Handler ................................................................................................................... 33 Filter Object ...................................................................................................... 51

File-Based Configuration .............................................................................. 55

Formatter Object ................................................................................................ 58 Conclusion ............................................................................................................. 58

Chapter 3 Formatting JDK 1. 4 Logging Information .................................................... 59

Default Formatter Objects ............................................................................ 59

Localization of Logging Messages ............................................................. 68 Writing Custom Formatters ............................................................................ 69

Conclusion ............................................................................................................. 72

v

Contents

Chapter 4 Extending the Logging Framework ........................ 73

Configuring the Logging Framework : .......................................................... 73 Writing Custom Handlers ................................................................................. 83 Remote Logging .................................................................................................... 94 Logging in Practice ....................................................................................... 102 Conclusion ........................................................................................................... 120

Chapter 5 Understanding Apache log4j ................................ 121

Installing log4j .............................................................................................. 121 Overview of the log4j Architecture ....................................................... 122

Configuring log4j ............................................................................................ 125 Level Object ....................................................................................................... 136 Logger Object ..................................................................................................... 136

LogManager Object ............................................................................................ 145 Nested Diagnostic Context (NDC) ............................................................. 146 Message Diagnostic Context (MDC) ........................................................... 147 Appender Object ................................................................................................ 149 Filter Object ..................................................................................................... 166 Layout Object ..................................................................................................... 168 ObjectRenderer .................................................................................................. 168 A Complete log4j Example ............................................................................. 169 Conclusion ........................................................................................................... 175

Chapter 6 Formatting Logging Information in log4j ............................................................................... 177

The Layout Hierarchy ..................................................................................... 177 The Layout Objects in log4j ...................................................................... 178 Conclusion ........................................................................................................... 198

Chapter 7 Advanced Logging with log4j .............................. 199

A Sample Advanced Logging Application ................................................ 200 Logging to a Database with JDBCAppender ............................................ 202 Implementing JMS-Based Logging with JMSAppender .......................... 212 Working with SocketAppender ...................................................................... 223 Logging to Windows NT Event Log with NTEventLogAppender ......... 228 Distributing Logging Information via SMTPAppender ...................... 229 Making Messages Available Through Telnet

with TelnetAppender ................................................................................ 232 Conclusion ........................................................................................................... 232

vi

Contents

Chapter 8 Extending log4j to Create Custom Logging Components ................................... 235

Creating the Custom WindowAppender ...................................................... 235 Configuring log4j from a Database ......................................................... 243 Custom Logging Framework ............................................................................ 258 More on Filtering ............................................................................................ 270 Error Handling .................................................................................................. 277 Conclusion ........................................................................................................... 284

Chapter 9 Using the Apache Log Tag Library ................. 285

Installing the Log Tag Library ............................................................... 285 A Simple Example of Using the Log Tag Library .............................. 286 Using a Custom Logger with the Log Tag Library ............................ 291

Description of Log Tags .............................................................................. 292

Creating Custom Tags with the Log Tag Library to Use a Custom Level ............................................................................ 294

Conclusion ........................................................................................................... 298

Chapter 10 Best Practices ............................................................... 299

Obtaining a Logger ......................................................................................... 299

Using Logger Hierarchy ................................................................................. 301 Logging Messages Efficiently .................................................................... 302 Issues with Localization ............................................................................ 304 Using Location Information ........................................................................ 304

Formatting Logging Information ............................................................... 305 Using Renderer Objects ................................................................................. 305 Using Asynchronous Logging ........................................................................ 306 Using Filter Objects ..................................................................................... 306 Using Nested Diagnostic Context ............................................................. 307 Configuration Issues ..................................................................................... 308 Comparing log4j and JDK 1. 4 Logging API ............................................ 309 Conclusion ........................................................................................................... 313

Index ................................................................................................................... 315

vii

viii

About the Author and Technical Reviewer

About the Author

Samudra Gupta holds a postgraduate degree in information technology and management from All India Management Association, India, and has around six years of experience in designing and developing Web-based applications ranging from research-based projects toe-commerce applications. He started his career as a research engineer at the Indian Institute of Technology, Kanpur, India, and he is presently working as an independent Java consultant in the United Kingdom, architecting and developing several e-commerce-based applications, content management system software, and retail-based software. Samudra also writes articles for Java World and Java Developer's Journal, and is a monthly contributor to Java Boutique (http: I /java boutique. internet. com). When not programming, he plays a lot of contract bridge.

About the Technical Reviewer

Jeff Heaton is an author, college instructor, and consultant. Jeff lives in Chesterfield, Missouri. The author of three books and over a dozen journal and magazine articles, Jeff specializes in Internet, socket -level/ spidering, and artificial intelligence programming. A Sun-certified Java programmer and a member of the IEEE, Jeff has a masters degree in information management from Washington University in St. Louis.

Acknowledgments

ALTHOUGH THERE APPEARs only one name on the cover of this book, the credit for this accomplishment goes to many. I would first of all like to thank everybody in the Apress family for making a dream come true for me by publishing this book. Special thanks go to John Zukowski, Editorial Director, Apress, for signing me to write this book and suggesting many ideas during the course of putting the manu­script together to make this book a better one. Grace Wong, Assistant Publisher, deserves all the credit for her guidance from the manuscript stage to the production stage of this book. Tracy Brown Collins and Ami Knox both have done a splendid job with development and copyediting of this book, contributing so many valuable ideas and making this book coherent and consistent throughout. Without their great efforts, many mistakes might have made their way into this book. I also thank the production team at Apress-Kari Brooks, Production Manager, as well as Susan Glinert Stevens, Lori Bring, and Ann Rogers-for their commendable job in the final production of this book.

I am greatly thankful to Jeff Heaton, Technical Reviewer, who suggested numerous improvements to make this book more accurate and useful. I feel honored to have his name associated with this book. My heartfelt thanks must also go to Paul Burden and Ashish Patel, two of the great programmers I have had the privilege to work with, for contributing their most valuable ideas from the initial stages of this book.

I take this opportunity to express my deepest gratitude and convey my most humble regards to Doctor T.V. Prabhakar, Department of Computer Science and Engineering, Indian Institute of Technology, Kanpur, India, who initiated me into the world of computer science. Without his most valuable and affectionate guidance, it just could not have been the same. My special thanks go to Mr. N. V. Brahmaji Rao, Doctor Amit Neogi, and Doctor Chaitali Roy for encouraging me throughout my efforts in writing this book. Without their encouragement, I might not have ventured to do so.

Lastly, my parents and my elder brother (whom I call Dadabhai) have been a source of constant inspiration and encouragement throughout. I offer them my

sincerest regards, and words cannot express my gratitude to them. In the end, I say a big "thank you" to all my friends, too many to name individually, and you know

whoyouare.

ix

X

Preface

lins BOOK DEAlS WTIH the concept ofbuilding a flexible and robust application logging

framework for Java-based applications. After an introduction to application logging, this book covers the two most popular Java-basedloggingAPis: the JDK 1.4loggingAPI

and Apache log4j version 1.2.6. The text provides a comprehensive study of these

two APis, and in the final chapter you will find a comparative study of the two

logging APis and a few best practices for using them. This book is aimed at providing an in-depth guide to the use of the JDK 1.4

logging API and Apache log4j with an emphasis on

• Understanding the internals of these APis and how they work

• Working with the extremely useful, robust logging features available in theseAPis

• Extending the existing logging framework for certain specialized, application-specific needs

The book provides numerous examples, ranging from simple programs to complex ones, written in the Java language. The simple examples explain how the

loggingAPis work and what they are capable of producing in terms of logging output.

The complex examples resemble real-life application scenarios and demonstrate how useful logging can be to maintaining large-scale distributed application com­ponents. Finally, the comparison between the JDK 1.4loggingAPI and Apache log4j

will act as a guideline for deciding which of the two discussed APis to use in your

project.

Target Audience

This book, which discusses logging APis based in the Java language, targets

beginning-to-advanced Java language application developers. It provides many

simple and straightforward examples that demand only minimal familiarity with

the Java language. Thus this book can also be helpful to non-Java language appli­cation developers, who can still benefit from the ideas presented in this book.

Chapter Synopsis

This book is mainly divided into two sections: one for the JDK 1.4loggingAPI, and the other for Apache log4j version 1.2.6. Readers interested in only one particular API can skip the chapters discussing the other. In general, the book comprises the following chapters:

Chapter 1: Introduction to Application Logging

This chapter discusses application logging. It describes the advantages and disad­vantages related to the various concepts of application logging. This chapter also discusses a few criteria for a good logging framework.

Chapter 2: JDK 1.4 Logging API

This chapter introduces the JDK 1.4logging API and provides an in-depth discussion about the internals and use of this API.

Chapter 3: Formatting JDK 1.4 Logging Information

This chapter explores the issues related to the formatting oflogging output. It discusses the available formatting options within the JDK 1.4logging API and also shows how to write custom formatters to do customized formatting.

Chapter 4: Extending the Logging Framework

This chapter is dedicated to explaining and demonstrating how to extend the existing JDK 1.4loggingframework to write custom, application-specific logging components. It provides some real-life examples to illustrate how custom logging components can be developed and used.

Chapter 5: Understanding Apache log4j

This chapter provides an in-depth discussion of Apache log4j based on version 1.2.6. It explains the core objects involved in the log4j framework, and how they work and interact with each other to finally produce logging output.

Preface

xi

Preface

xii

Chapter 6: Formatting Logging Information in log4j

This chapter discusses different formatting options available within log4j to

structure the final logging output. It also shows how to use configurable patterns

to format logging information.

Chapter 7: Advanced Logging with log4j

This chapter is dedicated to the advanced logging features oflog4j. It details the process of distributing logging information via a database, a Java Message Service

(JMS), the Simple Mail Transfer Protocol (SMTP), and various other options

available within log4j.

Chapter 8: Extending log4j to Create Custom Logging Components

This chapter focuses on the techniques to extend the existing log4j framework in

order to write custom, application-specific logging components. It provides some

real-life examples to demonstrate how effective custom logging components can

be in certain application scenarios.

Chapter 9: Using the Apache Log Tag Library

This chapter discusses the Apache Log tag library, which can be used along with Java Server Pages USPs) to achieve log4j-based logging activity. It describes the installation and use of the Log tag library and also shows how to incorporate

custom tags within this tag library.

Chapter 10: Best Practices

This chapter provides a guideline to the best practices involved in using the JDK 1.4

logging API and Apache log4j. It also provides a comparative study of these two logging APis.