Logging ensures that problems and program errors are recorded for
later analysis. The logging mechanism must be configured properly to
record the information. For OpenNTF Domino API the configuration is
stored in the
IBM_TECHNICAL_SUPPORT\org.openntf.domino.logging.logconfig.properties
file in the Domino data directory. When this file does not exist, the ODA
uses default settings.
By default the log messages for the
org.openntf.domino
package with level WARNING and higher are:
IBM_TECHNICAL_SUPPORT
directory within the Domino data directory
Configuration for the logging mechanism is stored in the
IBM_TECHNICAL_SUPPORT\org.openntf.domino.logging.logconfig.properties
file in the Domino data directory. This file is checked for changes
every minute and dynamically reloaded when needed. The message
"Logging: Updated LogConfig from changed PropertyFile" is printed on
the server console when the configuration is successfully reloaded.
The configuration file consists of two parts. First part defines the Handlers, second part defines the Filter Handlers.
A Handler object takes log messages from a Logger and exports them. You may define arbitrary many handlers. These handlers must be listed on the "Handlers=<handler 1 name>, <handler 2 name>" line. Handler names are arbitrary. Each handler is configured by Handler. <handler name>-properties, where the following properties may/must be defined:
Class | Required | Handler's class name (subclass of java.util.logging.Handler ).
|
MinimalLevel | Optional | Minimal level (SEVERE, WARNING, FINE, ...) the handler may publish. |
Formatter | Optional | Class for the handler's Formatter; if none is specified, some default formatter is used. |
Props | Optional | Set of comma-separated properties for handler configuration. The properties are specific to the handler. |
A handler's class must implement some static methods which will be called via reflection:
{@link org.openntf.domino.logging.LogHandlerConfigIF} | configFromProps(String
props) [public static] |
The "Props" from above are examined, the resulting Object should contain a configuration set for the handler. In case of "wrong" props, an Exception should be thrown. |
<HandlerClass> | getInstance(LogHandlerConfigIF
config, boolean useDefaultFormatter) [public static] |
Parameter config contains the return
value from configFromProps method, useDefaultFormatter
is true if (and only if) no Formatter is configured.
|
Additionally, a handler may implement the {@link org.openntf.domino.logging.LogHandlerUpdateIF} interface to enable the handler to be dynamically attached to a new log configuration.
Handlers=HFile1, HConsole, HLogDB Handler.HFile1.Class=org.openntf.domino.logging.LogHandlerFile Handler.HFile1.Props= Limit=50000000, \ Count=10, \ Append=true, \ Pattern=<notesdata>/IBM_TECHNICAL_SUPPORT/org.openntf.log.%u.%g.txt Handler.HConsole.Class=org.openntf.domino.logging.LogHandlerConsole Handler.HConsole.MinimalLevel=WARNING Handler.HLogDB.Class=org.openntf.domino.logging.LogHandlerOpenLog Handler.HLogDB.MinimalLevel=INFO Handler.HLogDB.Props= LogDB=OpenLog.nsf
Handlers are attached to Loggers through FilterHandlers. Loggers are identified by name (usually a package or a class name) and specified using the LoggerPrefices property. FilterHandlers are identified by name, each can have the following properties:
LoggerPrefices | Required | Comma separated names of loggers to attached the specified handlers to |
DefaultLevel | Required | Messages of this level and above will be passed to the Handler. If the message level is the same or above of a MinimalLevel property specified for the handler, it will be processed. |
DefaultHandlers | Required | Comma separated list of handler names specified on the "Handlers=" line. Specified handlers will be attached to loggers identified by LoggerPrefices property. |
FilterHandlers=OpenNTF FilterHandler.OpenNTF.LoggerPrefices=org.openntf.domino FilterHandler.OpenNTF.DefaultLevel=WARNING FilterHandler.OpenNTF.DefaultHandlers=HFile1, HConsole, HLogDB
Optionally a FilterHandler can be accompanied by a Filter Config Entry. They further fine tune the behavior of the logging mechanism. Filter Config Entries can be used to change loggers based on a formula condition.
There can be any number of Filter Config Entries. They are supposed to be named FCE1, FCE2 and so on and are attached to a FilterHandler.
FCE<n> | Required | Logger name; must be a child of one of the FilterHandler's loggers |
FCE<n>.Level | Required | FINEST, FINER, FINE, CONFIG, INFO, WARNING, or SEVERE |
FCE<n>.Handlers | Required | One or more defined Handlers (not necessarily contained in DefaultHandlers) |
FCE<n>.FormulaCondition | Optional | Condition as a formula (in Formula
Language); the following variables may be used:
|
FCE<n>.ValidUntil | Optional | Expiration date in ISO format (yyyy-mm-dd), i.e. the whole FCE entry is ignored after this date. |
In this example the logging level for the "org.openntf.domino.impl.Document" logger will be changed to FINE and log records will be written to a file pointing to by the HFile1 handler from Monday through Friday:
FilterHandler.OpenNTF.FCE1=org.openntf.domino.impl.Document FilterHandler.OpenNTF.FCE1.Level=FINE FilterHandler.OpenNTF.FCE1.Handlers=HFile1 FilterHandler.OpenNTF.FCE1.FormulaCondition=@Weekday(@Today) = 2:3:4:5:6
Below is a complete example of the configuration file. It defines three handlers - HFile1 writes log records to a text file, HConsole handler writes to the server console and HLogDB to the OpenLog.nsf Notes database. A more detailed logging is turned on for an application with the path ending with hvm.nsf for the implementation of a Document class (via a Filter Config Entry).
Handlers=HFile1, HConsole, HLogDB Handler.HFile1.Class=org.openntf.domino.logging.LogHandlerFile Handler.HFile1.Props= Limit=50000000, \ Count=10, \ Append=true, \ Pattern=<notesdata>/IBM_TECHNICAL_SUPPORT/org.openntf.log.%u.%g.txt Handler.HConsole.Class=org.openntf.domino.logging.LogHandlerConsole Handler.HConsole.MinimalLevel=WARNING Handler.HLogDB.Class=org.openntf.domino.logging.LogHandlerOpenLog Handler.HLogDB.MinimalLevel=INFO Handler.HLogDB.Props= LogDB=OpenLog.nsf FilterHandlers=OpenNTF FilterHandler.OpenNTF.LoggerPrefices=org.openntf.domino FilterHandler.OpenNTF.DefaultLevel=WARNING FilterHandler.OpenNTF.DefaultHandlers=HFile1, HConsole, HLogDB FilterHandler.OpenNTF.FCE1=org.openntf.domino.impl.Document FilterHandler.OpenNTF.FCE1.Level=FINE FilterHandler.OpenNTF.FCE1.Handlers=HFile1 FilterHandler.OpenNTF.FCE1.FormulaCondition=@Ends($DBPATH$; "hvm.nsf")
You can configure OpenNTF Domino API logging for your own loggers. This way messages logged by your logger will be recorded using the same mechanisms as ODA uses.
A minimum configuration requires:
Using your own FilterHandler helps to distinguish your logging settings from the settings for the ODA.
Bellow is an example of this configuration which adds a new filter handler and specifies the required properties. Log messages will be recorded using the handler HFile1 defined in the Handlers part. You can also specify your own handler which writes messages to a separate file or a separate copy of OpenLog.nsf database. Check the MinimalLevel property of the handler - if this is specified then only messages of that level and above will be recorded no matter what DefaultLevel you specify for your FilterHandler.
FilterHandlers=OpenNTF,[your filter handler name] FilterHandler.[your filter handler name].LoggerPrefices=[hierarchical dot-separated name of your logger] FilterHandler.[your filter handler name].DefaultLevel=INFO FilterHandler.[your filter handler name].DefaultHandlers=HFile1
Created By :