This article outlines the steps required to understand and implement logging of the XPages runtime environment on the Domino Server. We use the
Java Logging API to take a look under the hood of the XPages runtime running on the Domino Server JVM. The default logging information for applications running on the JVM is contained in the
logging.properties file located within the
Domino Install Dir\jvm\libdirectory. This file can be edited to allow for custom logging of the XPages runtime to aid debugging etc..
Creating Handlers for loggers:
The first step in the logging process is to create handlers for the loggers. These handlers filter and format the output of a logger and typically direct the output to the console (ConsoleHandler) or to a file (FileHandler). Handlers are intitialised by adding the following line to
logging.properties:
handlers=java.util.logging.ConsoleHandler,java.util.logging.FileHandler
Next, set up the location of the file-based loggers by including the following line with the placeholder set to your preferred log location (remember to use double backslashes on Windows machines, e.g.
C:\\Domino\\mylog.txt):
java.util.logging.FileHandler.pattern = YOUR_FILE_PATH
The output of any file-based loggers will be directed to your specified location, whereas the output of any console-based loggers will be contained in the
console.log file which can be found at
Domino Install Dir\data\IBM_TECHNICAL_SUPPORT\console.log. All information written out to System.out or System.err will also be sent to this file. Several other useful system log files can also be found in this directory.
Configuring Logging:
Once the location of the logs has been configured, the granularity level of the logging information can be adjusted. However, it is good practice to assign a default level to each type of handler. In the Java Logging API there are seven logging levels, ranging from the low priority, FINEST, to the highest priority, SEVERE (see link above for details). The loggers can also collect information for all levels by setting the level to ALL, or logging can be switched off by changing the level to OFF. For example, the default logging level for the console and file handlers is set up by the following two lines:
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.FileHandler.level = INFO
You can also control the output format, size, and filters applied by each handler by adjusting parameters outlined in the ConsoleHandler and FileHandler classes (refer to
FileHandler API). In this example setting the formatting to be “simple”, and the number of lines to print to be 5000:
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.limit = 5000
Registering Loggers:
Now that the handlers are initialised you can register which loggers will be handled and at which level logging information will be collected. This is similar to how the default level is set for the handlers, however, you must explicitly list on a separate line, each logger and the level required in the following format “com.abc.someLogger.level = SOME_LEVEL” (minus the quotes of course). For example, com.ibm.xsp.adapter.level = ALL
The loggers available for use in XPages environment are divided into hierarchical groups (which may change in future releases) with more general loggers encapsulating others. For example, the group com.ibm.xsp.adapter will contain all the logging information produced by loggers with that prefix, i.e.com.ibm.xsp.adapter.servlet. These are the available groups, with a brief comment included following the "
":
com.ibm.xsp.adapter
used to log when a service cannot be loaded
com.ibm.xsp.adapter.env
log the LCD environment service method
com.ibm.xsp.adapter.servlet used when a page is not found when processing a request
com.ibm.xsp.adapter.servlet.wrapper
extensive logging of the LCD servlet implementation i.e. request, response, session, config etc.
com.ibm.xsp.adapter.servlet.mime logs the method to get the MIME type
com.ibm.xsp.adapter.notescontext
logs startup and shutdown of the notes context
com.ibm.xsp.adapter.notesurl logs aspects of Notes (.nsf) URL creation, opening, closing etc.
com.ibm.xsp.adapter.module
checks for existence of and state of .nsf components
com.ibm.xsp.adapter.module.timeout checks for timed out modules
com.ibm.xsp.adapter.module.classloader
logs the classloading for modules
com.ibm.xso.core encapsulates the next two loggers
com.ibm.xsp.core.component
logs the creation of UI components and whether they have children/facets
com.ibm.xsp.core.page.compiled logs the issues in the XPage .class files generated in Domino Designer
com.ibm.xsp.theme
logs the loading of the UI theme
com.ibm.xsp.user.timezone logs the computation of the user time zone
com.ibm.common.standard
logs the management of extensions
com.ibm.xsp.domino logs the resetting of the domino rich text item
com.ibm.xsp.domino.view
logs domino view column values
com.ibm.xsp.extsn logs a multipart MIME item
com.ibm.xsp.extsn.component
General purpose logger that logs number converters, AJAX type-ahead, and some Dojo components converters
In addition to these a number of loggers specific to the XSP Command Manager may be configured:
com.ibm.domino.xsp.bridge.http.manager
Command manager logging
com.ibm.domino.xsp.bridge.http.config
Logging of config
com.ibm.domino.xsp.bridge.http.native Log communication between command manager and domino http server
com.ibm.domino.xsp.bridge.http.servlet
Extensive logging of the XSP HTTP servlet request handling