Die Dokumentation ab Version 39.5.17 von PLANTA project finden Sie in der neuen PLANTA Online-Hilfe.
TWiki> Current Web>TechnischeDokumentation>SpezielleFunktionen>LoggingDocumentation

Logging-System des PLANTA-Servers Neu ab S 39.5.5

Basis des Logging-Systems

Informationen
  • Ziel der Entwicklung des hier beschriebenen Logging-Systems war die Vereinheitlichung der unterschiedlichen Mechanismen, die zur Sammlung von Meldungen dienten.
  • Hierbei stand die hohe Anpassbarkeit und Zukunftssicherheit im Fokus.
  • Aufgrund der seit Server 39.5 bestehenden Java-Basis lag die Auswahl eines der zahlreichen in der Java-Welt vorhandenen Logging-Systeme nahe.
  • Die Logging-Fassade SLF4J gepaart mit deren nativer Implementierung Logback zählt unter diesen Systemen zu den fortgeschrittensten.

SLF4J/Logback

  • Wie bei Logging-Systemen üblich wird ein Logger mit einem Namen versehen (meist der voll qualifizierte Klassenname).
  • Log-Nachrichten werden vom Entwickler zusammen mit dem Log-Level, einer Einschätzung der Wichtigkeit der Meldung, diesem Logger übergeben.
  • Log-Levels in SLF4J sind error > warn > info > debug > trace, wobei die Sortierung hier die Wichtigkeit der Nachricht wiederspiegelt.
  • SLF4J ist eine Logging-Fassade; so können zur Kompilierzeit verschiedene Logging-Systeme eingebunden werden (nähere Informationen hierzu finden Sie auf slf4j.org).
  • Eine von den Log-Nachrichten (und vom Quelltext) unabhängige Konfiguration erlaubt die Filterung von Nachrichten und formatierte Ausgabe, die üblicherweise in Dateien erfolgt.
  • SLF4J im Zusammenspiel mit dessen nativer Implementierung Logback bietet besondere Konzepte, die auch im PLANTA-Server Verwendung finden:
    • Mapped Diagnostic Context (MDC): Hier können im Thread-Kontext Schlüsselwert-Paare hinzugefügt werden, mit deren Hilfe Nachrichten dieses Kontextes gesondert behandelt werden können.
    • Marker: Nachrichten können hierdurch "eingefärbt" werden; auch dies erlaubt eine weitreichendere Filterung (z.B. thematische Aufspaltung von Log-Dateien).
  • Die Konfigurationsmöglichkeiten von Logback sind sehr reichhaltig, weshalb Details auf der entsprechenden Dokumentationsseite nachzuschlagen sind.

Hinweis

  • Die bisherigen Logging-Systeme (Eigenentwicklung und Log4j) werden durch das beschriebene Logging-System abgelöst.

PLANTA-spezifische Dokumentation

Nachrichtenidentifikatoren

Details
  • Log-Nachrichten, die ein Log-Level von error, warn oder info besitzen, erhalten einen Nachrichtenidentifikator.
  • Dieser wird in dem Nachrichtentext in Form einer Nummer angegeben.
  • Über diesen Identifikator kann die Beschreibung der Nachricht und, sollte es sich um einen Fehler handeln, Behebungsmaßnahmen eingesehen werden.
  • Ein Verzeichnis aller mit Identifikatoren versehenen Nachrichten ist hier zu finden.

Thematische Einordnung von Nachrichten über Marker

Details
  • In PLANTA-Server dient das Marker-Konzept zur thematischen Einordnung einer Nachricht.
  • Dies erlaubt beispielsweise, einem Benutzer mit fachlichem Hintergrund für ihn wichtige Nachrichten auszugeben, ohne dass administrative Benutzer von für sie unwichtigen Informationen überflutet werden.
  • So können für jeden thematischen Komplex Log-Dateien konfiguriert werden, in die die entsprechenden Nachrichten einsortiert werden, wobei auch Überschneidungen berücksichtigt werden können.
  • In PLANTA-Server werden nur die mit Identifikator versehenen Log-Nachrichten entsprechend markiert; das Nachrichtenverzeichnis gibt die Zuordnungen an.

Aktualisierung der Konfiguration im laufenden Betrieb

Information
  • Die mitgelieferte Konfiguration befindet sich im Installationsverzeichnis unter conf/logback.xml.
Details
  • Logback ermöglicht Konfigurationsänderungen im laufenden Betrieb, sowohl über die Logback-API als auch über die Konfigurationsdatei.
  • Der folgende Ausschnitt zeigt, wie in der mitgelieferten Konfiguration die automatische Aktualisierung der Konfiguration eingeschaltet wird: 
<configuration scan="true" scanPeriod="1 minute">
[...]
</configuration>
  • Die Anweisung scan="true" aktiviert hier die Aktualisierung, über scanPeriod="1 minute" prüft Logback die Konfigurationsdatei jede Minute auf Änderungen.
  • Das in PLANTA-Server implementierte Logging-System umfasst auch native Teile, die von Logback selbst nicht entsprechend aktualisiert werden können.
  • Daher muss die folgende PLANTA-spezifische Anweisung in der zu aktualisierenden Konfigurationsdatei vorhanden sein (wie in der mitgelieferten Konfiguration enthalten): 
<!-- NativeLevelChangePropagator enables live configuration updates -->
<contextListener class="de.planta.server.logging.NativeLevelChangePropagator"/>
  • Zu beachten ist bei der Aktualisierung, dass auch nach Ablauf der konfigurierten scanPeriod die Konfigurationsaktualisierung nicht zwingend sofort durchgeführt wird.
  • Dem liegt zugrunde, dass Logback aus Performance-Gründen die Prüfung nur beim Auftreten jeder 16. Log-Nachricht durchführt.
  • Somit ist es u.U. erforderlich, eine Aktion zu starten (z.B. eine Client-Verbindung herzustellen), um die Aktualisierung zu starten.

Log-Dateien

Details

Ab S 39.5.8

  • Über die mitgelieferte Konfiguration werden alle Log-Dateien im Verzeichnis log/ des Arbeitsverzeichnisses von PLANTA-Server angelegt.
  • Für den Betrieb relevante Log-Nachrichten werden hier in der Datei PlantaServer.log ausgegeben.
  • Über eine größenbasierte Rotation (mit Schwellwert von 5 MB) wird eine Historie von maximal 10 komprimierten Dateien angelegt, die nach dem Schema PlantaServer.[NUMMER].log.zip benannt sind.
  • Ist ein session-basiertes Logging aktiv (die Vorgehensweise hierzu siehe das nächste Kapitel), so wird für jede Session eine Datei PlantaSession-[SessionID].log erstellt, in die zur Session gehörige Nachrichten ausgegeben werden.
  • NEU Session-Logfiles sind defaultmäßig mit Rotation eingerichtet.

Bis S 39.5.8

  • Über die mitgelieferte Konfiguration werden alle Log-Dateien im Verzeichnis log/ des Arbeitsverzeichnisses von PLANTA-Server angelegt.
  • Für den Betrieb relevante Log-Nachrichten werden hier in der Datei PlantaServer.log ausgegeben.
  • Über eine größenbasierte Rotation (mit Schwellwert von 5 MB) wird eine Historie von maximal 10 komprimierten Dateien angelegt, die nach dem Schema PlantaServer.[NUMMER].log.zip benannt sind.
  • Ist ein session-basiertes Logging aktiv (die Vorgehensweise hierzu siehe das nächste Kapitel), so wird für jede Session eine Datei PlantaSession-[SessionID].log erstellt, in die zur Session gehörige Nachrichten ausgegeben werden
  • Die Session-Logfiles sind ohne Rotation eingerichtet.

    • Session-basiertes Logging für Fehleranalysen

    Ab S 39.5.9

    Information NEU
    • Um die Erstellung eines session-basierten Logfiles für die Fehleranalyse zu aktivieren, ist es nicht mehr notwendig, die Anpassungen in der logback.xml -Datei vorzunehmen. PLANTA stellt eine zweite Datei logback_debug.xml zur Verfügung, die bereits alle notwendigen Einstellungen beinhaltet. Die beiden Dateien müssen lediglich nur umbenannt werden, damit das Logging aktiviert wird und die Umbenennung wieder rückgängig gemacht werden, wenn das Logging ausgeschaltet werden soll.

    Vorgehensweise NEU

    • Die Datei logback.xml beliebig umbenennen.
    • Die Datei logback_debug.xml in logback.xml umbenennen.
    • Nachdem das Logfile erstellt wurde, die Umbenennungen der Dateien rückgängig machen.

    Bis S 39.5.9

    Information
    • Um die Erstellung eines session-basierten Logfiles für die Fehleranalyse zu aktivieren, müssen bestimmte Anpassungen in der Konfigurationsdatei logback.xml vorgenommen werden. Vorgehensweise
    • Um den Grad der Ausführlichkeit für die Fehleranalyse zu erhöhen, muss zunächst das Log-Level für den PLANTA Namespace "de.planta.server" angepasst werden: 
    [...]
<!-- enable this for tracing/debugging logs in the PLANTA namespace -->
<logger name="de.planta.server" level="debug"/>
[...]
    • Weiterhin muss das session-basierte Logging eingeschaltet werden. Hierzu ist der folgende Block in der mitgelieferten Konfiguration einzukommentieren: 
    [...]
<!-- enable the following to enable session logs; don't forget to
uncommment 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>
[...]
    • Der Appender "SESSIONLOG" muss nun auch referenziert werden: 
    [...]
<!-- enable logging for messages with level <= info -->
<root level="info">
<appender-ref ref="CONSOLE" />
<appender-ref ref="SERVERLOG" />
<appender-ref ref="SESSIONLOG" />
</root>

</configuration>

    Hinweis

    • Das Log für betriebsrelevante Nachrichten verändert sich durch diese Einstellung nicht.

    Spezielle Namensräume

    Namensraum Beschreibung
    de.planta.server Der Namensraum des PLANTA-Servers
    de.planta.server.native Log-Nachrichten aus den nativen Programmteilen werden innerhalb dieses Namensraumes ausgegeben
    de.planta.server.python Aus dem Python-Kontext über die Schnittstelle gesendete Nachrichten werden innerhalb dieses Namensraumes ausgegeben

             PLANTA project







     
    • Suche in Topic-Namen

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