This article outlines the steps required to understand and implement logging of the XPages runtime environment on the Domino Server. The instructions for enabling logging are simpler in Domino 8.5.2 and later releases.
Logging in 8.5.2 and more recent releases.
The newer logging behavior, from Domino 8.5.2, is that logging to a file is enabled by default.
The Java log files are:
The currently running HTTP task saves logged entries in error-log-0.xml and trace-log-0.xml. When you restart the HTTP task, those files are renamed to have the -1 suffix, and new -0 files are created. The numbered files are created and renamed each time you restart the server, up to a limit of 10 files. After the limit of 10 files, older files are deleted. So files with the -9 suffix will be deleted when the HTTP task is restarted.
The trace log file contains everything that was logged, including the message and the stack trace of any logged exceptions. The error log only contains entries with severity values SEVERE, WARNING and INFO, and does not contain the stack trace for any exceptions. It never contains the lower-severity entries, even when their level is configured to be logged, so you have to check the trace logs when dealing with low-severity entries.
The file where you configure the logging levels has also changed in 8.5.2. The levels are now configured in:
As before, the configured logging levels will control which severity of messages will actually appear in the log files, for each individual logger that handles a group of related loggable entries.
That file contains a list of loggers, where you can remove the # to enable each:
#To enable logging groups, uncomment and modify the commented line appropriately
The full list is below.
In releases 8.5.2 and 8.5.3, the log file entries would appear on the Domino server console by default. However many of the issues logged were not relevant to the day-to-day work of administrators, so from 9.0, the logging does not appear on the console by default; only in the log files. You can enable the log entries to appear in the Domino server console in 9.0 by adding the option:
to the file:
and restarting the HTTP task.
The entries that appear on the console are also logged in the application:
C:\Domino\data\log.nsf (Server Log)
Since the logging messages do not appear in the console by default, they will usually not be present in that NSF, except where the notes.ini setting has been enabled.
Older instructions for logging in 8.5.1 and 8.5
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\lib
directory. 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
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.
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 (in order the levels are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST). 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. 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
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.
The XPages logger groups
These are the available groups, with a brief comment included:
# used to log when a service cannot be loaded
# log the LCD environment service method
# used when a page is not found when processing a request
# extensive logging of the LCD servlet implementation
# i.e. request, response, session, config etc.
# logs the method to get the MIME type
# logs startup and shutdown of the notes context
# logs aspects of Notes (.nsf) URL creation, opening, closing etc.
# checks for existence of and state of .nsf components
# checks for timed out modules
# logs the classloading for modules
# encapsulates the next two loggers
# logs the creation of UI components and whether they have children/facets
# logs the issues in the XPage .class files generated in Domino Designer
# logs the loading of the UI theme
# the computation of the user time zone
# logs the management of extensions
# logs the resetting of the domino rich text item
# logs domino view column values
# logs a multipart MIME item
# General purpose logger that logs number converters, AJAX type-ahead,
# and some Dojo components converters
In addition to those a number of loggers specific to the XSP Command Manager may be configured:
# Command manager logging
# Logging of config
# Log communication between command manager and domino http server
# Extensive logging of the XSP HTTP servlet request handling