com.apama.util
Class Logger

java.lang.Object
  extended by com.apama.util.Logger

public class Logger
extends java.lang.Object

The Logger class provides access to the logging functionality used by Apama Java classes.

An instance of the Logger can be obtained by using one of the getLogger() static factory methods.

Example usage

    import com.apama.util.Logger;
 
    class MyClass {
       private static final Logger logger = Logger.getLogger(MyClass.class);
       public static void main(String[] args) {
          logger.debug("Message to be logged at DEBUG level");
          
          try
          {
             // some operation
          } catch (IllegalArgumentException e)
          {
             // log the specified message at ERROR, but log the stack trace only if DEBUG logging is enabled
             // (alternatively, use the error(Exception,String) method to log the entire stack trace at ERROR level) 
             logger.errorWithDebugStackTrace("My operation failed: ", e); 
          }
       }
    }
 

If the logger is being used in a multi-classloader application (e.g. Tomcat), please make sure the shutdown() method is invoked after the last message has been logged.

Configuring the logging implementation

The underlying logging implementation used by this class can be configured using the APAMA_LOG_IMPL system property. The main implementations are the SimpleLogger and the Log4JLogger (which provides additional functionality such as hierarchical categories). By default, Log4J is always given preference over the SimpleLogger if it is available.
In order to force use of the SimpleLogger, specify the following system property:
-DAPAMA_LOG_IMPL=simple

When using the SimpleLogger, or when a Log4J configuration file cannot be found, the log level (threshold) may be set at any of the following levels (listed in order) by setting the system property APAMA_LOG_LEVEL:

   OFF, DEBUG, INFO, WARN, ERROR, FATAL, CRIT, ALL

When using the SimpleLogger, or when a Log4J configuration file cannot be found, the output destination may be set by using the system property APAMA_LOG_FILE. The default destination is the console, using stdout for DEBUG, INFO and WARN, and using stderr for ERROR and FATAL.

The Log4J logging system can be more finely configured by use of a configuration file. The location of the file can be specified by a java system property as follows:
-Dlog4j.configuration=file:log4j.properties
If the value of this property is a valid URL then the file is loaded from that location, otherwise it is used to specify the filename that will be loaded from the classpath.

If a Log4J configuration file cannot be found, then the values of the APAMA_LOG_LEVEL and APAMA_LOG_FILE system properties will take effect just as they do for the SimpleLogger.

Example content for a log4j.properties file:


 # Log4j config file for Apama
 # Create an appender, one called stdout
 log4j.rootLogger=DEBUG,stdout
 
 # Configure stdout appender to go to console
 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
 
 # Configure stdout appender to use pattern layout
 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

 # Configure the pattern to output the caller's filename and line number
 log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p [%t] - <%c>: %m%n
 
 # Change this to alter log level for Apama classes only - For example:
 #log4j.logger.com.apama=WARN
 #log4j.logger.com.apama.model=INFO
 #log4j.logger.com.apama.emm=INFO
 #log4j.logger.com.apama.emm.swing.GuiController=DEBUG
 

See Also:
LogLevel, getLogger(Class)

Field Summary
static java.lang.String ALL_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String CRIT_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String DEBUG_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String DEFAULT_LOG_FILENAME
          The default log filename is null, which will cause stdout/err to be used instead.
static java.lang.String DEFAULT_LOG_IMPL
          The default log implementation is equal to LOG_IMPL_LOG4J.
static java.lang.String DEFAULT_LOG_INCREMENTAL_TIME
          The default value for the system property indicating if the Logger implementation named "simple" will log the time since the last log statement - useful to set to true occasionally when diagnosing performance issues.
static java.lang.String DEFAULT_LOG_LEVEL
          The default log level is equal to ERROR_STR.
static java.lang.String DEFAULT_LOG_RELATIVE_TIME
          The default value for the system property indicating if the Logger implementation named "simple" will log the number of seconds since the logger was first used - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.
static java.lang.String DEFAULT_LOG_THREADNAME
          The default value for the system property indicating if the Logger implementation named "simple" will log the name of the calling thread - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.
static java.lang.String DEFAULT_LOG_TIME
          The default value for the system property indicating if the Logger implementation named "simple" will log the current date/time - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.
static java.lang.String ERROR_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String FATAL_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String FORCE_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String INFO_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String LOG_FILENAME_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure the default log output destination.
static java.lang.String LOG_IMPL_LOG4J
          Constant for configuring log implementation is equal to "log4j".
static java.lang.String LOG_IMPL_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure the default log implementation.
static java.lang.String LOG_IMPL_SIMPLE
          Constant for configuring log implementation is equal to "simple".
static java.lang.String LOG_INCREMENTAL_TIME_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the number of seconds since the last log statement.
static java.lang.String LOG_LEVEL_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure the default log level.
static java.lang.String LOG_RELATIVE_TIME_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the number of seconds since the logger was first used.
static java.lang.String LOG_STACK_TRACE_FILENAME_PROPERTY_NAME
          A full path to a file that will be overwritten with the latest stack trace if periodic stack traces were enabled using the APAMA_LOG_STACK_TRACE_INTERVAL property.
static java.lang.String LOG_STACK_TRACE_INTERVAL_PROPERTY_NAME
          The interval, in milliseconds, between logging of this process's stack by the JVMUtil class.
static java.lang.String LOG_THREADNAME_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the name of the calling thread.
static java.lang.String LOG_TIME_PROPERTY_NAME
          Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the current date/time.
static java.lang.String OFF_STR
          Constant for configuring log level with the setThreshold() method.
static java.lang.String VERSION_COMMENT
          This is the string that is logged when the logger initialises.
static java.lang.String WARN_STR
          Constant for configuring log level with the setThreshold() method.
 
Method Summary
 void crit(java.lang.String msg)
          Logs the specified message at CRIT level.
 void crit(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at CRIT level, followed by a stack trace for the exception.
 boolean critEnabled()
          Determines if the logging is enabled at the CRIT level for this Logger instance.
 void debug(java.lang.String msg)
          Logs the specified message at DEBUG level.
 void debug(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at DEBUG level, followed by a stack trace for the exception.
 boolean debugEnabled()
          Determines if the logging is enabled at the DEBUG level for this Logger instance.
 void error(java.lang.String msg)
          Logs the specified message at ERROR level.
 void error(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at ERROR level, followed by a stack trace for the exception.
 boolean errorEnabled()
          Determines if the logging is enabled at the ERROR level for this Logger instance.
 void errorWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at ERROR level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level.
 void fatal(java.lang.String msg)
          Logs the specified message at FATAL level.
 void fatal(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at FATAL level, followed by a stack trace for the exception.
 boolean fatalEnabled()
          Determines if the logging is enabled at the FATAL level for this Logger instance.
 void force(java.lang.String msg)
          Always logs the specified message.
 void force(java.lang.String msg, java.lang.Throwable ex)
          Always logs the specified message, followed by a stack trace for the exception.
 boolean forceEnabled()
          Determines if the logging is enabled at the FORCE level for this Logger instance.
static Logger getLogger()
          Factory method - use to get the default instance of a logger.
static Logger getLogger(java.lang.Class<?> clazz)
          Factory method - use to get an instance of a logger.
static Logger getLogger(java.lang.String name)
          Factory method - use to get an instance of a logger.
 void info(java.lang.String msg)
          Logs the specified message at INFO level.
 void info(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at INFO level, followed by a stack trace for the exception.
 boolean infoEnabled()
          Determines if the logging is enabled at the INFO level for this Logger instance.
 void setThreshold(java.lang.String levelStr)
          Sets the logging threshold for this instance of Logger.
static void shutdown()
          Performs any necessary cleanup for this logger.
 void warn(java.lang.String msg)
          Logs the specified message at WARN level.
 void warn(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at WARN level, followed by a stack trace for the exception.
 boolean warnEnabled()
          Determines if the logging is enabled at the WARN level for this Logger instance.
 void warnWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex)
          Logs the specified message at WARN level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION_COMMENT

public static final java.lang.String VERSION_COMMENT
This is the string that is logged when the logger initialises.

See Also:
Constant Field Values

LOG_IMPL_PROPERTY_NAME

public static final java.lang.String LOG_IMPL_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure the default log implementation. The value is normally APAMA_LOG_IMPL.

See Also:
Constant Field Values

LOG_LEVEL_PROPERTY_NAME

public static final java.lang.String LOG_LEVEL_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure the default log level. The value is normally APAMA_LOG_LEVEL.

See Also:
Constant Field Values

LOG_FILENAME_PROPERTY_NAME

public static final java.lang.String LOG_FILENAME_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure the default log output destination. The value is normally APAMA_LOG_FILE.

See Also:
Constant Field Values

LOG_STACK_TRACE_INTERVAL_PROPERTY_NAME

public static final java.lang.String LOG_STACK_TRACE_INTERVAL_PROPERTY_NAME
The interval, in milliseconds, between logging of this process's stack by the JVMUtil class. Turned off by default. If enabled, writes to the log at WARN level unless the APAMA_LOG_STACK_TRACE_FILENAME property is specified.

See Also:
Constant Field Values

LOG_STACK_TRACE_FILENAME_PROPERTY_NAME

public static final java.lang.String LOG_STACK_TRACE_FILENAME_PROPERTY_NAME
A full path to a file that will be overwritten with the latest stack trace if periodic stack traces were enabled using the APAMA_LOG_STACK_TRACE_INTERVAL property. If this is not specified, stack traces will be written to the main log.

See Also:
Constant Field Values

ALL_STR

public static final java.lang.String ALL_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

CRIT_STR

public static final java.lang.String CRIT_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

DEBUG_STR

public static final java.lang.String DEBUG_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

INFO_STR

public static final java.lang.String INFO_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

WARN_STR

public static final java.lang.String WARN_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

ERROR_STR

public static final java.lang.String ERROR_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

FATAL_STR

public static final java.lang.String FATAL_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

FORCE_STR

public static final java.lang.String FORCE_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

OFF_STR

public static final java.lang.String OFF_STR
Constant for configuring log level with the setThreshold() method.

See Also:
Constant Field Values

DEFAULT_LOG_LEVEL

public static final java.lang.String DEFAULT_LOG_LEVEL
The default log level is equal to ERROR_STR.

See Also:
Constant Field Values

LOG_IMPL_LOG4J

public static final java.lang.String LOG_IMPL_LOG4J
Constant for configuring log implementation is equal to "log4j".

See Also:
Constant Field Values

LOG_IMPL_SIMPLE

public static final java.lang.String LOG_IMPL_SIMPLE
Constant for configuring log implementation is equal to "simple".

See Also:
Constant Field Values

DEFAULT_LOG_IMPL

public static final java.lang.String DEFAULT_LOG_IMPL
The default log implementation is equal to LOG_IMPL_LOG4J.

See Also:
Constant Field Values

DEFAULT_LOG_FILENAME

public static final java.lang.String DEFAULT_LOG_FILENAME
The default log filename is null, which will cause stdout/err to be used instead.


LOG_THREADNAME_PROPERTY_NAME

public static final java.lang.String LOG_THREADNAME_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the name of the calling thread. The value is normally APAMA_LOG_THREAD.

See Also:
Constant Field Values

LOG_TIME_PROPERTY_NAME

public static final java.lang.String LOG_TIME_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the current date/time. The value is normally APAMA_LOG_TIME.

See Also:
Constant Field Values

LOG_RELATIVE_TIME_PROPERTY_NAME

public static final java.lang.String LOG_RELATIVE_TIME_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the number of seconds since the logger was first used. The value is normally APAMA_LOG_RELATIVE_TIME.

See Also:
Constant Field Values

LOG_INCREMENTAL_TIME_PROPERTY_NAME

public static final java.lang.String LOG_INCREMENTAL_TIME_PROPERTY_NAME
Constant that provides the name of the system property that is used to configure if the Logger implementation named "simple" will log the number of seconds since the last log statement. The value is normally APAMA_LOG_INCREMENTAL_TIME.

See Also:
Constant Field Values

DEFAULT_LOG_THREADNAME

public static final java.lang.String DEFAULT_LOG_THREADNAME
The default value for the system property indicating if the Logger implementation named "simple" will log the name of the calling thread - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.

See Also:
Constant Field Values

DEFAULT_LOG_TIME

public static final java.lang.String DEFAULT_LOG_TIME
The default value for the system property indicating if the Logger implementation named "simple" will log the current date/time - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.

See Also:
Constant Field Values

DEFAULT_LOG_RELATIVE_TIME

public static final java.lang.String DEFAULT_LOG_RELATIVE_TIME
The default value for the system property indicating if the Logger implementation named "simple" will log the number of seconds since the logger was first used - currently "false" for backwards compatibility of log file format, but may change to "true" in a future release.

See Also:
Constant Field Values

DEFAULT_LOG_INCREMENTAL_TIME

public static final java.lang.String DEFAULT_LOG_INCREMENTAL_TIME
The default value for the system property indicating if the Logger implementation named "simple" will log the time since the last log statement - useful to set to true occasionally when diagnosing performance issues.

See Also:
Constant Field Values
Method Detail

getLogger

public static Logger getLogger()
Factory method - use to get the default instance of a logger.


getLogger

public static Logger getLogger(java.lang.String name)
Factory method - use to get an instance of a logger.


getLogger

public static Logger getLogger(java.lang.Class<?> clazz)
Factory method - use to get an instance of a logger. This method is eqivalent to calling getLogger( clazz.getName() )


shutdown

public static void shutdown()
Performs any necessary cleanup for this logger.

See Also:
Logger.LoggerFactory.shutdown()

setThreshold

public void setThreshold(java.lang.String levelStr)
Sets the logging threshold for this instance of Logger. If the levelStr is not a valid level, then the default level will be used.


debugEnabled

public boolean debugEnabled()
Determines if the logging is enabled at the DEBUG level for this Logger instance.


infoEnabled

public boolean infoEnabled()
Determines if the logging is enabled at the INFO level for this Logger instance.


warnEnabled

public boolean warnEnabled()
Determines if the logging is enabled at the WARN level for this Logger instance.


errorEnabled

public boolean errorEnabled()
Determines if the logging is enabled at the ERROR level for this Logger instance.


fatalEnabled

public boolean fatalEnabled()
Determines if the logging is enabled at the FATAL level for this Logger instance.


critEnabled

public boolean critEnabled()
Determines if the logging is enabled at the CRIT level for this Logger instance.


forceEnabled

public boolean forceEnabled()
Determines if the logging is enabled at the FORCE level for this Logger instance.


debug

public void debug(java.lang.String msg)
Logs the specified message at DEBUG level.


debug

public void debug(java.lang.String msg,
                  java.lang.Throwable ex)
Logs the specified message at DEBUG level, followed by a stack trace for the exception.


info

public void info(java.lang.String msg)
Logs the specified message at INFO level.


info

public void info(java.lang.String msg,
                 java.lang.Throwable ex)
Logs the specified message at INFO level, followed by a stack trace for the exception.


warn

public void warn(java.lang.String msg)
Logs the specified message at WARN level.

Note that if the warning is being logged because an exception was caught, users are strongly discouraged from calling this method and logging the exception object (or its message) using the msg string argument. Instead, call warn(String, Throwable) or warnWithDebugStackTrace(String, Throwable) so that all of the valuable diagnostic information from the exception object is available in the log.


warn

public void warn(java.lang.String msg,
                 java.lang.Throwable ex)
Logs the specified message at WARN level, followed by a stack trace for the exception.

See Also:
warnWithDebugStackTrace

warnWithDebugStackTrace

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

This method is more appropriate for performance-critical code than warn(String, Throwable), because it does not log the stack trace unless DEBUG level logging has been enabled.

Parameters:
msg - The message to be logged. Information from the exception object will be automatically appended to the end of this message, so it is recommended that msg ends with a colon and space, i.e. ": ".
ex - The exception object associated with this warning.
Since:
4.3.0.0
See Also:
warn

error

public void error(java.lang.String msg)
Logs the specified message at ERROR level.

Note that if the error is being logged because an exception was caught, users are strongly discouraged from calling this method and logging the exception object (or its message) using the msg string argument. Instead, call error(String, Throwable) or errorWithDebugStackTrace(String, Throwable) so that all of the valuable diagnostic information from the exception object is available in the log.


error

public void error(java.lang.String msg,
                  java.lang.Throwable ex)
Logs the specified message at ERROR level, followed by a stack trace for the exception.

See Also:
errorWithDebugStackTrace

errorWithDebugStackTrace

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

This method is more appropriate for performance-critical code than error(String, Throwable), because it does not log the stack trace unless DEBUG level logging has been enabled.

Parameters:
msg - The message to be logged. Information from the exception object will be automatically appended to the end of this message, so it is recommended that msg ends with a colon and space, i.e. ": ".
ex - The exception object associated with this error.
Since:
4.3.0.0
See Also:
error

fatal

public void fatal(java.lang.String msg)
Logs the specified message at FATAL level.


fatal

public void fatal(java.lang.String msg,
                  java.lang.Throwable ex)
Logs the specified message at FATAL level, followed by a stack trace for the exception.


crit

public void crit(java.lang.String msg)
Logs the specified message at CRIT level.


crit

public void crit(java.lang.String msg,
                 java.lang.Throwable ex)
Logs the specified message at CRIT level, followed by a stack trace for the exception.


force

public void force(java.lang.String msg)
Always logs the specified message.


force

public void force(java.lang.String msg,
                  java.lang.Throwable ex)
Always logs the specified message, followed by a stack trace for the exception.



Submit a bug or feature
Copyright (c) 2013-2014 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its Subsidiaries and or/its Affiliates and/or their licensors. Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG.