org.lsst.ccs.utilities.logging (LSST Camera Control Software

Class Summary
Class	Description
ConsoleHandlerN	A Console handler that detects duplicate logs.
ContextLogManager	instance of this class should be built only during load time.
FileHandlerN
IsLoggableDelegate	A utility to plug into Handlers that want to detect duplicate logs.
JULAppender	simple bridge from Log4J to JUL.
Logger	Just a wrapper class around java.util.Logger to add specific logging methods.
LogManagement	Ths static initialization of this class should be fired early in an application by doing
SocketHandlerN	A `SocketHandler` that detects duplicate publications.Y
StackTraceFormats
StreamHandlerN	: A `StreamHandler` that detects duplicate publications.
TextFormatter

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 initialisation", 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.
Special handlers are provided to check for duplicates: ConsoleHandlerN, StreamHandlerN, SocketHandlerN, ... all rely on the service of a IsLoggableDelegate that checks the records for multiple publishing.

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)

Example of a logging.properties file:


 # Properties file which configures the operation of the CCS
 # logging facility.

 # Global logging properties.
 # ------------------------------------------
 # The set of handlers to be loaded upon startup.
 # Comma-separated list of class names.
 # (? LogManager docs say no comma here, but JDK example has comma.)
 # do not put space characters in this list!
 # handlers are loaded by the primordial log manager

 handlers=
 ## use HandlersN to avoid classLoading problems
 ## these are loaded by the ClassLoader that knows about thoses classes
 handlersN=org.lsst.ccs.utilities.logging.ConsoleHandlerN,org.lsst.ccs.utilities.logging.FileHandlerN

 ## BEWARE: you CAN'T set  org.lsst.ccs.bus.utils.LogBusHandler HERE!
 ## because it is initialized later (when the buses are activated)

 # Default global logging level.
 # Loggers and Handlers may override this level
 # SEE LSSTCCS-290
 .level=WARNING

 #The level of the CCS Root logger LSSTCCS-297
 org.lsst.ccs.level=INFO
 # Loggers
 # ------------------------------------------
 # Loggers are usually attached to packages.
 # Here, the level for each package is specified.
 # The global level is used by default, so levels
 # specified here simply act as an override.
 #myapp.ui.level=ALL
 #myapp.business.level=CONFIG
 #myapp.data.level=SEVERE


 # Handlers
 # -----------------------------------------

 # --- ConsoleHandler ---
 # Override of global logging level
 #java.util.logging.ConsoleHandler.level=SEVERE

 org.lsst.ccs.utilities.logging.ConsoleHandlerN.level=INFO

 ## now you can set the level of the LogBusHandler here
 org.lsst.ccs.bus.utils.LogBusHandler.level=WARNING

 # --- FileHandler ---
 # Override of global logging level

 org.lsst.ccs.utilities.logging.FileHandlerN.level=ALL

 # Naming style for the output file:
 # (The output file is placed in the directory
 # defined by the "user.home" System property.)
 # use %t if temporary directory to be used (instead of %h)
 # see below other CCS options
 # org.lsst.ccs.utilities.logging.FileHandlerN.pattern=%h/ccs/ccs-logs-%u.log

 #org.lsst.ccs.utilities.logging.FileHandlerN.pattern=%t/ccs-logs-%u.log

 # the case where we use our own log property from Property "org.lsst.ccs.logdir"

 org.lsst.ccs.utilities.logging.FileHandlerN.pattern=%L/ccs-logs-%A.log

 # the case where we use our own log property from Property "org.lsst.ccs.workdir"

 #org.lsst.ccs.utilities.logging.FileHandlerN.pattern=%W/logs/ccs-logs-%u.log

 # Limiting size of output file in bytes:
 org.lsst.ccs.utilities.logging.FileHandlerN.limit=5000000

 # Number of output files to cycle through, by appending an
 # integer to the base file name:
 org.lsst.ccs.utilities.logging.FileHandlerN.count=20

 # Style of output (Simple or XML):
 org.lsst.ccs.utilities.logging.FileHandlerN.formatter=java.util.logging.SimpleFormatter
 # a special formatter that deals with StackTraces
 org.lsst.ccs.bus.utils.LogBusHandler.formatter=org.lsst.ccs.utilities.logging.TextFormatter
 org.lsst.ccs.utilities.logging.ConsoleHandlerN.formatter=org.lsst.ccs.utilities.logging.TextFormatter
 # change that one if you want to modify the way StackTraces are printed
 # negative value means all the stacktrace will be printed
 StackTraceFormats.depth=2
 #org.lsst.ccs.utilities.logging.FileHandlerN.formatter=java.util.logging.XMLFormatter

 # Example to customize the SimpleFormatter output format
 # to print one-line log message like this:
 #     level: log message [date/time]
 #
 java.util.logging.SimpleFormatter.format=%4$s: %5$s [%1$tc]%n
 # index starts at 1 : date, source, Logger, Level, message, throwableStr
 # here we have source :log_message throwable
 org.lsst.ccs.utilities.logging.TextFormatter.format=%4$s: %5$s[%2$s]%n%6$s