Konfiguration Logging (fs-logging.xml) - Log4j 2

Im Unterverzeichnis conf des FirstSpirit-Servers befindet sich die Datei fs-logging.xml, die wichtige Konfigurationseinstellungen für die Log-Ausgaben enthält und bei Bedarf angepasst werden muss.

Änderungen an der Konfigurationsdatei fs-logging.xml können über das FirstSpirit ServerMonitoring vorgenommen werden (siehe Protokollierung). Die Änderungen werden dann in die Konfigurationsdatei geschrieben und auf dem Server aktualisiert. (Wenn Zugriff auf das Dateisystem besteht, können Änderungen an der fs-logging.xml auch direkt über die Konfigurationsdatei erfolgen.)

Auftretende Fehler und Infomeldungen werden dem Logging-Framework (z. B. „Log4j“, „Logback“) übergeben. Über das Framework kann eine Gewichtung der Log-Ausgaben vorgenommen werden. Das Konfigurationsbeispiel zeigt beispielsweise die Kategorien DEBUG, INFO und ERROR. Potenziell können aber noch weitere Kategorien konfiguriert werden (z. B. FATAL, WARN). Ausnahmen bilden die beiden Stufen ALL und OFF, die das Logging entweder komplett deaktivieren (OFF) oder alle Meldungen ungefiltert ausgeben (ALL).

Im Installationsumfang von FirstSpirit sind weitere Logging-Dateien enthalten. Die Aktivierung einer bestimmten Logging-Konfiguration sowie die Filterung und Art der Ausgabe kann zur Laufzeit über das ServerMonitoring konfiguriert werden (siehe Protokollierung).

Konfigurationsdateien müssen der Syntax

fs-logging.<Loglevel>.xml

folgen, damit sie von FirstSpirit erkannt werden und über das ServerMonitoring aktiviert werden können.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="de.espirit.firstspirit.server.logging">
   <Appenders>
      <!-- dated logging is used by server monitoring for log file display -->
      <FsAppender name="fs" datedLogging="true" maxFileSize="5MB" buffer="8192" flushCycle="10"/>
   </Appenders>
   <Loggers>
      <Logger name="org.eclipse.jetty" level="WARN" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache" level="WARN" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.fontbox" level="ERROR" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.pdfbox" level="ERROR" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Root level="INFO">
          <AppenderRef ref="fs"/>
      </Root>
   </Loggers>
</Configuration>

Zu weiterführenden Informationen zum Logging-Framework „log4j 2“ und eine Beschreibung der Parameter siehe https://logging.apache.org/log4j/2.x/manual/configuration.html

Angabe von Pfaden unter Windows: Soll eine Datei für die Ausgabe der Log-Dateien angegeben werden, so ist der Pfad folgendermaßen anzugeben (Pfadangabe durch / getrennt):

<File name="audit" fileName="/home/firstspirit/log/audit.log" bufferedIO="true" immediateFlush="true" append="true">

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="de.espirit.firstspirit.server.logging">
   <Appenders>
      <!-- dated logging is used by server monitoring for log file display -->
      <File name="audit" fileName="/home/firstspirit/log/audit.log" bufferedIO="true" immediateFlush="true" append="true">
         <PatternLayout>
            <pattern>%d{DEFAULT} %p %C{10} [%t] %m %n</pattern>
         </PatternLayout>
      </File>
      <FsAppender name="fs" consoleLogging="false" plainLogging="true"
datedLogging="true" maxFileSize="5MB" buffer="8192" flushCycle="10"/>
   </Appenders>
   <Loggers>
      <Logger name="de.espirit.firstspirit.logging.audit" level="INFO" additivity="false">
         <AppenderRef ref="audit"/>
      </Logger>
      ...
      <Root level="INFO">
         <AppenderRef ref="fs"/>
      </Root>
   </Loggers>
</Configuration>

Parameter zur Auswahl des Log-Verfahrens

Die im Folgenden beschriebenen Konfigurationsparameter dienen zur Auswahl des Log-Verfahrens und können unabhängig voneinander an- und ausgeschaltet werden. Erlaubte Werte sind hier false für „deaktiv“ und true für „aktiv“.

consoleLogging

Schalter für die Ausgabe der Log-Meldungen auf die Konsole (Kommandozeile/Shell), von der FirstSpirit gestartet wurde.

plainLogging

Schalter für die Ausgabe der Log-Meldungen als Klartext in eine Datei. Die Log-Datei für den Server hat den festen Namen fs-server.log.

datedLogging

Schalter für die Ausgabe der Log-Meldungen als Klartext in eine Datei. Die Log-Datei erhält hier immer den Zusatz des Datums des ersten Eintrags, also beispielsweise fs-server.20070322_100436.log (mit Ersteintrag vom 22. März 2007 um 10:04:36 Uhr). Dieser Parameter muss aktiviert werden, um die Suche innerhalb der Log-Dateien des ServerMonitoring zu ermöglichen.

Parameter zur Konfiguration der maximalen Dateigröße

maxFileSize

Dieser Parameter beeinflusst die maximal erlaubte Größe für eine Log-Datei. Der Wert gibt diese Größe in Bytes an. Standardwert sind 5 MByte.

Konfiguration der Log-Rotation

Abhängig vom Log-Verfahren erfolgt bei Erreichen der maximal erlaubten Größe der Log-Datei ein Zurücksetzen oder eine Rotation.

1. Ist der Parameter plainLogging aktiviert und der Parameter datedLogging deaktiviert, so wird die aktuelle Log-Datei (z. B. fs-server.log) umbenannt. Sie bekommt einen mit dem Datum des ersten Eintrags versehenen Zusatz (z. B. fs-server.20070322_100436.log). Die umbenannte Datei wird anschließend komprimiert und erhält die zusätzliche Endung .gz. Währenddessen wird in eine neu angelegte Log-Datei mit dem ursprünglichen Namen weiter geloggt.
2. Ist der Parameter plainLogging deaktiviert und der Parameter datedLogging aktiviert, so wird die aktuelle Log-Datei (z. B. fs-server.20070322_100436.log) komprimiert und erhält die zusätzliche Endung .gz. Währenddessen wird weiter in eine neu angelegte Log-Datei (mit neuem Datumszusatz) geloggt.
3. Sind die Parameter plainLogging und datedLogging aktiviert, so wird parallel in die Log-Datei ohne Datumszusatz und in die Log-Datei mit Datumszusatz geloggt. Eine Rotation erfolgt wie unter 2. (die Log-Datei ohne Datumszusatz wird lediglich zurückgesetzt).

Parameter zur Konfiguration des Log-Verhaltens

buffer

Beeinflusst die intern zu benutzende Puffergröße (in Bytes) (Standardwert: 8192 bytes). Der Puffer nimmt Log-Nachrichten auf und speichert diese, bis die Puffergröße erreicht ist. Erst dann werden die Nachrichten in die Log-Datei geschrieben, um unnötige und zeitintensive Schreiboperationen zu sparen. Bei Beendigung des Servers wird der Puffer auch bei Nichterreichen der Puffergröße geschrieben.

flushCycle

Bestimmt die maximale Zeit (in Sekunden) zwischen zwei Schreibvorgängen. Ist diese Zeit abgelaufen, wird der Puffer auch bei Nichterreichen der Puffergröße geschrieben.

Neben der Datei fs-server.log werden u.a. für die Fehlersuche wichtige Logmeldungen auch in die Datei fs-wrapper.log geschrieben (siehe Protokollierung).

Konfiguration des Audit-Logging

Es gibt die Möglichkeit, das FirstSpirit-Logging um Audit-Funktionen zu erweitern. Dies ist in einem eigenen Bereich dokumentiert, der hier zu finden ist: Audit-Logging in FirstSpirit.

Runlevel

Beim Start eines FirstSpirit-Servers stehen Informationen über den aktuellen Runlevel zur Verfügung.

Die Runlevel werden an verschiedenen Stellen ausgegeben:

• als Logausgabe in der Datei fs-server.log bzw. fs-wrapper.log
• als Wert [Zahl] in der Datei ~FS/.fs.lock

Anhand dieser Runlevels kann abgelesen werden, ob bzw. wann welche Server-Funktionalität zur Verfügung steht:

• SHUTDOWN (RunLevel 0)
  Der Server ist heruntergefahren.
  Hinweis: Die Datei ~FS/.fs.lock ist in diesem Runlevel nicht vorhanden.
• IN_PROGRESS (RunLevel 20)
  Der Server startet bzw. wird beendet, es sind keine Funktionalitäten sicher verfügbar.
• CORE_STARTED (RunLevel 40)
  Die Grundfunktionalitäten stehen zur Verfügung, der Server kann über den SOCKET-Port erreicht werden.
• ROOT_WEBAPP_STARTED (RunLevel 60)
  Der Server kann nun auch über den HTTP-Port erreicht werden.
• CORE_WEBAPPS_STARTED (RunLevel 80)
  Die globalen Web-Anwendungen stehen zur Verfügung.
• STARTED (RunLevel 100)
  Alle FirstSpirit-Funktionalitäten stehen zur Verfügung.

Auf diese Runlevel kann beispielweise per API reagiert werden (Interface RunLevelAgent, Package de.espirit.firstspirit.agency, FirstSpirit Access-API).