com.sleepycat.je.utilint
Class LoggerUtils

java.lang.Object
  extended by 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 enviroment 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
(package private) static Map<Thread,EnvironmentImpl> envMap
           
static String FIXED_PREFIX
           
(package private) static Map<Thread,Formatter> formatterMap
           
static String NO_ENV
           
 
Constructor Summary
LoggerUtils()
           
 
Method Summary
static void envLogMsg(Level logLevel, EnvironmentImpl envImpl, String msg)
          Use the environment logger.
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 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 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

envMap

static Map<Thread,EnvironmentImpl> envMap

formatterMap

static Map<Thread,Formatter> formatterMap

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.


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)


Copyright (c) 2004-2012 Oracle. All rights reserved.