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 configuration update is activated in the supplied configuration:

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

• Here, the scan="true" instruction activates the update. 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 updated by logback itself.

• Therefore, the following PLANTA specific instruction must be included in the configuration file to be updated (as included in the supplied configuration file):

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

• When updating, you have to bare in mind that after the scanPeriod has expired the configuration update 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 the update.

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.

• The log files are rolled up daily and deleted after 14 days.

• 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. The file used for the configuration can be defined in the logback parameter.

Procedure

• Define the desired file in the logback field.

• After the logfile has been created, you can change the configuration again if necessary.

Special Name Spaces