Package org.lsst.ccs.utilities.logging

This package provides proxies to the standard java.util.logging package.

See: Description

Class Summary

Class	Description
CCSLogManager	A dedicated LogManager class to control the resetting of the LogManager when a sigterm signal is received.
DailyRollingFileHandler	A Log File Handler that rolls every day.
JULAppender	simple bridge from Log4J to JUL.
Log4JConfiguration	Utility class to provide Log4j configuration.
Logger	Just a wrapper class around java.util.Logger to add specific logging methods.
LogPropertiesLoader	The role of this class is: to read the logging.properties and offer other codes (namely handlers) access to the properties described (a thing not permitted by the standard logManager) to be sure that the Handlers are lazily loaded (the standard LogManager may not be able to load the Handlers class due to ClassLoading problems) to delegate informations to the LogManager so it can behave properly (e.g.
StackTraceFormats	manages formatting of stackTrace.
TextFormatter	A simple text formatter.
UserConsoleFilter	Filter that discards logs which level smaller than Level.WARNING and coming from loggers other than "org.lsst.ccs.subsystem" or "org.lsst.ccs.driver".

Package org.lsst.ccs.utilities.logging Description

This package provides proxies to the standard java.util.logging package.
Its Logger class is only for codes that log messages or data (not for codes that deal with Level, Formatters or Handlers). It provides methods that can simply replace logging invocations meant to be handled by Log4J or simple standard java logging invocations: you can then in your codes just change the import directives and keep you code "as is".

So you have for instance :

     Logger logger = Logger.getLogger("org.lsst.ccs.mypackage") ;
     //....
     logger.info("doing the right thing!") ;
     //...
     if( logger.isInfoEnabled() ) {
         logger.log(Level.INFO, "still better", methodCall()) ;
     }
     //...
     try {
         //...
     } catch(Exception exc) {
         logger.error("Oops!", exc) ;
     }
 

But the Logger class is not only to get syntactic sugar: it provides access to "multi-dimensional logging".

What's that?

The idea is that can log the same call to different loggers in a single invocation. So, for instance, you have the usual logger linked to a package but you want also to address different "concerns" that are common to different classes or package. Then you can write:

     logger.log(Level.INFO, "Object being initialized", theObject, "INIT");
 

this means that the created LogRecord will be submitted to the current Logger and also to another one named "INIT".
Thus you can create many "transversal" loggers named "INIT", "CONFIG", "MOVE" (or whatever you want) and then you will be able to handle log informations reporting specifically about one of this "concerns".

     logger.log(Level.INFO, "Object being moved at initialization", theObject, "INIT", "MOVE");
 

Then you can set the level for the corresponding package to SEVERE and set the level of the "INIT" concern to INFO .
All the logging methods of the Logger class takes an optional String... variable argument list where you can name concerns.

Then you can handle real java.util.logging.Loggers that bear a name of package or a name of concern. Then you can use setLevel or addHandler methods to this actual loggers (of type java.util.logging.Logger). But you should note there are changes to the way Handlers should be defined and to the configuration file (if you want to pilot logging through a configuration file).

Handler design

Since the same LogRecord might be provided to different Loggers then a Handler may receive many publish requests for the same LogRecord! It means that the Handlers should memorize which records are published and not report twice the same record.

Configuration file

There is a logging.properties file to define the behaviour of loggers ans handlers: though this file is in the standard format of java.util.logging it is positioned in a different way:

• it is considered a better policy to put the file at a global level of the CLASSPATH. ("/logging.propertie" in resource handling syntax).
• to obtain this behaviour call Class.forName("org.lsst.ccs.utilities.logging.LogManagement early in your main (this will call static initialization code)