Package com.apama.util

Class Logger

  • public class Logger
extends java.lang.Object
    The Logger class is a logging facade used by Apama's Java client API, and also by Apama classes and user-defined plug-ins that run inside the correlator and IAF processes.

    When logging from your own classes our best practice recommendations are:

    • Correlator plug-ins: Use either SLF4J or this Logger class, and prefix your logger names with "plugins." where possible, for example "plugins.mypackage.MyPlugin". If you're writing a connectivity plug-in, use the SLF4J logger instance passed to your plug-in's constructor. The correlator's root classloader contains both the SLF4J API and an implementation that sends all SLF4J and Log4j 2 logging to the correlator log file as well as the necessary Log4j configuration, so if you choose to code your plug-ins against SLF4J you just need to add the SLF4J API to your classpath at compilation time. The correlator usually runs with INFO level logging. The main Apama documentation describes how log levels can be customized for individual log categories by specifying correlatorLogging in a correlator YAML configuration file.
    • IAF plug-ins: Use this Logger class, which will send log output to the IAF log file. The IAF usually runs with INFO level logging.
    • External clients: Use this Logger class, or the SLF4J API and Log4j 2 implementation. Since Apama's client libraries use the com.apama.util.Logger facade which writes to Log4j 2 by default, if you wish to have your own logging go to the same place without coupling it tightly to the Apama Logger class you could code again the SLF4J API and then add the SLF4J API, Log4J 2 SLF4J implementation, and Log4j 2 API and core implementation jars to your classpath. You will also need to provide a Log4j configuration file; see Log4j documentation for detailed information about how to do that.

    The Apama Logger writes log messages to Log4j 2 by default (except in the IAF where it goes directly to the IAF log file). It is also possible to configure it to use a non-production "simple" logging implementation that does not require Log4j (by setting -DAPAMA_LOG_IMPL=simple). However we recommend sticking with the default Log4j implementation, as the behavior of the simple logging implementation may change in future releases. Some of the configuration constants on this class only apply to the simple logging implementation and should be ignored if it is not being used.

    Users are encouraged not to use the FATAL or CRIT log levels provided by this 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.

    Example usage of this class: 
    
    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); 
          }
       }
    }
    See the main documentation for information about configuring log levels in the correlator using correlatorLogging, and also information about handling personal data that may appear when logging from Apama applications. The Javadoc for the LOG_LEVEL_PROPERTY_NAME constant has information about configuring the default log level using system properties which can be useful for quickly turning up the log level for specific packages if running outside the correlator.
    See Also:
    getLogger(Class)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ALL_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String CRIT_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String DEBUG_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String DEFAULT_LOG_FILENAME
      The default log filename to be used if the "simple" logging implementation is selected.
      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 WARN_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 the log level with the setThreshold() method.
      static java.lang.String FATAL_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String FORCE_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String INFO_STR
      Constant for configuring the 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; only applicable when the "simple" logger is in use.
      static java.lang.String LOG_IMPL_LOG4J
      Constant for configuring the 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 the 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 root logger's 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 the log level with the setThreshold() method.
      static java.lang.String TRACE_STR
      Constant for configuring the log level with the setThreshold() method.
      static java.lang.String VERSION_COMMENT
      This is the string that is logged when the logger initializes.
      static java.lang.String WARN_STR
      Constant for configuring the log level with the setThreshold() method.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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 logging is enabled at 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 logging is enabled at 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 logging is enabled at 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 logging is enabled at 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 logging is enabled at 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 logging is enabled at 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 trace​(java.lang.String msg)
      Logs the specified message at TRACE level.
      void trace​(java.lang.String msg, java.lang.Throwable ex)
      Logs the specified message at TRACE level, followed by a stack trace for the exception.
      boolean traceEnabled()
      Determines if logging is enabled at TRACE level for this logger instance.
      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 logging is enabled at 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 initializes.
        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 root logger's log level. The value is APAMA_LOG_LEVEL. It is also possible to set log levels for individual log categories by appending a colon and the category name. For example: -DAPAMA_LOG_LEVEL:org.mycompany.MyClass=DEBUG
        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; only applicable when the "simple" logger is in use. 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

      • DEFAULT_LOG_LEVEL

        public static final java.lang.String DEFAULT_LOG_LEVEL
        The default log level is equal to WARN_STR.
        See Also:
        Constant Field Values

      • LOG_IMPL_LOG4J

        public static final java.lang.String LOG_IMPL_LOG4J
        Constant for configuring the 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 the log implementation is equal to "simple".
        See Also:
        Constant Field Values

      • DEFAULT_LOG_FILENAME

        public static final java.lang.String DEFAULT_LOG_FILENAME
        The default log filename to be used if the "simple" logging implementation is selected. The default destination is the console, using stdout for DEBUG, INFO and WARN, and using stderr for ERROR and FATAL.

      • 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 equivalent 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.

      • traceEnabled

        public boolean traceEnabled()
        Determines if logging is enabled at TRACE level for this logger instance.

      • debugEnabled

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

      • infoEnabled

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

      • warnEnabled

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

      • errorEnabled

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

      • fatalEnabled

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

      • critEnabled

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

      • forceEnabled

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

      • trace

        public void trace​(java.lang.String msg)
        Logs the specified message at TRACE level.

      • trace

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

      • 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.

        • Callers are encouraged to use this method in code paths that are executed very frequently (such as code within a message processing loop) - to avoid cluttering the log with lots of long stack traces if many warnings occur, which would reduce performance and readability.
        • However it is best to use warn(String, Throwable) when the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code) - to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not 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 (": ").
        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.

        • Callers are encouraged to use this method in code paths that are executed very frequently (such as code within a message processing loop) - to avoid cluttering the log with lots of long stack traces if many errors occur, which would reduce performance and readability.
        • However it is best to use error(String, Throwable) when the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code) - to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not 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 (": ").
        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. Instead of FATAL level, it is recommended to use ERROR for all errors.

      • 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. Instead of FATAL level, it is recommended to use ERROR for all errors.

      • crit

        public void crit​(java.lang.String msg)
        Logs the specified message at CRIT level. Instead of CRIT level, it is recommended to use INFO for informational messages and ERROR for errors.

      • 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. Instead of CRIT level, it is recommended to use ERROR for errors.

      • 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.