Home > DOCUMENTUM > Enabling Logging in DFC Applications

Enabling Logging in DFC Applications

November 1, 2010

Log4j is a Java based logging utility primarily used as a debugging tool. It’s an open source project of Apache Software Foundation that provides a reliable, fast and extensible logging library for Java.

Dflogger is a Documentum DFC class (available with version 5.1 and higher) that can be used to enable logging from DFC Applications. This post describes how to configure and use the logging library from DFC.

Enabling Logging:
Let us have a look at how to enable logging for a java application.
Open the $DOCUMENTUM/config/log4j.properties file (created during the DFC install itself). And, enter the following lines of code at the end of the file and save it.
# Enable log messages for a custom class
log4j.logger.com.documentum.custom.webui=DEBUG,WebUI
#WebUI Appender
log4j.appender.WebUI=org.apache.log4j.RollingFileAppender
log4j.appender.WebUI.File=C\:/WebUI.log
log4j.appender.WebUI.MaxFileSize=10MB
log4j.appender.WebUI.layout=org.apache.log4j.PatternLayout
log4j.appender.WebUI.layout.ConversionPattern=%d{HH:mm:ss} %p %c %m %n

Let us have a look at each of the lines that we have appended to the properties file.
Line 1 : log4j.logger.com.documentum.custom.webui=DEBUG,WebUI
This line specifies the following:
a) the package/class being logged,
b) the priority level – 5 levels of priority are defined in log4j (DEBUG,INFO,WARN,ERROR & FATAL). In our example, we have set it to DEBUG resulting in all messages being logged.
c) the name of the Appender. Log4j allows logging requests to print to multiple destinations. In log4j jargon, an output destination is called an appender. Currently, appenders exist for the console, files, GUI components, remote socket servers, JMS, NT Event Loggers, and remote UNIX Syslog daemons. It is also possible to log asynchronously. We have named our appender WebUI. Lines 2-6 are for configuring the appender.
Line 2 : log4j.appender.WebUI=org.apache.log4j.RollingFileAppender
This line specifies the type of appender to use. RollingFileAppender backs up log files once they reach a max size(specified by the next line).

Line 3 : log4j.appender.WebUI.MaxFileSize=10MB
This line specifies the maximum size of the log file. Once the file reaches this size, the appender backs it up and creates a new log file.
Line 4 : log4j.appender.WebUI.File=C\:/WebUI.log
This line specifies the name of the log file to be created as well as its location. In case the location is not specified, then the log file gets created in the location of the executing class.
Line 5 : log4j.appender.WebUI.layout=org.apache.log4j.PatternLayout
This line specifies that a pattern layout is being used
Line 6 : log4j.appender.WebUI.layout.ConversionPattern=%d{HH:mm:ss} %p %c %m %n
This line specifies the interpretation of the pattern layout. The conversion pattern used here is as follows :
%d{ HH:mm:ss}–date and time of logging, %p- priority level of the message, %c- name of the category (i.e the class/package name),%m- the message, %n- newline character.
Others that could be used are: %t – name of current thread, %F – java source filename, %C –java class name, %M – java method name, %L – java source line number

Now, execution of any of the classes in the webui package will result in the creation of a file called WebUI.log in the specified location (see the entry ‘log4j.appender.WebUI.File’). This is the file into which all the log statements would be written to. But, the log statements cannot come out of thin air, we need to insert a call to DfLogger in our DFC code.
Using DfLogger
To log a message in the log file, we need to insert a call to the DfLogger class in our DFC code. The signature of the method is as follows:
DfLogger.debug(Object arg0, String arg1, String[] arg2, Throwable arg3)
Object arg0 : specifies the class for which the debug message is being logged. Usually, the DfLogger class is called from the class for which we log the message and hence we use the ‘this’ keyword. It refers to the current class instance.
String arg1 : the message to log
String[] arg2 : parameters to use when formatting message
Throwable arg3 : a throwable to log ,can be used to print a stack trace to the log file in case of an exception.
Ex: DfLogger.debug(this,”The Debug Message”,null,dfe);
If we need to print the stack trace of any exception in the class, we need to pass the instance of the Throwable class as the fourth argument.

Ex: catch(DfException dfe){
DfLogger.debug(this,”The Debug Message”,null,dfe);
}
The Outcome
Say, these are DfLogger class calls in our custom code :

DfLogger.error, DfLogger.fatal, DfLogger.info, DfLogger.warn are the method calls to log messages in that priority.
Then, when the user clicks on the link called search, the message gets logged in the log file as follows :

Note the conversion pattern. Also, since we have given the priority level as DEBUG in the properties file, it’s printing out all the log messages i.e other than DEBUG ones. Had we given FATAL (which is the highest level), then only the message for the call DfLogger.fatal(..) would have got logged.

Just a small configurational change and this could go a long way in helping a developer trace the root cause of any issue, understand the application, track the control flow in the application etc. But, one thing needs to be taken care, increasing the number of log messages in an application could bring down its performance.

%d bloggers like this: