Rushing to Judgement

A Brief Introduction to CFLog

As it is with many ColdFusion features, the CFLog tag provides a simplified interface for accessing more complex Java underpinnings. In this case, the widely-used Apache Logging (Log4j) library is the horsepower under the hood that allows your logging code to function smoothly. Let’s take a look at the tag, as defined in the CF8 LiveDocs, and look at some of its Log4j roots:

<cflog 
    text = "text"
    application = "yes|no"
    file = "filename"
    log = "log type"
    type = "information|warning|error|fatal">

As you probably already knew, CFLog limits you to a single variable where the log text can be placed. Behind the scenes, this winds up in the message payload that Log4j writes to disk. If you want to record several discrete properties you've got no choice other than stuffing them together into a single message.

If you are writing logs to a shared location, such as the application log, you might want to include the application name. Generally I prefer to log information for specific apps in their own files to avoid confusion, so I don't see recording the application name as that important.

If you choose to specify a filename, ColdFusion will automatically create a log file in the coldfusion8\logs folder. You have no control over where the file goes; it is always in this folder. If you are in a shared hosting environment, this is no good at all, as you probably can't access those logs!

You may not be aware that in Log4j the type of log can be used for more than just flagging an entry in the log file as one type or another. Log4j provides the means to configure different loggers that will selectively listen in for messages of a certain log level. In fact, the listed possibilities for type are derived directly from the log levels available by default in Log4j - trace, debug, info, warn, error, and fatal. In order to avoid getting into too much detail about the various levels or the hierarchical nature of Log4j's Logger objects, I will refer you to the great introduction available on the Apache Logging site. This is a must-read if you are really interested in digging deeper into Log4j.

Finally, besides not allowing the selection of a path for application logs, which is limiting in a shared hosting environment, CFLog does not provide any way for writing logs to a database. For the application I am working on, this is the most serious limitation of the tag, and it is what sent me down the path that ultimately led to this article.

Enter CFLog4j

When I began my research, I figured that someone else must have run into this problem before. Indeed, Qasim Rasheed has developed an excellent starting point for logging to a database with Log4j. The open-source CFLog4j provides a relatively easy way to access Log4j features, and is suitable out-of-the-box for use in a shared hosting environment. In fact, if all you’re looking to do is write your own private logs to disk in a shared environment, CFLog4j will do what you need without any additional modifications.

CFLog4j includes a class loader that will allow you to use the most recent version of Log4j. CF8 ships with an older version, and the one that comes with CFLog4j is also not the most recent, so I recommend downloading the latest stable build of 1.2.x (1.2.15 as of this writing). Learning to use CFLog4j for disk-based logs was an important step in my development of understanding about Log4j, so I encourage you to experiment with it.

Once you have downloaded the most recent versions of the files, configuring CFLog4j is fairly straightforward. There are two configuration files that you will be concerned with:

1. cflog4j.xml – This file is CFLog4j specific and contains the location of the properties and log4j jar files. You will need to update the file to point to the location of cflog4j.properties (for now just leave it in the same place as the xml file), and to the location of the log4j jar file.

2. cflog4j.properties – This file is not unique to CFLog4j. This is a typical Log4j properties file that could be from any Java application. It defines all of the configuration details for your Loggers. I recommend sticking with the parameters Qasim set up in his example file, with the exception of the File property which you should change to the location where you want your log file to be written.

The CFLog4j.properties File

As I mentioned above, this file is not unique to CFLog4j. Any application using Log4j will have to configure the Logger objects somehow. This can be done programmatically but is commonly done through configuration files. Log4j has the ability to use XML-based configuration, or more typically, a Java .properties file.

I am not going to get into too much depth about this file as there are extensive articles written about it; here is a good one. The one detail I really want to point out is the property for the Appender. The Log4j Appender is what actually writes the log information out to the storage medium. It is also the object that we will be extending in order to write to a database. Log4j comes with a JDBCAppender class that can be used to write to a database but it is not appropriate for use from ColdFusion.

At this point you should be able to use the supplied testCFLogger.cfm file to write some test logs. Note that if you changed the location of the XML configuration file (so that it is not in the same directory as the CFLog4j CFC’s) you will need to pass in the path to the constructor of the Configurator object.

Now that you can write your logs to disk, my next posts talks about writing them to a database.