Protokollierung (Logging)

Ab Version 3.28-02 nutzt Structorizer den standardmäßigen Java.util.logging-Mechanismus, um interne Statusinformationen, Fehlermeldungen, Warnungen und weitere Diagnosehilfen auf konfigurierbare Weise bereitzustellen. Diese Seite bezieht sich nur auf diesen allgemeinen Protokollierungsmechanismus für Structorizer. Beachten Sie, dass einige Funktionen (z. B. der Quellcode-Import) zusätzliche Protokollierungsmechanismen bereitstellen, die unabhängig konfiguriert werden (siehe z. B. Import Options (Importoptionen)).

Speicherort der Protokolldateien

Der Standardspeicherort der Protokolldateien ist der Unterordner .structorizer im Heimverzeichnis des Benutzers. Im Zweifelsfall finden Sie die tatsächlichen Pfade wichtiger Ordner oder Dateien auf der Registerkarte „Paths" (Pfade) des „About"-Dialogs (zu öffnen über das Menü „Help" (Hilfe) oder die Tastenkombination Ctrl+F1), um Ihnen wildes Raten zu ersparen (ab Version 3.28-10):

Die Protokolldateien entsprechen standardmäßig dem Namensmuster structorizer*.log. Das genaue Benennungsschema wurde jedoch mit Release 3.30 geändert (wobei es erst ab Version 3.30-08 wirksam wurde):

Vor Release 3.30 lautete der standardmäßige Protokolldateiname structorizer0.log. Bei mehreren gleichzeitig laufenden Structorizer-Instanzen wurden steigende „eindeutige" Nummern verwendet (structorizer1.log, structorizer2.log usw.), damit diese ihre Inhalte nicht vermischten. Es gab keine Sicherungskopien, und Protokolleinträge waren möglicherweise erst nach dem Schließen von Structorizer sichtbar. Beim Neustart von Structorizer wurde die vorherige Protokolldatei sofort überschrieben.
Ab Release 3.30 (tatsächlich ab Version 3.30-08) werden die Protokolldateien mit zwei Nummern benannt: der „eindeutigen" Nummer (wie oben beschrieben) und einem „Generations"-Zähler als zweiter Zahl. Die erste Protokolldatei heißt structorizer0.0.log. Bei gleichzeitigen Structorizer-Sitzungen verwenden diese unterschiedliche erste Nummern (structorizer0.*.log, structorizer1.*.log usw.). Beim Start von Structorizer wird nach der niedrigsten nicht gesperrten eindeutigen (ersten) Zahl gesucht; alle vorhandenen Protokolldateien mit dieser ersten Zahl werden dann durch Inkrementierung der zweiten Zahl umbenannt (z. B. wird structorizer0.0.log zu structorizer0.1.log usw.), bevor die neue Protokolldatei mit der Generationsnummer 0 erstellt wird. Je größer die zweite Zahl, desto älter die Protokolldatei. Der offensichtliche Vorteil der Dateiversionierung besteht darin, dass ein Neustart von Structorizer das vorherige Protokoll nicht zerstört.

Eine leere Datei mit der zusätzlichen Erweiterung .lck (z. B. structorizer1.0.log.lck) signalisiert, dass eine Structorizer-Instanz in die entsprechende Protokolldatei schreibt und ein Handle darauf hält. Dies hindert andere Structorizer-Instanzen daran, sie parallel zu öffnen und ihre Protokolldaten einzumischen. Stattdessen würden diese eigene Protokolldateien mit höherer (erster) Nummer verwenden oder erstellen (z. B. structorizer2.0.log).

Beim Start von Structorizer werden die Protokollierungsparameter aus einer Datei logging.properties gelesen (siehe Abschnitt unten), die im oben besprochenen Protokollordner abgelegt werden soll. Zu den Parametern gehören:

der Zielordner für die Protokolldateien (der oben besprochene Unterordner des Heimverzeichnisses),
das Dateibenennungsmuster der Protokolldateien (mit Platzhaltern %h, %u, %g für das Heimverzeichnis, die eindeutige Zahl und die Generationsnummer),
die Struktur der Protokolleinträge (standardmäßig ein XML-Schema) und
der minimale Protokolllevel, für den Benachrichtigungen protokolliert werden dürfen (standardmäßig: CONFIG).

Wenn Sie Structorizer-Versionen < 3.30 verwendet haben, müssen Sie die Datei logging.properties aus dem Ordner .structorizer entfernen, um die neue Konfiguration zu erhalten (wenn eine Konfigurationsdatei gefunden wird, bleibt sie erhalten, da sie möglicherweise eine benutzerspezifische Konfiguration enthält). Alternativ können Sie die vorhandene Konfigurationsdatei manuell bearbeiten (siehe unten). Dasselbe gilt für Version 3.30-08, die das Benennungsschema korrigiert. (Wenn Ihre Protokolldateien den Namen structorizer0.log.0 haben, haben Sie bei der Installation eine fehlerhafte logging.properties-Datei erhalten, was jedoch nicht kritisch ist.)

Hinweis: Es mag so erscheinen, als würden die Protokollinformationen mit einer gewissen Verzögerung in die Protokolldatei geschrieben; die Dateigröße wird in Ihrem Dateimanager möglicherweise als 0 angezeigt, selbst nach einem gemeldeten Fehler. Lassen Sie sich jedoch nicht täuschen. Öffnen Sie die Protokolldatei einfach mit einem Textbetrachter oder -editor — Sie werden sehen, dass sie tatsächlich Protokolleinträge enthält, die Sie kopieren können.

Wenn Sie Structorizer nach einem Fehlverhalten neu gestartet haben, das Sie analysieren lassen möchten, gehen die Informationen nicht sofort verloren: Wenn die Protokollierungskonfiguration aktuell ist, werden die Protokolle der letzten fünf Sitzungen noch gespeichert (ihre zweite Zahl wird jedes Mal inkrementiert, wenn Sie Structorizer schließen und wieder starten, wie oben erläutert).

Unter Linux und OS X ist der Protokollordner in der Regel ausgeblendet (aufgrund des Benennungsschemas). Sie müssen ihn daher möglicherweise sichtbar machen, um ihn einsehen zu können, z. B. unter Mac OS X durch Drücken der Tastenkombination Shift+Cmd+H im Finder, um das Heimverzeichnis anzuzeigen, und dann Shift+Cmd+., um Verzeichnisse und Dateien mit einem führenden Punkt sichtbar zu machen. Bei einem GUI-Dateimanager unter Linux müssen Sie möglicherweise eine Option „Versteckte Dateien anzeigen" im Menü „Ansicht" aktivieren.

Beispielinhalt einer Protokolldatei

Der einfachste Protokolldateiinhalt kann wie folgt aussehen:

<?xml version="1.0" encoding="windows-1252" standalone="no"?>
<!DOCTYPE log SYSTEM "logger.dtd">
<log>
<record>
  <date>2019-10-05T21:17:22</date>
  <millis>1570303042244</millis>
  <sequence>0</sequence>
  <logger>Structorizer</logger>
  <level>INFO</level>
  <class>Structorizer</class>
  <method>main</method>
  <thread>1</thread>
  <message>Command line: </message>
</record>
<record>
  <date>2019-10-05T21:17:22</date>
  <millis>1570303042416</millis>
  <sequence>1</sequence>
  <logger>lu.fisch.structorizer.gui.Mainform</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.gui.Mainform</class>
  <method>&lt;init&gt;</method>
  <thread>1</thread>
  <message>Structorizer 1 (version 3.30) starting up.</message>
</record>
<record>
  <date>2019-10-05T21:17:22</date>
  <millis>1570303042478</millis>
  <sequence>2</sequence>
  <logger>lu.fisch.structorizer.locales.Locale</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.locales.Locale</class>
  <method>&lt;init&gt;</method>
  <thread>1</thread>
  <message>Loading now locale: en.txt</message>
</record>
<record>
  <date>2019-10-05T21:18:04</date>
  <millis>1570303084255</millis>
  <sequence>22</sequence>
  <logger>lu.fisch.structorizer.gui.Mainform</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.gui.Mainform$4</class>
  <method>windowClosing</method>
  <thread>16</thread>
  <message>Structorizer 1 (version 3.30) shutting down.</message>
</record>

Sobald Sie z. B. eine Quelldatei importieren oder bei bestimmten Problemen, sind deutlich mehr Einträge (Records) verschiedener Levels zu erwarten.

Protokollierungskonfiguration

Der Speicherort der Datei logging.properties ist der Unterordner .structorizer im Heimverzeichnis des Benutzers (siehe Erörterung unter „Speicherort der Protokolldateien" oben).

Die Standardeinstellungen in der Properties-Datei lauten:

handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

(legt fest, dass Protokolleinträge zuerst in eine Datei und dann in die Konsole geschrieben werden)

.level= INFO

(legt fest, dass standardmäßig nur Protokolleinträge mit dem Level INFO und wichtiger protokolliert werden, sofern der jeweilige Protokoll-Handler keinen noch strengeren Filter vorschreibt)

java.util.logging.FileHandler.pattern = %h/.structorizer/structorizer%u.%g.log
java.util.logging.FileHandler.limit = 100000
java.util.logging.FileHandler.count = 5
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.level = CONFIG

(konfiguriert für die Datei-Protokollierung im Einzelnen:

wie die Protokolldateien benannt werden und wo sie abgelegt werden,
eine maximale Größe von 100.000 Bytes — rund 100 KiB — pro Protokolldatei, bevor die Protokollierung in die nächste Datei wechselt,
dass höchstens 5 Dateien (vor Release 3.30 war es nur 1 Datei) für eine rotierende Protokollierung verwendet werden — d. h. die Protokolldatei wird zyklisch überschrieben; Sie können eine größere Zahl angeben,
dass der Protokollinhalt im XML-Format formatiert wird und
dass Protokolleinträge ab Level CONFIG grundsätzlich zugelassen werden — was ausführlicher als nur INFO ist und bereits bestimmte Diagnose-Records enthält, aber erfordert, dass der Standard-Protokolllevel mindestens CONFIG ist.)

java.util.logging.ConsoleHandler.level = SEVERE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

(legt fest, dass der Konsolen-Protokollierungsfilter auf SEVERE angehoben wird — d. h. nahezu nichts wird an die Konsole weitergegeben, außer sehr kritischen Ereignissen — und dass die Konsolenmeldungen ein sehr einfaches zweizeiliges Format verwenden)

lu.fisch.structorizer.parsers.level = CONFIG

(legt fest, dass beim Quellcode-Import der allgemeine Protokolllevel-Schwellenwert INFO für jene Protokoll-Handler auf CONFIG gesenkt wird — und damit einige Entwicklerdiagnosen einschließt —, die dafür offen sind, d. h. für Datei oder Konsole)

Ausführlichere Informationen zur Protokollierungskonfiguration finden Sie in der offiziellen Java-Dokumentation.

Ihre individuellen Einstellungen in dieser Datei bleiben auch bei einem Update von Structorizer auf eine neue Version erhalten. Wenn Sie zu den ursprünglichen Standardeinstellungen von Structorizer zurückkehren oder umgekehrt auf die neuen Konfigurationen von Release 3.30 aktualisieren möchten, benennen Sie die Datei logging.properties vor dem nächsten Start von Structorizer um oder löschen Sie sie — Structorizer erstellt dann eine neue Standardkonfigurationsdatei im Ordner .structorizer.

Verwendung der Protokollergebnisse

Nach einem Funktionsproblem in Structorizer oder einem Absturz können Sie die entsprechende Protokolldatei aus dem Ordner .structorizer sichern (d. h. kopieren) und sie zusammen mit dem Fehlerbericht zur weiteren Analyse an das Structorizer-Entwicklerteam weiterleiten.

Beachten Sie, dass die Protokolldatei möglicherweise unvollständig ist, solange Structorizer noch läuft (wie oben erwähnt). Sie sollten Structorizer nicht erneut öffnen, bevor Sie die Protokolldatei kopiert haben, da ein Start von Structorizer eine vorhandene Protokolldatei überschreiben kann.

Datenschutzhinweis

Protokolldateien enthalten keine persönlichen Daten oder sensiblen Daten über Ihr System. Sie können jedoch Dateipfade und damit Benutzerkonto-Namen enthalten. Sie können den Inhalt natürlich einsehen und sicherstellen, dass keine Datenschutzrisiken bestehen, bevor Sie die Datei hochladen oder per E-Mail versenden — die Datei enthält standardmäßig XML (oder Klartext, wenn Sie z. B. java.util.logging.SimpleFormatter als Formatter angeben). Wenn Sie einige Informationen entfernen möchten, die Sie nicht teilen möchten, sollten Sie natürlich die wohlgeformte XML-Struktur erhalten.