Logging System of the PLANTA Server

Base of the Logging System

Information

• The objective of the development of the logging system described here was the standardization of different mechanisms for message collection.
• Here, the focus was placed on high adaptability and future security.
• Due to the Java base which exists from Server 39.5 on, opting for one of the logging systems within the Java world was only logical.
• The SLF4J logging facade paired with its native logback implementation is considered to be the most progressive among such systems.

SLF4J/Logback

• As is common for logging systems, a logger is given a name (usually the fully qualified class name).
• Log messages including the log level (an estimation of the importance of the message) are handed over to the logger.
• Log levels in !SLF4J are error > warn > info > debug > trace, whereas the sorting reflects the importance of the message here.
• SLF4J is a logging facade, i.e., different logging systems can be integrated at compile time (for further information on this topic, see slf4j.org).
• A configuration independent of the log messages (and of the source text) enables filtering and formatted output in the form of files.
• SLF4J in combination with its native logback implementation offers special concepts which are also used in PLANTA Server:
  • Mapped Diagnostic Context (MDC): Here, key value pairs with the help of which messages with this context can be treated individually can be added in the thread context.
  • Marker: This way, messages can be "colored"; this also allows extensive filtering (e.g. thematic splitting of log files).
• The configuration options of logbacks are quite complex. For details, see the corresponding documentation page.

Note

• Previous logging systems (in-house development and Log4j) are replaced by the described logging system.

PLANTA Specific Documentation

Message Identifiers

Details

• Log messages that possess an error, warn, or info log level, receive a message identifier.
• It is specified in the message text in the form of a number.
• Via this identifier, the description of the message can be viewed, and, if it is an error message, corrective measures can be viewed.
• A directory of all messages with identifiers can be found here.

Thematic Classification of Messages on Markers

Details

• In PLANTA Server, the marker concept serves to thematically classify a message.
• This allows a user with technical background, to have, e.g., messages displayed that are relevant for him without having administrative users flooded with information which is irrelevant for them.
• Hence, for each thematic complex, log files can be configured, into which the corresponding messages are sorted. Overlappings can be considered as well.
• In PLANTA Server, only log messages that possess an indicator are marked appropriately; the message directory specifies assignments.

Refresh the Configuration During Ongoing Operation

Information

• The configuration supplied can be found at conf/logback.xml.

Details

• Logback enables configuration changes via both the logback API as well as the configuration file during ongoing operation.
• The following excerpt shows how automatic refreshing is activated in the supplied configuration:

<configuration scan="true" scanPeriod="1 minute">
[...]
</configuration>

• Here, the scan="true" instruction activates refreshing. Via scanPeriod="1 minute", logback checks the configuration file for changes every minute.
• The logging system implemented in PLANTA Server also includes native parts which cannot be refreshed by logback itself.
• Therefore, the following PLANTA specific instruction must be included in the configuration file to be refreshed (as included in the supplied configuration file):

<contextListener class="de.planta.server.logging.NativeLevelChangePropagator"/>

• When refreshing, you have to bare in mind that after the scanPeriod has expired, the configuration refreshing is not necessarily continued.
• The reason for this is that for performance reasons logback carries out the check for every 16th occurring message only.
• Hence, it may be necessary to start an action (e.g. establishing a client connection) in order to start refreshing.

Log Files

Details

• Via the supplied configuration, all log files are created in the log/ directory of the PLANTA Server work directory.
• Log messages relevant for operation are displayed in the PLANTAServer.log file.
• Via a size-based rotation (threshold value of 5MB), a history of up to a maximum of 10 compressed files, which are named according to the PLANTAServer.[NUMMER].log.zip schema, is created.
• If session based logging is active (for the procedure, see the next chapter), a PLANTASession-[SessionID].log file is created for each session, in which messages belonging to the session are displayed.
• Session logfiles are setup with rotation by default.

Session-Based Logging for Error Analyses

Information

• In order to activate the creation of a session based logfile for error analysis, it is no longer necessary to make the adjustments in the logback.xml file. PLANTA provides a second logback_debug.xml file, which already contains all necessary settings. In order for the logging to be activated, you simply have to rename both files. In order to deactivate the logging again, you only have to undo the renaming.

Procedure

• Rename the logback.xml file arbitrarily.
• Rename the logback_debug.xml file to logback.xml.
• After the logfile has been created, undo the renaming of the files.

Special Name Spaces