MicroStrategy ONE
Logging Architecture and Components
The logging infrastructure used in MicroStrategy Web products is based on the logging framework introduced in the Java 2 Platform, Standard Edition (J2SE) 1.4. For detailed information on any of the terms discussed below, refer to the J2SE documentation at http://java.sun.com.
You can configure the location where error messages should be logged, the level of detail that should be logged (errors or warnings) as well as the format in which the messages should be logged.
Before beginning a discussion on the logging architecture in MicroStrategy Web products, here are some important terms to understand.
A logger object is used for logging informative or error messages from classes within a given package. The message is encapsulated in a log record and forwarded to handlers associated with this logger. In addition to the message, a log record contains information about the logging level, type of message, and the exception thrown, if any. For additional information on a logger, click here.
Every logger object is associated with a set of log handlers. A handler provides you the ability to send the log record to destinations such as a file, system console or a debugging monitor. Each handler is must be associated with a formatter, and optionally a filter. For additional information on a handler, click here.
A formatter object converts a log record into a string of desired format such as XML. For additional information on a formatter, click here.
A filter object applies custom filtering criteria to select the messages to log. For additional information on a filter, click here.
The value of the logging level indicates the importance of a log message, which ranges from FINEST to SEVERE:
-
OFF
-
SEVERE (highest)
-
WARNING
-
INFO
-
CONFIG
-
FINE
-
FINER
-
FINEST (lowest)
-
ALL
Enabling logging at a certain level enables logging for that level and all levels higher. For example, if you enable a logger at logging level INFO, all log messages at levels higher (SEVERE and WARNING) get logged along with log messages at level INFO. The logging levels OFF and ALL are used by loggers, handlers, and filters to disable or permit all logging respectively.
For additional information on logging level, click here.
This is the properties file used for setting up the logging infrastructure. By default, this file is created in WEB-INF/xml when the application is initialized. It logs all SEVERE errors to a text file in WEB-INF/log. For additional information on the logger.properties file, click here.
In MicroStrategy Web 7.5.x, the logger.properties file was created in WEB-INF/log, rather than in WEB-INF/xml.
Logging Architecture
Now that you are familiar with a logger, handler, formatter, filter, logging level and the logger.properties file, let’s see how these components fit into the Logging Architecture.
As explained previously, every logger is associated with handler. A logger can have zero or more handlers with each handler having its own formatter and filter (optional).
If a logger does not declared any handlers, it is recommended the logger level be set to OFF or SEVERE.
There are two kinds of loggers—a root logger and a package-level logger. A root logger exists at the highest level. This root logger is globally defined for the entire MicroStrategy Web application and logs SEVERE messages by default. The root logger receives all messages from package-level loggers. Package-level loggers are loggers that catch messages for all classes within that package. It is important to note that irrespective of the logging level of the log record or the package-level logger, all log records are forwarded to the root logger.
The package-level logger then checks the logging level on the log record to determine if the log record needs to be sent to the handlers. Each log record passing through the package-level logger must have a logging level higher than the logging level of the package-level logger or the handler, otherwise it does not get forwarded by the package-level logger to its handler. It is important to note that both, the logger and handler have a logging level. Typically, the logging level of the handler should be the same as that of the logger.
The following diagram summarizes how loggers and handlers work with respect to logging levels and filters.
The following diagram highlights the role of package-level loggers and handlers using actual packages within the MicroStrategy Web products. The description follows the diagram.
All log records received by the package-level logger for com.microstrategy.web.objects are forwarded to the root logger. However, before forwarding the log record to its own handlers, the package-level logger checks the logging level for the log record. The logging level for the log record for com.microstrategy.web.objects is SEVERE. Since the logging level on the package-level logger is FINE, it sends the log record to handlers, h3 and h4. Handlers h3 and h4 have logging levels of FINE; thus they accepts the log record and log them to the destination specified.
The package-level logger for com.microstrategy.web.beans also forwards all log records to the root logger. However, before forwarding the log record to its own handlers, the package-level logger checks the logging level for the log record. The logging level for the log record for com.microstrategy.web.beans is WARNING. Since the logging level on the package-level logger is WARNING as well, it sends the log record to handlers, h3 and h4. Handler h3 has logging level of FINE; thus it accepts the log record and logs it to a file. However, the logging level of handler h4 has logging level of SEVERE; thus it discards the log record and does not log anything to the debugging monitor. If there are any filters defined for the handlers, the filtering criterion determines what gets logged. Note that if the logging level for the log record for com.microstrategy.web.beans is INFO (that is, any logging level lower than WARNING), the log record is discarded and not forwarded to the handlers.