Using Log4j with JBoss

217320

Date: 2002-05-26, 11:29:37 AM

SCOTT STARK

The JBoss Group

Using Log4j with

JBoss

Edition

1

PREFACE0 PAGE 1

Page 1 of 29

SCOTT STARK, AND THE JBOSS GROUP

Using Log4j with JBoss

© JBoss Group, LLC

2520 Sharondale Dr.

Atlanta, GA 30305 USA

sales@jbossgroup.com

PREFACE0 PAGE 2

Page 2 of 29

Table of Content

PREFACE...................................................................................................................................................................................................................................2

ABOUT THE AUTHORS...............................................................................................................................................................................................................2

ACKNOWLEDGMENTS.................................................................................................................................................................................................................2

0. INTRODUCTION TO LOG4J...................................................................................................................................................................................3

WHAT THIS BOOK COVERS........................................................................................................................................................................................................3

1. AN OVERVIEW OF THE LOG4J API.....................................................................................................................................................................4

The org.apache.log4j.Category class............................................................................................................................................................................4

org.apache.log4j.Logger..................................................................................................................................................................................................6

The JBoss org.jboss.log.Logger wrapper..................................................................................................................................................................6

The org.apache.log4j.Appender interface....................................................................................................................................................................7

The org.apache.log4j.Layout class................................................................................................................................................................................8

Configuring log4j using org.apache.log4j.PropertyConfigurator...............................................................................................................................8

Configuring log4j using org.apache.log4j.xml.DOMConfigurator...........................................................................................................................10

Log4j usage patterns......................................................................................................................................................................................................18

The Log4jService MBean...............................................................................................................................................................................................19

SUMMARY................................................................................................................................................................................................................................20

2. USING LOG4J...........................................................................................................................................................................................................21

EMAIL NOTIFICATIONS BASED ON PRIORITY...........................................................................................................................................................................21

The SMTPAppender........................................................................................................................................................................................................21

org.apache.log4j.AsyncAppender.................................................................................................................................................................................23

3. INDEX..........................................................................................................................................................................................................................24

PREFACE0 PAGE 3

Page 3 of 29

Table of Listings

Listing 1-1, A summary of the key methods in the log4j Category class.__________________________________________________________4

Listing 1-2, A summary of the key methods in the log4j 1.2 Logger class._________________________________________________________6

Listing 1-3, The JBoss Logger class summary._________________________________________________________________________________6

Listing 1-4,Tthe standard JBoss-2.4.x log4j.properties configuration file.__________________________________________________________8

Listing 1-5,Tthe standard JBoss-3.0.x log4j.xml configuration file.______________________________________________________________14

Listing 2-1, A SMTPAppender configuration sample___________________________________________________________________________22

Listing 2-2, An AsyncAppender configuration sample that delegates messages to the ErrorNotifications SMTPAppender________________23

PREFACE0 PAGE 4

Page 4 of 29

Table of Figures

Figure 1-1, The DTD for the configuration documents supported by the log4j version 1.1.3 DOMConfigurator.________________________12

Figure 1-2, The DTD for the configuration documents supported by the log4j version 1.2.3 DOMConfigurator.________________________14

INTRODUCTION TO LOG4J - 0 PAGE 1

Page 1 of 29

INTRODUCTION TO LOG4J - 0 PAGE 2

Page 2 of 29

Preface

About the Authors

Scott Stark

, Ph.D., was born in Washington State of the U.S. in 1964. He started out as a chemical engineer and graduated with a B.S. from the University of Washington, and latter a PhD from the University of Delaware. While at Delaware it became apparent that computers and programming were to be his passion and so he made the study of applying massively parallel computers to difficult chemical engineering problems the subject of his PhD research. It has been all about distributed programming ever since. Scott currently serves as the Chief Technology Officer of the JBoss Group, LLC.

JBoss Group LLC

, headed by Marc Fleury, is composed of over 1000 developers worldwide who are working to deliver a full range of J2EE tools, making JBoss the premier Enterprise Java application server for the Java 2 Enterprise Edition platform. JBoss is an Open Source, standards-compliant, J2EE application server implemented in

100% Pure Java. The JBossServer and complement of products are delivered under the

LGPL license. With over 1,000,000 downloads, JBoss is the most downloaded J2EE based server in the industry.

Acknowledgments

Thanks go out to the Log4j developers for establishing and maintaining such a flexible logging framework.

Preface

i

INTRODUCTION TO LOG4J - 0 PAGE 3

Page 3 of 29

0. Introduction to Log4j

What is Log4j and why do we use it

Logging of messages is a common requirement in all applications. In a server environment it is a critical feature due to the distributed multi-user interaction that is characteristic of a server. Many users interact simultaneously with an application server and some degree of logging of the interactions is essential for support. A unique aspect of an application server is that many different developers may have contributed code to the applications that comprise the active components. The logging requirement could vary significantly between the various components or applications. What is needed is a flexible logging API that supports these use cases. The JBoss server has standardized on log4j as its logging API. The switch to log4j has been a gradual one, and as of the 2.4.4 release, log4j is the only logging API used internally by JBoss. JBoss-2.4.6 includes the log4j 1.1.3 release while JBoss-3.0.0 includes the log4j 1.2.3 release. The JBoss-2.4.6 version can be used with the log4j 1.2 release by simply replacing the log4j.jar in the JBoss distribution with the 1.2 version of the log4j.jar. Although there are many logging APIs, including the JSR47 logging framework that is bundled with the current JDK 1.4 release, the log4j API appears to the most commonly used of all available. It is designed to be fast, flexible, and simple. Further, the log4j community is very active and responsive to both bug reports and feature requests. These are probably the most important criteria for an application server logging framework.

What this Book Covers

The focus of this book is using Log4j within JBoss. After an overview the Log4j API we go into the details of configuring and using Log4j. Both the log4j 1.1.3 log4j 1.2.3 releases are discussed as JBoss 2.4.x uses log4j 1.1.3 while JBoss 3.x uses log4j 1.2.3.

Chapter

0

AN OVERVIEW OF THE LOG4J API

Page 4 of 29

1. An Overview of the Log4j API

What is the Log4j API and how does it fit into JBoss. Log4j has four fundamental objects: categories, priorities, appenders and layouts. Of these, API users directly use only categories and maybe priorities. Together these components allow developers to log messages according to message type and priority, and to control at runtime how these messages are formatted and where they are reported. We will cover the basics of log4j to allow you to understand the JBoss log4j configuration and help get you started using log4j in your components. For additional documentation refer to the log4j home page, which is located here: http://jakarta.apache.org/log4j/.

The org.apache.log4j.Category class

The central component in the log4j 1.1.3 API is the org.apache.logj4.Category class. A category is a named entity and its name is a case-sensitive, hierarchical construct whose naming hierarchy adheres to the following rule, which is taken from the log4j manual:

A category is said to be an ancestor of another category if its name followed by a dot is a prefix of

the descendant category name. A category is said to be a parent of a child category if there are no ancestors between itself and the descendant category. This is the same convention as the Java package namespace. There exists a special root category that simply is, but has no name. It is accessed via a static method of the Category class. The Category class itself contains a large number of methods, but only the factory, logging and priority state methods are of general interest. A summary of the Category class restricted to these methods is summarized in Listing 1-1. Listing 1-1, A summary of the key methods in the log4j Category class. public class Category public static Category getRoot() public static Category getInstance(Class clazz) public static Category getInstance(String name)

Chapter

1

AN OVERVIEW OF THE LOG4J API

Page 5 of 29

public void debug(Object msg) public void debug(Object msg, Throwable t) public boolean isDebugEnabled() public void info(Object msg) public void info(Object msg, Throwable t) public boolean isInfoEnabled() public boolean isEnabledFor(Priority priority) public void log(Priority priority, Object msg) public void log(Priority priority, Object msg, Throwable t) Before going through the methods we need to define the Priority class that shows up in the

Category

method signatures. The org.apache.log4j.Priority object represents the importance or level of a message. Whenever you log a message it has a Priority associated with it. There are a small number of Priorities defined by default and are know by the names: FATAL, ERROR, WARN, INFO and DEBUG. You can extend the set of known priorities by providing subclasses of the Priority class. The utility of assigning a priority to a message is that it allows one to filter messages based on their priority or importance. Further, you can test to see if a given priority has been enabled for a Category to avoid generating log messages that would have no affect due to the current priority filters. This is important for high frequency debugging messages whose volume can adversely impact the server. Priority objects have both a string name and an integer value. The name is simply a mnemonic label for the priority. The integer value defines a relative order amongst priorities. This allows one to enable or disable all priorities below a given threshold.

Date: 2002-05-26, 11:29:37 AM

SCOTT STARK

The JBoss Group

Using Log4j with

JBoss

Edition

1

PREFACE0 PAGE 1

Page 1 of 29

SCOTT STARK, AND THE JBOSS GROUP

Using Log4j with JBoss

© JBoss Group, LLC

2520 Sharondale Dr.

Atlanta, GA 30305 USA

sales@jbossgroup.com

PREFACE0 PAGE 2

Page 2 of 29

Table of Content

PREFACE...................................................................................................................................................................................................................................2

ABOUT THE AUTHORS...............................................................................................................................................................................................................2

ACKNOWLEDGMENTS.................................................................................................................................................................................................................2

0. INTRODUCTION TO LOG4J...................................................................................................................................................................................3

WHAT THIS BOOK COVERS........................................................................................................................................................................................................3

1. AN OVERVIEW OF THE LOG4J API.....................................................................................................................................................................4

The org.apache.log4j.Category class............................................................................................................................................................................4

org.apache.log4j.Logger..................................................................................................................................................................................................6

The JBoss org.jboss.log.Logger wrapper..................................................................................................................................................................6

The org.apache.log4j.Appender interface....................................................................................................................................................................7

The org.apache.log4j.Layout class................................................................................................................................................................................8

Configuring log4j using org.apache.log4j.PropertyConfigurator...............................................................................................................................8

Configuring log4j using org.apache.log4j.xml.DOMConfigurator...........................................................................................................................10

Log4j usage patterns......................................................................................................................................................................................................18

The Log4jService MBean...............................................................................................................................................................................................19

SUMMARY................................................................................................................................................................................................................................20

2. USING LOG4J...........................................................................................................................................................................................................21

EMAIL NOTIFICATIONS BASED ON PRIORITY...........................................................................................................................................................................21

The SMTPAppender........................................................................................................................................................................................................21

org.apache.log4j.AsyncAppender.................................................................................................................................................................................23

3. INDEX..........................................................................................................................................................................................................................24

PREFACE0 PAGE 3

Page 3 of 29

Table of Listings

Listing 1-1, A summary of the key methods in the log4j Category class.__________________________________________________________4

Listing 1-2, A summary of the key methods in the log4j 1.2 Logger class._________________________________________________________6

Listing 1-3, The JBoss Logger class summary._________________________________________________________________________________6

Listing 1-4,Tthe standard JBoss-2.4.x log4j.properties configuration file.__________________________________________________________8

Listing 1-5,Tthe standard JBoss-3.0.x log4j.xml configuration file.______________________________________________________________14

Listing 2-1, A SMTPAppender configuration sample___________________________________________________________________________22

Listing 2-2, An AsyncAppender configuration sample that delegates messages to the ErrorNotifications SMTPAppender________________23

PREFACE0 PAGE 4

Page 4 of 29

Table of Figures

Figure 1-1, The DTD for the configuration documents supported by the log4j version 1.1.3 DOMConfigurator.________________________12

Figure 1-2, The DTD for the configuration documents supported by the log4j version 1.2.3 DOMConfigurator.________________________14

INTRODUCTION TO LOG4J - 0 PAGE 1

Page 1 of 29

INTRODUCTION TO LOG4J - 0 PAGE 2

Page 2 of 29

Preface

About the Authors

Scott Stark

, Ph.D., was born in Washington State of the U.S. in 1964. He started out as a chemical engineer and graduated with a B.S. from the University of Washington, and latter a PhD from the University of Delaware. While at Delaware it became apparent that computers and programming were to be his passion and so he made the study of applying massively parallel computers to difficult chemical engineering problems the subject of his PhD research. It has been all about distributed programming ever since. Scott currently serves as the Chief Technology Officer of the JBoss Group, LLC.

JBoss Group LLC

, headed by Marc Fleury, is composed of over 1000 developers worldwide who are working to deliver a full range of J2EE tools, making JBoss the premier Enterprise Java application server for the Java 2 Enterprise Edition platform. JBoss is an Open Source, standards-compliant, J2EE application server implemented in

100% Pure Java. The JBossServer and complement of products are delivered under the

LGPL license. With over 1,000,000 downloads, JBoss is the most downloaded J2EE based server in the industry.

Acknowledgments

Thanks go out to the Log4j developers for establishing and maintaining such a flexible logging framework.

Preface

i

INTRODUCTION TO LOG4J - 0 PAGE 3

Page 3 of 29

0. Introduction to Log4j

What is Log4j and why do we use it

Logging of messages is a common requirement in all applications. In a server environment it is a critical feature due to the distributed multi-user interaction that is characteristic of a server. Many users interact simultaneously with an application server and some degree of logging of the interactions is essential for support. A unique aspect of an application server is that many different developers may have contributed code to the applications that comprise the active components. The logging requirement could vary significantly between the various components or applications. What is needed is a flexible logging API that supports these use cases. The JBoss server has standardized on log4j as its logging API. The switch to log4j has been a gradual one, and as of the 2.4.4 release, log4j is the only logging API used internally by JBoss. JBoss-2.4.6 includes the log4j 1.1.3 release while JBoss-3.0.0 includes the log4j 1.2.3 release. The JBoss-2.4.6 version can be used with the log4j 1.2 release by simply replacing the log4j.jar in the JBoss distribution with the 1.2 version of the log4j.jar. Although there are many logging APIs, including the JSR47 logging framework that is bundled with the current JDK 1.4 release, the log4j API appears to the most commonly used of all available. It is designed to be fast, flexible, and simple. Further, the log4j community is very active and responsive to both bug reports and feature requests. These are probably the most important criteria for an application server logging framework.

What this Book Covers

The focus of this book is using Log4j within JBoss. After an overview the Log4j API we go into the details of configuring and using Log4j. Both the log4j 1.1.3 log4j 1.2.3 releases are discussed as JBoss 2.4.x uses log4j 1.1.3 while JBoss 3.x uses log4j 1.2.3.

Chapter

0

AN OVERVIEW OF THE LOG4J API

Page 4 of 29

1. An Overview of the Log4j API

What is the Log4j API and how does it fit into JBoss. Log4j has four fundamental objects: categories, priorities, appenders and layouts. Of these, API users directly use only categories and maybe priorities. Together these components allow developers to log messages according to message type and priority, and to control at runtime how these messages are formatted and where they are reported. We will cover the basics of log4j to allow you to understand the JBoss log4j configuration and help get you started using log4j in your components. For additional documentation refer to the log4j home page, which is located here: http://jakarta.apache.org/log4j/.

The org.apache.log4j.Category class

The central component in the log4j 1.1.3 API is the org.apache.logj4.Category class. A category is a named entity and its name is a case-sensitive, hierarchical construct whose naming hierarchy adheres to the following rule, which is taken from the log4j manual:

A category is said to be an ancestor of another category if its name followed by a dot is a prefix of

the descendant category name. A category is said to be a parent of a child category if there are no ancestors between itself and the descendant category. This is the same convention as the Java package namespace. There exists a special root category that simply is, but has no name. It is accessed via a static method of the Category class. The Category class itself contains a large number of methods, but only the factory, logging and priority state methods are of general interest. A summary of the Category class restricted to these methods is summarized in Listing 1-1. Listing 1-1, A summary of the key methods in the log4j Category class. public class Category public static Category getRoot() public static Category getInstance(Class clazz) public static Category getInstance(String name)

Chapter

1

AN OVERVIEW OF THE LOG4J API

Page 5 of 29

public void debug(Object msg) public void debug(Object msg, Throwable t) public boolean isDebugEnabled() public void info(Object msg) public void info(Object msg, Throwable t) public boolean isInfoEnabled() public boolean isEnabledFor(Priority priority) public void log(Priority priority, Object msg) public void log(Priority priority, Object msg, Throwable t) Before going through the methods we need to define the Priority class that shows up in the

Category

method signatures. The org.apache.log4j.Priority object represents the importance or level of a message. Whenever you log a message it has a Priority associated with it. There are a small number of Priorities defined by default and are know by the names: FATAL, ERROR, WARN, INFO and DEBUG. You can extend the set of known priorities by providing subclasses of the Priority class. The utility of assigning a priority to a message is that it allows one to filter messages based on their priority or importance. Further, you can test to see if a given priority has been enabled for a Category to avoid generating log messages that would have no affect due to the current priority filters. This is important for high frequency debugging messages whose volume can adversely impact the server. Priority objects have both a string name and an integer value. The name is simply a mnemonic label for the priority. The integer value defines a relative order amongst priorities. This allows one to enable or disable all priorities below a given threshold.