How to Use OGSA-DAI Logging

OGSA-DAI provides a logging class - uk.org.ogsadai.common.msgs.DAILogger - which you can use to manage logging within any extensions you make to OGSA-DAI.

This class wraps Apache Log4J logging functionality and combines it with OGSA-DAI's support for internationalization and message bundles. This ensures that within OGSA-DAI most messages that are logged are internationalized using the currently available message bundles.

We described message bundles and internationalization in the tutorials on How to Register New Message Bundles and How to Write OGSA-DAI-compliant Exceptions and assume you have read these. We also assume you know How to Enable Logging.

How to create a DAILogger

DAILoggers are typically created on a per-class basis. To use one in one of your classes you would use the static getLogger method as shown in the following example:

package com.example;

import uk.org.ogsadai.common.msgs.DAILogger;

public MyClass
{
    private static final DAILogger LOG = DAILogger.getLogger(MyClass.class);

    public void myMethod() 
    {
        ...
        LOG.debug("This is an example of using DAILogger");
        ...
    } 
}

How to log with a DAILogger

The DAILogger class provides a collection of methods which can be used to log information at various levels. The levels we use are those used by Apache Log4J. These levels, and the information within OGSA-DAI which is logged at those levels, are as follows:

• FATAL - for server-side problems encountered when a service is initialised or when accessing resource-related information.
• ERROR - for server-side problems of concern to a service or resource deployer.
• WARN - for server-side problems that are viewed as of no great concern (e.g. exceptions that are gulped) or for problems caused by information from a client that is in some way problematic.
• INFO - for general status and progress information that may be of use to a service or resource deployer.

As we shall shortly see, DAILogger is very strict as to what information can be logged at each of these levels. There is, however, one additional level at which any information can be logged.

• DEBUG - for general debugging information that may be of use to a developer.

Naturally, it is up to you at what level you log the information in any extensions you make to OGSA-DAI.

How to log FATAL, ERROR and WARNing information

DAILogger provides six methods which allow information to be logged at the FATAL, ERROR and WARN levels. These are the following:

public void warn(Throwable exception)
public void warn(Throwable exception, boolean stackTrace)
public void error(Throwable exception)
public void error(Throwable exception, boolean stackTrace)
public void fatal(Throwable exception)
public void fatal(Throwable exception, boolean stackTrace)

When an exception is passed to these methods the DAILogger will get the exception message from the exception (using the Throwable.getLocalizedMessage method) and log it at the specified level. It will then proceed to any cause exception and log its message likewise until every exception in the causal chain has had its message logged.

For OGSA-DAI-compliant exceptions the implementation of the Throwable.getLocalizedMessage method will internationalize the exception message using the exception's error ID, the associated error key and the current message bundles.

Versions of the logging methods are provided so that you can also request that the entire exception stack trace is logged by passing in a stackTrace flag set to true. We recommend that you do not log stack traces often as they can make server-side logs very difficult to read.

How to log INFO

DAILogger provides three methods which allow information to be logged at the INFO level. These are the following:

public void info(MessageID messageID)
public void info(MessageID messageID, Object parameter)
public void info(MessageID messageID, Object[] parameters)

Note that these take message IDs - internationalization of INFO messages is therefore enforced by OGSA-DAI. Variants of the methods are provided for messages which may take parameters - as defined in the current message bundles.

How to log DEBUG information

DAILogger provides two methods which allow information to be logged at the DEBUG level. These are the following:

public void debug(String message)
public void debug(uk.org.ogsadai.common.msgs.DAIUniqueID id, String message)

Any information can be logged at this level.

The second method is provided so that a message can be indexed by an ID that is guaranteed to be unique.

How to make logging conditional

As mentioned DAILoggers use Apache Log4J. We recommend you follow their best practice and make calls to info or debug conditional if work is required to compute the parameters passed to these methods. We have provided isDebugEnabled or isInfoEnabled methods to support this. For example:

if (LOG.isDebugEnabled())
{
    LOG.debug("Object A : " + objectA.toString() + 
              " Object B : " + objectB.toString());
}
if (LOG.isInfoEnabled())
{
    LOG.info(MessageID.THIS_IS_AN_EXAMPLE, new Object[]{objectA, objectB});
}