XPages: How to log the XPages server runtime environment?

Introduction:
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 

No Comments Found