Search



XPages: How to log the XPages server runtime environment?

Skip to article content
Article information
  • Edit
  •  XPages 
    logging , handler
    William Doran
    10/09/2008
    William Doran
    10/10/2008
      Written by IBM



    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

    Comments

    No Comments Found