Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 79938 invoked by uid 500); 26 Jul 2001 17:19:59 -0000 Mailing-List: contact axis-dev-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: axis-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list axis-dev@xml.apache.org Received: (qmail 79928 invoked from network); 26 Jul 2001 17:19:58 -0000 Received: from adsl-63-197-150-84.dsl.snfc21.pacbell.net (HELO mail.nelson.monkey.org) (identdIsStupid@63.197.150.84) by h31.sny.collab.net with SMTP; 26 Jul 2001 17:19:58 -0000 Received: (from nelson@localhost) by mail.nelson.monkey.org (8.9.3/8.9.3) id KAA04490; Thu, 26 Jul 2001 10:19:41 -0700 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="imdGwb4PdU" Content-Transfer-Encoding: 7bit Message-ID: <15200.20781.142780.701674@syrah.nelson.monkey.org> Date: Thu, 26 Jul 2001 10:19:41 -0700 (PDT) From: nelson@monkey.org (Nelson Minar) To: axis-dev@xml.apache.org Subject: Re: [ATTN COMMITTERS!] VOTE : log4j In-Reply-To: References: X-Spam-Rating: h31.sny.collab.net 1.6.2 0/1000/N --imdGwb4PdU Content-Type: text/plain; charset=us-ascii Content-Description: message body text Content-Transfer-Encoding: 7bit Thanks for the comments, Glen. >Nelson Minar has volunteered to start doing some of the changeover >work if we agree this is a good direction to go. As this is a fairly >major feature, I'd like to get an official vote on it. I recently did this conversion for Sun's Project JXTA - after much discussion they agreed to go with log4j instead of a wrapper. I wrote up some notes on how to use log4j for them - I envision much the same thing for Axis. I'm attaching the JXTA notes here. --imdGwb4PdU Content-Type: text/html Content-Description: log4j usage notes for Project JXTA Content-Disposition: inline; filename="log4j-usage.html" Content-Transfer-Encoding: 7bit Log4j usage documentation for Project JXTA

Log4j usage documentation for Project JXTA

Log4j is an amazingly powerful debug logging library for Java. Log4j is used extensively throughout the JXTA platform to record debugging events. This document describes how to use log4j as it is implemented in JXTA.

Introduction

Text messages are a primitive way to debug a package, but they're simple and often very effective. Log4j allows one to replace the ad-hoc System.out() or printf() statements many programmers use with a low-overhead, simple object oriented approach. With log4j, debug messages can then be turned on or off by debug level and by class or package.

Log4j is free software, under the Apache software license. This file is not a log4j manual, users are referred to the log4j site for detailed, full documentation. Rather, this file explains how to use log4j with JXTA.

Using log4j

JXTA should start out-of-the-box with a reasonable log4j configuration. Messages should print out like 

  <DEBUG 18:22:55,977 Endpoint:488> demux: send to service handler
  <DEBUG 18:22:55,981 ResolverService:405> demuxing a query
Reading across, what you see are the debug level, the timestamp (including milliseconds), the class name, the line number, and the debug message. Note - by default DEBUG is turned off, so you won't see many (if any!) messages.

By default, the JXTA platform is configured via a file named log4j.properties that is loaded from the CLASSPATH. The build scripts put this file in jxta.jar by loading it up from the directory binding/java/. You can change the configuration by editing the log4j.properties file, overriding it in your CLASSPATH, or setting the property log4j.configuration to your own configuration file.

Log4j can be configured a variety of ways. My personal favourite is the PropertyConfigurator, which uses a Java properties file to configure log4j. The format is a bit confusing, but if you start with an example it isn't so bad. You can do all sorts of neat things like filter different packages to different levels, redirect log messages to files and network services, and change the format of outputs. In addition to the log4j manual, you may want to look at the javadoc for PatternLayout and PropertyConfigurator .

Log4j in your source

The JXTA use of log4j follows the common idiom of having one log4j Category object for every class. This allows maximum flexibility when filtering logging messages. To follow this idiom, follow three rules:

  1. Every class should have this line:
    import org.apache.log4j.Category;
  2. Every class should have this declaration:
    private static final Category LOG = Category.getInstance(CLASSNAME.class.getName());
    where CLASSNAME is the class name of the class itself.
  3. Every debug messages should be written like this:
    LOG.debug("A debug-level message");
    LOG.error("Got a bad exception", ex);
If there are any doubts, see the existing sources for examples.

Log4j allows messages to be logged at one of 4 levels. The guidelines for debugging messages are as follows:

error
For serious errors that indicate that the software is going to fail. Errors are never turned off. Example: failing to properly invoke a method via reflection.
warn
For things that are happening that are not good, but the software can recover from. Developers should probably keep warnings turned on, end users off. Example: parsing errors, etc.
info
For informational messages about what is happening in the software. Developers may turn off info for whole packages, but leave it on when they want a bit of tracing. Example: receiving a message from another peer.
debug
For prolific output, stuff that only someone debugging that library would want to see. Usually turned off. Example: printing out the results of a parse as it runs.

I use emacs to edit my source code, and find the following templates useful: 

  (global-set-key "\C-cld" 'tempo-template-java-log4j-debug)
  (global-set-key "\C-cli" 'tempo-template-java-log4j-info)
  (global-set-key "\C-clw" 'tempo-template-java-log4j-warn)
  (global-set-key "\C-cle" 'tempo-template-java-log4j-error)
  (tempo-define-template "java-log4j-debug" '(& "LOG.debug(\"" p "\");" >))
  (tempo-define-template "java-log4j-info"  '(& "LOG.info(\"" p "\");" >))
  (tempo-define-template "java-log4j-warn"  '(& "LOG.warn(\"" p "\");" >))
  (tempo-define-template "java-log4j-error" '(& "LOG.error(\"" p "\");" >))
(I also have a new buffer template that handles setting up the Category object for me, but it's too much to include here.)

Nelson Minar Created: July 6, 2001
<nelson@clip2.com> Updated: July 6, 2001

Nelson Minar thanks Clip2 for funding this work. --imdGwb4PdU Content-Type: text/plain; charset=us-ascii Content-Description: message body text Content-Transfer-Encoding: 7bit To head off a few questions: log4j is part of Apache. http://jakarta.apache.org/log4j/docs/index.html I'm only proposing log4j for debug logging that programmers read, not application logging that sysadmins read. log4j can do the latter very well, too, but it's a different topic. log4j allows you to send debug log messages wherever you want, via a customizable interface called "Appender". I'm certain it would be easy to feed the log stream into an app server's own log framework. http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/Appender.html There are two comparable logging packages for Java - JLog and JSR47. log4j is by far the most popular of the three. I thought JLog was free, but a quick look indicates it isn't: http://www.alphaworks.ibm.com/tech/loggingtoolkit4j That would seem to rule it out immediately. JSR47 has the virtue of being a proposed Java standard, and is currently slated for release in Java 1.4 http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html log4j has a detailed technical response to JSR47 that convinces me that log4j is better, you can read it here: http://jakarta.apache.org/log4j/docs/critique.html The only thing I see going for JSR47 is that someday it may be part of the standard Java platform, although even that is in question right now. In any event, I don't think we want to wait for it. And given the amount of log4j code out there, I think it's a safe bet now. I've used log4j for a year and a half now. It's good code. --imdGwb4PdU--