public class Logger
extends java.lang.Object
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:
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.
Logger
class, which will send log output to the IAF log file.
The IAF usually runs with INFO level logging. 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.getLogger(Class)
Modifier and Type | Field and 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. |
Modifier and Type | Method and 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.
|
public static final java.lang.String VERSION_COMMENT
public static final java.lang.String LOG_IMPL_PROPERTY_NAME
public static final java.lang.String LOG_LEVEL_PROPERTY_NAME
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
public static final java.lang.String LOG_FILENAME_PROPERTY_NAME
public static final java.lang.String LOG_STACK_TRACE_INTERVAL_PROPERTY_NAME
public static final java.lang.String LOG_STACK_TRACE_FILENAME_PROPERTY_NAME
public static final java.lang.String ALL_STR
setThreshold()
method.public static final java.lang.String CRIT_STR
setThreshold()
method.public static final java.lang.String TRACE_STR
setThreshold()
method.public static final java.lang.String DEBUG_STR
setThreshold()
method.public static final java.lang.String INFO_STR
setThreshold()
method.public static final java.lang.String WARN_STR
setThreshold()
method.public static final java.lang.String ERROR_STR
setThreshold()
method.public static final java.lang.String FATAL_STR
setThreshold()
method.public static final java.lang.String FORCE_STR
setThreshold()
method.public static final java.lang.String OFF_STR
setThreshold()
method.public static final java.lang.String DEFAULT_LOG_LEVEL
WARN_STR
.public static final java.lang.String LOG_IMPL_LOG4J
public static final java.lang.String LOG_IMPL_SIMPLE
public static final java.lang.String DEFAULT_LOG_IMPL
LOG_IMPL_LOG4J
.public static final java.lang.String DEFAULT_LOG_FILENAME
public static final java.lang.String LOG_THREADNAME_PROPERTY_NAME
public static final java.lang.String LOG_TIME_PROPERTY_NAME
public static final java.lang.String LOG_RELATIVE_TIME_PROPERTY_NAME
public static final java.lang.String LOG_INCREMENTAL_TIME_PROPERTY_NAME
public static final java.lang.String DEFAULT_LOG_THREADNAME
public static final java.lang.String DEFAULT_LOG_TIME
public static final java.lang.String DEFAULT_LOG_RELATIVE_TIME
public static final java.lang.String DEFAULT_LOG_INCREMENTAL_TIME
public static Logger getLogger()
public static Logger getLogger(java.lang.String name)
public static Logger getLogger(java.lang.Class<?> clazz)
getLogger( clazz.getName() )
public static void shutdown()
Logger.LoggerFactory.shutdown()
public void setThreshold(java.lang.String levelStr)
public boolean traceEnabled()
public boolean debugEnabled()
public boolean infoEnabled()
public boolean warnEnabled()
public boolean errorEnabled()
public boolean fatalEnabled()
public boolean critEnabled()
public boolean forceEnabled()
public void trace(java.lang.String msg)
public void trace(java.lang.String msg, java.lang.Throwable ex)
public void debug(java.lang.String msg)
public void debug(java.lang.String msg, java.lang.Throwable ex)
public void info(java.lang.String msg)
public void info(java.lang.String msg, java.lang.Throwable ex)
public void warn(java.lang.String msg)
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.
public void warn(java.lang.String msg, java.lang.Throwable ex)
warnWithDebugStackTrace
public void warnWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex)
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.
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. 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.warn
public void error(java.lang.String msg)
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.
public void error(java.lang.String msg, java.lang.Throwable ex)
errorWithDebugStackTrace
public void errorWithDebugStackTrace(java.lang.String msg, java.lang.Throwable ex)
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.
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. 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.error
public void fatal(java.lang.String msg)
public void fatal(java.lang.String msg, java.lang.Throwable ex)
public void crit(java.lang.String msg)
public void crit(java.lang.String msg, java.lang.Throwable ex)
public void force(java.lang.String msg)
public void force(java.lang.String msg, java.lang.Throwable ex)
Submit a bug or feature
Copyright (c) 2013-2019 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.