Logging from IAF plug-ins in Java

This API provides a mechanism for recording status and error log messages from the IAF runtime and any plug-ins loaded within it. Plug-in developers are encouraged to make use of the logging API instead of custom logging solutions so that all the information may be logged together in the same standard format and log file(s) used by other plug-ins and the IAF runtime.

The logging API also allows control of logging verbosity, so that any messages below the configured logging level will not be written to the log. The logging level and file are initially set when an adapter first starts up – see Logging configuration (optional) for more information about the logging configuration.

The Java logging API is based around the Logger class.

The recommended way of using the Logger class is to have a private final com.apama.util.Logger variable, and then create an instance in the transport or codec's constructor based on the plug-in name, such as the following:

private final Logger logger;
public MyTransport(String name, ...)
{ super(...);
logger = Logger.getLogger(name);
}

The Logger class supports the following logging levels:

It is recommended that you do not use the FATAL or CRIT log levels provided by the Logger class, which are present only for historical reasons. It is better to use ERROR for all error conditions regardless of how fatal they are, and INFO for informational messages. See Setting correlator and plug-in log files and log levels in a YAML configuration file for information about configuring log levels in the correlator.

For each level, there are three main methods. For example, for logging at the DEBUG level, here are the three main methods:

logger.debug(String, Throwable) — Logs the stack trace and message of a caught exception together with a high-level description of the problem. Apama strongly recommend logging exceptions like this to assist with debugging in the event of problems.

logger.debugEnabled() — Determines whether messages at this log level are currently enabled (this depends on the current IAF log level, which may be changed dynamically). Apama strongly recommend checking this method's result (particularly for DEBUG messages) before logging messages where constructing the message string may be costly, for example:

if (logger.debugEnabled())
  logger.debug("A huge message was received, and the string
      representation of it is: "+thing.toString()+
      " and here is some other useful info: "+foo+", "+bar);

Note that there is no point using the Enabled() methods if the log message is a simple string (or string plus exception), such as:

To make it easier to diagnose any errors that may occur, Apama recommends one of the following methods to log the application's stack trace:

errorWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex) — Logs the specified message at the ERROR level followed by the exception's message string, and then logs the exception's stack trace at the DEBUG level.

warnWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex) — Logs the specified message at the WARN level followed by the exception's message string, and then logs the exception's stack trace at the DEBUG level.

See the API Reference for Java (Javadoc) for more information about the Logger class.