Log4j

Recently I started a new project at work. It is a server-side program suite for managing a large number of devices out in the world, with a database back-end and all sorts of goodies. I decided that it would be a good idea to use a standard logging package, instead of my standard method.

Not that my standard method is bad, it just isn't very flexible. There is a program-wide DEBUG flag set at startup which controls all debugging output of any sort, from any source. Since I'd be working with a much larger system than I'm used to, I thought it'd be nice to use a package with a few more features than 'debugging output is on' and 'debugging output is off.'

So Log4j seemed like the best choice. It's open-source (from the Apache foundation) and provides all of the neat little features that might be useful:

1. It can selectively turn on/off logging depending on the source of the call.
2. It can direct logging output to any of a number of different destinations.
3. It has importance levels, so you can filter out the debugging messages from stable code but continue to see the errors/warnings from the same object.

Sounds pretty good, huh? It certainly did to me. But if that's the case, why am I writing this, you might ask? If you're a loyal reader, you may have noticed that I don't have many positive posts...

Log4j has virtually no documentation. Well... no, let me revise that: Log4j has virtually no free documentation.

There's a short introduction describing what it can do, how fast it is, ... BUT it doesn't tell you how to do it.

There's a FAQ which tells you what it can do, how fast it is, ... but again, not how to do it. It just gives you more details on the same subjects as the introduction.

There's even a Wiki! But no help there, it's aimed at developers of Log4j, not developers of programs using Log4j.

So where can I learn how to use this feature-rich, fast logging platform for Java? Well, you can buy a $20 PDF book that describes everything!

But surely there's information available online, through Google or something, right? No. Everybody just seems to know how to use it, but nobody is saying how they know. Did everybody read the source code? I don't know... I certainly don't want to learn how to use a library by reading its source, that's what documentation is for!

Oh, there are some examples on the Log4j page, and a few more spread around the web, but guess what? They're the same examples! Nobody thought that it would be a good idea to, perhaps, come up with their own to describe the other features that aren't documented on the home page. They just copied the same examples and assumed they explained everything.

So here are a few little pieces to help the lost developer trying to configure Log4j that doesn't want to buy the book or read through the source:

; Comments begin with a semicolon ; Set the options on the root logger to ; output all messages to appender A1 ; Since loggers are organized in a ; hierarchy, unless you specify ; different options, this will apply ; to all loggers log4j.rootCategory=ALL, Console ; Set the class for the Console ; appender ; For a list of options, go to the ; Log4j site, view the Javadoc, find ; the Appender interface under the ; org.apache.log4j package, and look ; through the list of known ; implementing classes ; A console appender is the simplest, ; just outputting to stdout log4j.appender.A1= org.apache.log4j.ConsoleAppender ; Set the class that will format ; messages going through the console ; appender ; For a list of options, go to the ; Layout class in the same place as ; the Appenders and look through the ; direct known subclasses ; A pattern layout lets you specify ; the format yourself, using %x ; style arguments that get replaced ; by known data log4j.appender.Console.layout= org.apache.log4j.PatternLayout ; Set the output pattern ; Look at the javadoc for ; com.apache.log4j.PatternLayout for ; a complete list of format specifiers log4j.appender.Console.layout .ConversionPattern= %r [%t] %-5p %c{2} %x - %m%n ; Set the lower limit of what will be ; sent through this appender ; In this case, messages must have an ; importance of at least a warning to ; be printed on the console log4j.appender.Console.Threshold=WARN ; Set the level of an individual logger ; This means that, even if the appender ; is set with a lower threshold, this ; specific logger (com.blogspot...) ; will only pass along messages with ; an importance of at least ERROR log4j.logger.com.blogspot.jonrambles.X= ERROR

Other useful things you can do are use a rolling file appender (class is 'org.apache.log4j.RollingFileAppender'), which is given a maximum file size. It will output all messages to that file until it hits the max size, and then rename it and create a new one to write to. Here are the properties you should know about with it:

• log4j.appender.RFA.File=filename.log
• log4j.appender.RFA.MaxFileSize=1M
• log4j.appender.RFA.MaxBackupIndex=3

This will append to filename.log until it reaches 1 megabyte, then it will rename it to filename.log.1 (renaming filename.log.1 to filename.log.2 and so on as necessary), keeping files up to filename.log.3, but no more.

You can specify multiple appenders for the root logger like this:

 log4j.rootCategory=ALL, Console, RFA

One more useful trick is to send logger output to specific places. You can do that like this:

 log4j.logger.loggerName=ALL, A2
 log4j.additivity.loggerName=false

That will cause all logger output from that specific logger to go to A2, but not to the root logger's appender.

And finally, to get Log4j working, you need to add a little bit of code to the initialization of your program. I'd suggest doing this in a static block in your main class. You just need to call

 PropertyConfigurator.configureAndWatch(
     "log4j.properties", 5000)

That will cause the properties file that you just wrote using all of the tips I gave to be loaded at startup, and it will be checked for updates every 5 seconds. If it changes, the new settings will go into effect. That allows you to selectively enable logging as you notice unexpected behavior, but not be overwhelmed by log messages all the time.

So what's my conclusion? I know, I jumped from complaining about Log4j to showing how it works and what you can do with it. I actually kind of like the system. It is convenient to work with (except when you need to configure something), it monitors the configuration file so I can enable logging after the program starts, and I can supress messages for parts of the program I've already finished debugging.

So I'd say that you should give it a try, and hopefully someone will help you out when you can't find the right option for your current situation. And if nothing else works, read the source. It's painful, but that's how I figured out the additivity options.

Computer Software and Cars

As those who visit Slashdot are probably aware, many of the most vocal members of the site tend to push the ideology that all software should be open source. This is a noble goal, but it is not a workable model.

The main argument for people to want the source to their software (at least, in theory; in practice it is more because generally open source is free as in beer) is to tinker with it, to go "under the hood."

On the surface, this seems like an excellent analogy, comparing software developers to automobile hobbyists. You get a piece of software (or a car), and you tinker with it to really make it your own. Perhaps you make the user interface flashier (give it a good paint job) or tweak a few bits to make it run faster (tweak a few bits to make it run faster... yea, that translates pretty well).

So from that perspective, it seems like all software should be open source. Honestly, virtually everything technically is open for you to tweak, if you know how (for example, lawn mower races or anything that has received the Tim Taylor "more power!" treatment). But not software. Seems pretty unfair, as if we're getting the proverbial shaft.

But let's look a little closer. What is different between a piece of software and a car? Most notably, and what I'm focusing on here, is the price of the materials.

When you buy a car, the company that sold it to you really did sell the car to you; you can do whatever you want to it (except, probably, copy the design and sell it to others). They don't care what you do to it because they have your money. When you paid them, you covered the entire cost of the materials that went into the car, as well as the salaries of every engineer that helped design it, and every laborer that helped build it. Beyond that, there is no other car out there, even of the same model, that is exactly the same. (If you've ever seen discussion boards where people with the same cars are discussing their gas mileage, you'll understand this.)

When you buy a piece of software, most companies merely license it for your use. You don't own it. You don't even own your copy of it. You may own the media it was distributed on, but I am not a lawyer, so I can't say for sure. Like the car, though, what you paid for it covered the entire cost of materials and labor that created it.

But what's different? Why do they license instead of sell the software? Cost of materials. When you purchased that car, a very large percentage of the cost went towards the materials that made it (I don't know the exact numbers, but I remember someone once saying that, if it weren't for economies of scale, assembling a single average-priced car from individual parts would cost around $500,000). But when you purchased that piece of software, virtually none of the cost went towards the materials. A CD only costs a few cents to manufacture, and the extra packaging cannot possibly make up for much more of the usual $50 cost.

The car manufacturer doesn't need to worry about you copying the design, tweaking enough to avoid patent issues, and selling your own cars in competition, because it would simply cost too much; the barriers to entry in the automotive market are too high. But if you were allowed to tweak a few lines in that piece of software and start selling it, there's virtually nothing stopping you except the license agreement. Cost of materials? If you really wanted to get fancy, CDs and packaging are relatively cheap, but internet distribution is virtually free. There are no barriers to entry in the software markey beyond training!

So, although the car/software analogy is a nice way to talk about the benefits of open source, it doesn't quite fit. There will be a market for closed source software for the foreseeable future because it simply makes more business sense.

Now is the time that the Slashdot crowd would loudly exclaim "charge for service contracts, give away the software!" But honestly, I don't know about the rest of you, as a consumer I don't like service contracts. I feel like I'm wasting my money when I buy them for appliances and similar. I'm not going to pay someone else to answer my questions when I can find free answers myself.

Beyond that, service contracts just don't make sense for some software. Home office software, for example; OpenOffice.org doesn't even bother to offer anything of the sort, because it simply wouldn't make any money. The only people you can sell service contracts to are business users. For a business, it makes sense to buy the contract when it would be cheaper than hiring an expert. And, not all software is made for businesses (for example, games).

Before ending, I would like to say that I completely support open source software, I think it's great stuff, and I love watching as the quality and usage improve. I have donated money a couple of times (although not large amounts), and have released a few small utility programs with source myself. The purpose of this column was to illustrate that not everything can become open because there is no viable business model. If it really bothers you when someone keeps their software behind a restrictive license agreement and protects their source, start your own open version to compete. With enough enthusiasm, you'll probably beat them into submission in the end.