com.sleepycat.je.utilint

Class LoggerUtils

java.lang.Object

com.sleepycat.je.utilint.LoggerUtils

public class LoggerUtils
extends Object

Logging Architecture =========================== JE uses the java.util.logging package. The ability to dynamically specify logging levels per component is important functionality for the system. Logging output is directed to the console, to the je.info files, and in special cases, to a MemoryHandler. The latter is meant for debugging and field support. Logging output from multiple environments may end up going to the same handler, either because a single process is executing multiple environments, or because the output of multiple environments, such as a replication group, is combined in a single display. Because of that, it's important for logging output to be prefixed with an environment id so it can be distinguished by environment. Loggers managed by java.util.logging.LogManager are supposed to be maintained with a weak reference by the LogManager. In our experience, loggers do not seem to be released, and seem to accumulate in memory. Because of that, we create a single logger per JE class, rather than a logger per class instance. The latter would be more convenient, because we wish to use environment specific information, such as the environment name as a prefix, or the location of the je.info file, when creating output. Restricting ourselves to a single per-class logger requires that we keep the logger and its associated handlers and formatters stateless, because the logger may be shared by multiple environments. To compensate for that, we use per-thread state to permit per-environment customization of the logging output (that is the logging prefix) and file handler location. Because we've seen some performance issues with ThreadLocals, we elected instead to maintain a per-thread map to store state information needed by the logger. This state information is: - the environment impl from the envMap(from which one can obtain the prefix and the console, file and memory handlers to use) - or if the environment impl is null because the component executes without an environment, the output will go to only a console handler. It will use a particular formatter to prefix the output with a useful id. This is obtained from the formatter map. With this scheme, a JE process has a maximum of - N loggers, where N is the number of classes which get loggers - 3 handlers * number of environments, because each environment creates a Console, File and Memory handler. How To Use Logging in a JE Class ======================================= Creating a Logger: There are three kinds of loggers that a class may chose to use. 1. A class with a reference to EnvironmentImpl or RepImpl should use LoggerUtils.getLogger(Class<?>) to create a logger which prefixes its output with an environment id. When a logger is obtained this way, the logger should not be used directly. Instead, LoggerUtils provides several methods like this: LoggerUtils.severe() equals to logger.severe LoggerUtils.warning() equals to logger.warning etc LoggerUtils.logMsg(Logger, EnvironmentImpl, Level, String) equals to logger.log(Level, String) 2. A class without an EnvironmentImpl which still has some kind of custom information to prepend to the logging output should use LoggerUtils.getFormatterNeeded(). For example, com.sleepycat.je.rep.monitor.Monitor does not have an environment, but does have a NameIdPair, and it can insert that information via a specific Formatter. When using this logger, the class must create and maintain a Formatter instance to pass as a logging parameter. When using this flavor, use: LoggerUtils.logMsg(Logger, Formatter, Level, String) where the formatter is the one created by the using class. 3. A logger without an EnvironmentImpl does not prefix or customize the logging output, and uses LoggerUtils.getLoggerFixedPrefix to create a logger. In this case, use the usual java.util.logging.Logger logging methods. Note: there are some JE classes which only conditionally reference an environment. In that case, the environment must also conditionally create a logger, and then use the wrapper methods which use both an environmentImpl and a formatter. For example: if (envImpl != null) { logger = LoggerUtils.getLogger(getClass()); } else { logger = LoggerUtils.getLoggerFormatterNeeded(); } formatter = new Formatter(.....); Then use LoggerUtils.logMsg(Logger, EnvironmentImpl, Formatter, Level, String) instead of Logger.log(Level, String)

Field Summary

Fields

Modifier and Type	Field and Description
static String	FIXED_PREFIX
static String	NO_ENV

Constructor Summary

Constructors

Constructor and Description
LoggerUtils()

Method Summary

Modifier and Type	Method and Description
static void	envLogMsg(Level logLevel, EnvironmentImpl envImpl, String msg) Use the environment logger.
static String	exceptionTypeAndMsg(Exception e) Displays both the exception class and the message.
static void	fine(Logger useLogger, EnvironmentImpl envImpl, String msg)
static void	finer(Logger useLogger, EnvironmentImpl envImpl, String msg)
static void	finest(Logger useLogger, EnvironmentImpl envImpl, String msg)
static void	fullThreadDump(Logger logger, EnvironmentImpl envImpl, Level level) Logs a full thread dump as if jstack were piped to the je.info file.
static Level	getHandlerLevel(DbConfigManager configManager, ConfigParam param, String levelName)
static Logger	getLogger(Class<?> cl) Get a logger which is configured to use the shared console, memory, and file handlers of an EnvironmentImpl and prefixes all messages with an environment identifier.
static Logger	getLoggerFixedPrefix(Class<?> cl, String prefix)
static Logger	getLoggerFixedPrefix(Class<?> cl, String prefix, EnvironmentImpl envImpl) Get a logger that uses the generic console handler, with no attempt to use thread local state to customize the message prefix.
static Logger	getLoggerFormatterNeeded(Class<?> cl) Get a logger which only publishes to a console handler.
static String	getLoggerProperty(String property)
static Level	getPushLevel(String name) Get the push level for the MemoryHandler.
static String	getStackTrace() Return the stack trace of the caller, for debugging.
static String	getStackTrace(Throwable t) Return a String version of a stack trace
static void	info(Logger useLogger, EnvironmentImpl envImpl, String msg)
static void	logMsg(Logger useLogger, EnvironmentImpl envImpl, Formatter formatter, Level logLevel, String msg) Log a message using this logger.
static void	logMsg(Logger useLogger, EnvironmentImpl envImpl, Level logLevel, String msg) Log a message using this logger.
static void	logMsg(Logger useLogger, Formatter formatter, Level logLevel, String msg) Log a message with this logger.
static <T> void	logMsg(RateLimitingLogger<T> useLogger, EnvironmentImpl envImpl, T object, Level logLevel, String msg) Log a message using the given RateLimitingLogger.
static void	severe(Logger useLogger, EnvironmentImpl envImpl, String msg)
static void	traceAndLog(Logger logger, EnvironmentImpl envImpl, Level logLevel, String msg) Records a message both to the java.util.logging loggers and through the trace system which writes to the .jdb files.
static void	traceAndLogException(EnvironmentImpl envImpl, String sourceClass, String sourceMethod, String msg, Throwable t) Logger method for recording an exception and stacktrace to both the java.util.logging system and the .jdb files.
static void	warning(Logger useLogger, EnvironmentImpl envImpl, String msg)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_ENV

public static final String NO_ENV

See Also:

Constant Field Values

FIXED_PREFIX

public static final String FIXED_PREFIX

See Also:

Constant Field Values

Constructor Detail

LoggerUtils

public LoggerUtils()

Method Detail

getLogger

public static Logger getLogger(Class<?> cl)

Get a logger which is configured to use the shared console, memory, and file handlers of an EnvironmentImpl and prefixes all messages with an environment identifier. Use this for classes which have a reference to an EnvironmentImpl (or RepImpl). When a logger is obtained this way, the logger should not be used directly. Instead, the wrapper methods in LoggerUtils which put and remove the environment from the envMap must be used, so that the logging output can be properly prefixed and redirected to the correct environment.

getLoggerFormatterNeeded

public static Logger getLoggerFormatterNeeded(Class<?> cl)

Get a logger which only publishes to a console handler. The logging output is prefixed in a custom way, using the formatter map to access the proper state. This should be used by a class that does not have an EnvironmentImpl, but still wishes to prepend some kind of custom prefix to the logging output. When a logger is obtained this way, the logger should not be used directly. Instead, the wrapper methods in LoggerUtils which use a Formatter parameter, and put and remove the environment from the formatterMap must be used, so that the logging output can be properly prefixed and redirected to the correct environment.

getLoggerFixedPrefix

public static Logger getLoggerFixedPrefix(Class<?> cl,
                                          String prefix)

getLoggerFixedPrefix

public static Logger getLoggerFixedPrefix(Class<?> cl,
                                          String prefix,
                                          EnvironmentImpl envImpl)

Get a logger that uses the generic console handler, with no attempt to use thread local state to customize the message prefix.

getLoggerProperty

public static String getLoggerProperty(String property)

getPushLevel

public static Level getPushLevel(String name)

Get the push level for the MemoryHandler.

logMsg

public static void logMsg(Logger useLogger,
                          EnvironmentImpl envImpl,
                          Level logLevel,
                          String msg)

Log a message using this logger. We expect that this logger is one that has been configured to expect an environment. This utility method should be used to ensure that the thread specific context is pushed before logging, and cleared afterwards.

logMsg

public static <T> void logMsg(RateLimitingLogger<T> useLogger,
                              EnvironmentImpl envImpl,
                              T object,
                              Level logLevel,
                              String msg)

Log a message using the given RateLimitingLogger. We expect that this RLL wraps a Logger that has been configured to expect an environment. This utility method should be used to ensure that the thread specific context is pushed before logging, and cleared afterwards.

envLogMsg

public static void envLogMsg(Level logLevel,
                             EnvironmentImpl envImpl,
                             String msg)

Use the environment logger.

logMsg

public static void logMsg(Logger useLogger,
                          EnvironmentImpl envImpl,
                          Formatter formatter,
                          Level logLevel,
                          String msg)

Log a message using this logger. The logger may be either one that expects to use the state in the envMap (obtained via getLogger(), or it may be one that expects to use the state in the formatter map (obtained via getLoggerFormatterNeeded(). This method checks whether the EnvironmentImpl is null or not and choses the appropriate state type to use.

severe

public static void severe(Logger useLogger,
                          EnvironmentImpl envImpl,
                          String msg)

warning

public static void warning(Logger useLogger,
                           EnvironmentImpl envImpl,
                           String msg)

info

public static void info(Logger useLogger,
                        EnvironmentImpl envImpl,
                        String msg)

fine

public static void fine(Logger useLogger,
                        EnvironmentImpl envImpl,
                        String msg)

finer

public static void finer(Logger useLogger,
                         EnvironmentImpl envImpl,
                         String msg)

finest

public static void finest(Logger useLogger,
                          EnvironmentImpl envImpl,
                          String msg)

logMsg

public static void logMsg(Logger useLogger,
                          Formatter formatter,
                          Level logLevel,
                          String msg)

Log a message with this logger. This utility method should be used in tandem with loggers obtained via getLoggerFormatterNeeded() to ensure that the thread specific Formatter is pushed before logging, and cleared afterwards.

traceAndLogException

public static void traceAndLogException(EnvironmentImpl envImpl,
                                        String sourceClass,
                                        String sourceMethod,
                                        String msg,
                                        Throwable t)

Logger method for recording an exception and stacktrace to both the java.util.logging system and the .jdb files.

traceAndLog

public static void traceAndLog(Logger logger,
                               EnvironmentImpl envImpl,
                               Level logLevel,
                               String msg)

Records a message both to the java.util.logging loggers and through the trace system which writes to the .jdb files. The logLevel parameter only applies to the java.util.logging system. Trace messages are unconditionally written to the .jdb files. Because of that, this method should be used sparingly, for critical messages.

getStackTrace

public static String getStackTrace(Throwable t)

Return a String version of a stack trace

getStackTrace

public static String getStackTrace()

Return the stack trace of the caller, for debugging.

getHandlerLevel

public static Level getHandlerLevel(DbConfigManager configManager,
                                    ConfigParam param,
                                    String levelName)

fullThreadDump

public static void fullThreadDump(Logger logger,
                                  EnvironmentImpl envImpl,
                                  Level level)

Logs a full thread dump as if jstack were piped to the je.info file. Only one dump per EnvironmentImpl lifetime is allowed. Allowing multiple dumps can causes them to be interleaved, and risks filling the je.info files with repeated dumps. The envImpl should be invalidated when this method is called, so one dump should be enough.

exceptionTypeAndMsg

public static String exceptionTypeAndMsg(Exception e)

Displays both the exception class and the message. Use you wnat a relatively terse display of the exception (i.e. omitting stacktrace). Prefer to use this over exception.getMessage(), as some exceptions have null messages.