XPages: How to log the XPages server runtime environment? 

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.wrapperextensive 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.classloaderlogs the classloading for modules

com.ibm.xso.core encapsulates the next two loggers
com.ibm.xsp.core.componentlogs 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.standardlogs the management of extensions

com.ibm.xsp.domino logs the resetting of the domino rich text item
com.ibm.xsp.domino.viewlogs 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