The documentation from version 39.5.17 of PLANTA project can be found in the new PLANTA Online Help.
TWiki> CurrentEN Web>TechnicalDocumentation>SpecialFunctions>LoggingDocumentation

Logging System of the PLANTA Server New from S 39.5.5

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 every 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 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): 
<!-- NativeLevelChangePropagator enables live configuration updates -->
<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

From S 39.5.8

  • 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 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.[NUMBER].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.
  • NEW Session logfiles are setup with rotation by default.

Up to S 39.5.8

  • 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 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.[NUMBER].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.
  • The session logfiles are constructed without rotation.

    • Session Based Logging for Error Analysis

    From S 39.5.9

    Information NEW
    • 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 NEW

    • 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.

    Up to S 39.5.9

    Information
    • In order to activate the setting of a session-based logfile for error analysis, certain adjustments in the logback.xml configuration file must be made. Procedure
    • In order to enhance the degree of detail for the error analysis, you have to adjust the log level for the "de.planta.server" PLANTA name space first. 
    [...]
<!-- enable this for tracing/debugging logs in the PLANTA namespace -->
<logger name="de.planta.server" level="debug"/>
[...]
    • Furthermore, session-based logging must be activated. To do so, the following block is to be uncommented in the supplied configuration. 
    [...]
<!-- enable the following to enable session logs; don't forget to
uncomment the appender-ref to SESSIONLOG additionally
-->
<appender name="SESSIONLOG" class="ch.qos.logback.classic.sift.SiftingAppender">
<discriminator>
<key>sessionId</key>
<defaultValue>global</defaultValue>
</discriminator>
<sift>
<appender name="FILE-${sessionId}" class="ch.qos.logback.core.FileAppender">
<file>log/PlantaSession-${sessionId}.log</file>
<append>false</append>
<encoder>
<pattern>%d{HH:mm:ss.SSS} %level %marker %logger{35} - %msg%n</pattern>
</encoder>
</appender>
</sift>
</appender>
[...]
    • The "SESSIONLOG" appender must be referenced now: 
    [...]
<!-- enable logging for messages with level <= info -->
<root level="info">
<appender-ref ref="CONSOLE" />
<appender-ref ref="SERVERLOG" />
<appender-ref ref="SESSIONLOG" />
</root>

</configuration>

    Note

    • The log for company relevant messages is not changed by these settings.

    Special Name Spaces

    Name space Description
    de.planta.server Name space of the PLANTA server
    de.planta.server.native Log messages from the native program parts are displayed within this name space
    de.planta.server.python Messages sent from the Python context via the interface are displayed within this name space

             PLANTA project







     
    • Suche in Topic-Namen

    • Suche in Topic-Inhalten
    This site is powered by the TWiki collaboration platform Powered by Perl