Logging

Zur Fehlersuche werden Code-Ausführungsinformationen, Warnungen und Fehler in Log-Dateien geschrieben. Im Folgenden wird beschrieben, wo diese zu finden sind, wie diese konfiguriert werden können und wie das Log-Level festgelegt werden kann.

Konfigurationsdatei

Karaf verwendet Apache Log4j 2 zum Logging. Dessen Properties basierte Konfigurationsdatei befindet sich unter [karaf]/etc/org.ops4j.pax.logging.cfg.

Logging-Dateien

Die Logging-Dateien werden in das Verzeichnis [karaf]/data/log geschrieben. Dieses Verzeichnis wird in der zuvor genannten Konfigurationsdatei über die Java-Systemproperty ${karaf.log} festgelegt.

In der Voreinstellung werden mehrere Logging-Dateien erstellt. Die folgenden Beiden sind BPC-spezifisch.

Logger	Level	Datei
authentication	WARN	authentication.log
de.virtimo.bpc	WARN	bpc.log

Logger

Level

Datei

authentication

WARN

authentication.log

de.virtimo.bpc

WARN

bpc.log

Log-Level einstellen

Der Detailgrad der zu loggenden Daten kann pro Logger per Log Level festgelegt werden. Die möglichen Log-Level sind TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF. Von links nach rechts werden immer weniger Daten bis zu gar keinen geloggt.

Per Karaf Shell Kommando

Über das Karaf Shell Kommando log:list kann man sich die konfigurierten Logger und deren Log-Level anzeigen lassen.

virtimo@bpc()> log:list
Logger                       │ Level
─────────────────────────────┼──────
ROOT                         │ INFO
audit                        │ TRACE
authentication               │ WARN
de.virtimo.bpc               │ WARN
org.apache.aries.spifly      │ WARN
org.apache.felix.fileinstall │ INFO
org.apache.sshd              │ INFO

Der Level eines Loggers lässt sich zur Laufzeit über das Kommando log:set <LEVEL> <Logger> festlegen. Im folgenden Beispiel wird der Logger de.virtimo.bpc vom Log-Level WARN auf INFO geändert.

virtimo@bpc()> log:set INFO de.virtimo.bpc

Per BPC Weboberfläche

Die Log-Level können auch über die BPC-Weboberfläche festgelegt werden. Dazu navigieren Sie als Administrator zu BPC Administration → Übersicht → Status.

loggers

Durch Klicken auf den Level eines Loggers öffnet sich eine Auswahlbox mit den möglichen Log-Leveln. Die Auswahl wird hierbei direkt übernommen.

Neue Logger anlegen

Für das gezielte Troubleshooting oder für spezifische Entwicklungszwecke kann es sinnvoll sein, eigene Logger zu definieren. Diese können individuelle Log-Level und Log-Dateien verwenden, um relevante Informationen separiert von anderen Log-Daten zu speichern.

Logger per Konfigurationsdatei anlegen

Öffnen Sie die Datei org.ops4j.pax.logging.cfg im Verzeichnis [karaf]/etc.
Fügen Sie einen neuen Abschnitt hinzu, in dem Sie den Namen des Loggers sowie dessen Log-Level und Appender festlegen. Der folgende Beispiel-Logger zeichnet alle Nachrichten des H2-Datenbank-Pakets h2database auf:

# H2-Datenbank-Logger
log4j2.logger.h2database.name = h2database (1)
log4j2.logger.h2database.level = DEBUG (2)
log4j2.logger.h2database.additivity = false (3)
log4j2.logger.h2database.appenderRef.H2dbRollingFile.ref = H2dbRollingFile (4)

1	Der Name des Loggers, in diesem Fall `h2database`, der für H2-Datenbank-Logs verwendet wird.
2	Das gewünschte Log-Level (z.B. `TRACE`, `DEBUG`, `INFO`, etc.).
3	Legen Sie `additivity` auf `false` fest, um zu verhindern, dass Log-Nachrichten auch an andere Logger weitergegeben werden.
4	Hier wird angegeben, welcher Appender die Logs des neuen Loggers schreiben soll. In diesem Beispiel wird `H2dbRollingFile` als Appender verwendet, der ebenfalls in der Konfigurationsdatei definiert sein muss.

Beachten Sie unbedingt die Dokumentation des Java-Pakets, zu dem Sie den Logger anlegen.
Die H2-Datenbank erfordert beispielsweise explizit ein Trace-Level von 4, um Logs zu erhalten. Dies erfolgt durch Anpassung der JDBC-URL: jdbc:h2:tcp://localhost/~/test;TRACE_LEVEL_FILE=4;
Auch für den Logger-Namen muss explizit "h2database", statt des üblichen Java-Paketnamens (bspw. org.h2.jdbc) angegeben werden. (Siehe H2-Datenbank)

Fügen Sie einen neuen Abschnitt hinzu, in dem Sie den Appender festlegen. Der folgende Beispiel-Appender speichert alle H2-Datenbank-Logs in der Datei h2.log und sorgt für eine Rotation der Logdateien, sobald diese 20 MB erreicht haben.

# H2 Appender
log4j2.appender.H2database.type = RollingRandomAccessFile (1)
log4j2.appender.H2database.name = H2dbRollingFile (2)
log4j2.appender.H2database.fileName = ${karaf.log}/h2.log (3)
log4j2.appender.H2database.filePattern = ${karaf.log}/h2.log.%i (4)
log4j2.appender.H2database.append = true (5)
log4j2.appender.H2database.layout.type = PatternLayout (6)
log4j2.appender.H2database.layout.pattern = ${log4j2.maskpasswords.pattern} (7)
log4j2.appender.H2database.policies.type = Policies (8)
log4j2.appender.H2database.policies.size.type = SizeBasedTriggeringPolicy (9)
log4j2.appender.H2database.policies.size.size = 20MB (10)
log4j2.appender.H2database.strategy.type = DefaultRolloverStrategy (11)
log4j2.appender.H2database.strategy.max = 5 (12)

1	Der `type` wird auf `RollingRandomAccessFile` gesetzt, um eine Log-Datei zu erstellen, die bei Erreichen einer bestimmten Größe rotiert.
2	Der Name des Appenders, hier `H2dbRollingFile`, muss im Logger als appenderRef referenziert werden.
3	Der `fileName` gibt den Pfad und Namen der Hauptlogdatei an, in diesem Fall `h2.log`.
4	`filePattern` legt das Rotationsmuster fest. Bei einer neuen Log-Datei wird das Muster `jdbc.log.%i` verwendet, wobei `%i` für die Nummer der Datei steht.
5	`append = true` sorgt dafür, dass neue Logs an die bestehende Datei angehängt werden, anstatt diese zu überschreiben.
6	Der `layout.type` wird auf `PatternLayout` gesetzt, um ein anpassbares Muster für die Logausgabe zu ermöglichen.
7	`layout.pattern` verwendet ein vordefiniertes Muster für die Ausgabeformatierung, das Passwörter maskiert (durch `${log4j2.maskpasswords.pattern}`).
8	`policies.type = Policies` definiert eine Sammlung von Regeln, die bestimmen, wann eine Logrotation ausgelöst wird.
9	`policies.size.type = SizeBasedTriggeringPolicy` bedeutet, dass die Rotation auf Basis der Dateigröße ausgelöst wird.
10	`policies.size.size = 20MB` legt fest, dass eine Rotation erfolgt, sobald die Datei 20 MB erreicht hat.
11	`strategy.type = DefaultRolloverStrategy` gibt die Standardstrategie für das Rotationsverhalten an.
12	`strategy.max = 5` begrenzt die Anzahl der gespeicherten, rotierten Dateien auf 5, wobei die älteste Datei gelöscht wird, wenn das Limit erreicht ist.

Logger-Änderungen werden zur Laufzeit erfasst. Es ist kein Neustart von Karaf erforderlich, nachdem Sie die Änderungen in org.ops4j.pax.logging.cfg gespeichert haben.

Logger per Shell-Kommando anlegen

Es ist möglich, zur Laufzeit einen neuen Logger über die Karaf-Shell anzulegen und zu konfigurieren. Dies ist besonders hilfreich, wenn Sie schnell zusätzliche Logs für ein bestimmtes Paket oder eine Klasse aktivieren möchten, ohne die Konfigurationsdatei manuell zu bearbeiten.
Um einen Logger über die Shell anzulegen, verwenden Sie die folgenden Schritte:

Shell öffnen: Melden Sie sich an der Karaf-Shell an, siehe auch Karaf Zugriff
Logger hinzufügen: Verwenden Sie das Kommando log:set, um einen neuen Logger mit dem gewünschten Log-Level anzulegen. Hier ein Beispiel für das Hinzufügen eines Loggers für das Paket h2database mit dem Log-Level DEBUG: log:set DEBUG h2database
Aktive Logger anzeigen: Um sicherzustellen, dass der Logger erfolgreich hinzugefügt wurde, können Sie alle konfigurierten Logger mit dem folgenden Befehl auflisten: log:list

Wenn Sie den Logger per Shell-Kommando angelegt haben, werden die Logs standardmäßig in den rootLogger (hier karaf.log) geschrieben. Um weitere Anpassungen vorzunehmen, konfigurieren Sie org.ops4j.pax.logging.cfg wie in Logger per Konfigurationsdatei anlegen.

Keywords: