Friday, April 07, 2006

Setting up log4j

I just got told by Boss that we need to make our logging more official. I can buy that. I suggest log4j as a de facto standard. He can buy that, and I'm off and running.

So I wander over to the log4j site, use SuSE's yast to install it, and pull up a source file with a few println() calls, to try it out on. I install the docs and the API javadocs, and pull up the docs front page. The first link is "short manual", which sounds promising.

Here's where the story bogs down, and I slip into rant mode.

I'll start with the punchline. I needed to add to my app's startup code:

BasicConfigurator.configure( new ConsoleAppender( new PatternLayout( "%d{ISO8601} %c%n%p: %m%n" ) ) );

In each source file, I needed to add the following member variable:

private static Logger logger = Logger.getLogger( MyClass.class );

And in place of each println() call, I needed to add the following:

logger.debug( "your message here" );

Actually, the call to logger.debug() could have been a call to, logger.warn(), etc., depending on the nature of the message.

How long did it take you to read that? 30 seconds? Given that code, you now can go into the API docs and lookup PatternLayout, and see what that string means, or look up Logger and see what methods you call for what log levels. And while I still haven't mentioned much about what an Appender is, or how you control what log levels get output, (I'm not sure myself yet), you now have working logging, using log4j. Darn close to being as easy as those println() calls you're replacing.

We now return to the rant: How long did it take me to code this? About 20 minutes. The so-called "short manual", in my small Firefox font, takes up more than 22 full-screen pages. I glanced at it, saw bits and pieces of what I needed, poked around the API docs for a while, realized I needed to read short-man a bit more carefully, and gradually figured out what those three simple lines of code would be, to give log4j a whirl.

Why on earth did the so-called "short manual" not start off with three lines of code?! Why did somebody assume (not necessarily the short manual author, but rather the person who put the link to it at the top of the doc page) assume that I'd want to read 22+ small-fonted pages just to get started with log4j?

There was a moment, let me assure you, when, had I not suggested its use, and had I not been tasked with improving our logging, I would have said "println()'s are good enough", and stopped reading.

The key here is that I was in evaluation mode, having not yet bought into its use. 3 lines of code stuck in my app did convince me, once I divined what they were; handing them to me early would have been greatly appreciated, and sold me much quicker. One would assume others might glance around, see 22+ pages, and say without further ado, "println()'s are good enough", which would be a shame.

Later, I'm pretty sure I will want to know more about log4j, and the short manual will be quite useful. But at this moment, I just wanted to see what it'll do, and what I found was a bad way to show me that.

Okay, I've calmed down a bit.


Anonymous patrick wyss said...

and the worst part of this 20 minute short-manual-reading: you obviously did not see that calling:
is not necessary. in a normal situation you just place a or .xml file in your classpath and log4j automatically reads it...

so: yes you are right, the short manual is a bit too long.
but maybe reading it completely will help lot's of people to not only use log4j but to also know a bit about what it is doing.

provided they read it carefully, that is ;-)

8:26 AM  

Post a Comment

<< Home