Konzept Logging

Um zu verdeutlichen, dass es sich bei Logeinträgen um Entitäten – und nicht einfach nur einen „Freitext“ – handelt, wird der Inhalt eines Logeintrags in Abbildung 1 in Form von Entitäten dargestellt.

Jeder Logeintrag muss gewisse Standardinformationen enthalten. Diese sind in der Entität ETY_Logeintrag zusammengefasst. Je nach Zweck des Eintrags müssen jedoch noch weitere auswertbare Informationen (bspw. die Verarbeitungszeit eines Aufrufs) hinterlegt werden. Dies geschieht in Form von Markern (ETY_Marker), die eine generische Ergänzung des Logeintrags um Name/Wert-Paare ermöglichen.

Die Inhalte der Entitäten werden im Folgenden beschrieben.

Log-Level, Log-Kategorie und Ereignisschlüssel werden in dem Dokument Logging - Nutzungsvorgaben beschrieben.

Die Korrelations-ID ist immer mitzuloggen, damit die Logeinträge einzelnen Aufrufen zugeordnet und über die Komponenten der Anwendungs­landschaft verfolgt werden können. Die Korrelations-ID besteht aus einer Liste von IDs. Jede ID besteht ihrerseits wiederum aus einem UUID sowie einem optionalen Präfix. Die Korrelations-ID enthält die einzelnen IDs in der Reihenfolge, in der sie erzeugt wurden. Somit ist die letzte ID der Korrelations-ID stets die des aktuellen Systemaufrufs.

Eine exemplarische Korrelations-ID ist demnach (als JSON-Array formatiert):

{"c15638a2-4c38-4d18-b887-5ebd2a1c427d",
"f60143b3-3408-4501-9947-240ec1c48667",
"BATCH-c893d44f-3b8e-446e-a360-06a520440e64"}

Die Nachricht enthält eine menschenlesbare Beschreibung des eingetretenen Logereignisses. Diese ist dann relevant, wenn die Logeinträge unverarbeitet durch einen (menschlichen) Anwender ausgewertet werden, was insbesondere bei der Fehleranalyse der Fall ist.

Die Nachrichten sind so weit wie möglich zu vereinheitlichen. Dazu werden in dem Dokument Logging - Nutzungsvorgaben klare Vorgaben definiert, welche Nachrichten in welcher Situation zu erstellen sind.

Datenverarbeitung im Auftrag – auch Auftragsdatenverarbeitung (ADV) genannt – bezeichnete in Deutschland die Erhebung, Verarbeitung oder Nutzung personenbezogener Daten durch einen Dienstleister im Auftrag des Verantwortlichen. Seit Inkrafttreten der DSGVO regelt Artikel 28 der DSGVO die Verarbeitung im Auftrag. Artikel 28 verweist wiederum auf Artikel 32 der DSGVO, in dem eine Pseudonymisierung und Verschlüsselung personenbezogener Daten gefordert wird. Für die Weitergabe von Log Dateien an Auftragsverarbeiter (Entwickler) bedeutet das konkret, dass personenbezogene Daten nur pseudonymisiert weitergegeben werden dürfen.

Ausnahme: Sollten die datenschutzrechtlich- oder sicherheitsrelevanten Daten zur Analyse zwingend notwendig sein – bspw., wenn fachlich fehlerhafte Daten zu technischen Fehlern führen – dürfen diese Daten im dafür notwendigen Maße mitgeschrieben werden. Die entsprechenden Logeinträge müssen durch einen Marker markiert werden, damit sie durch die Loginfrastruktur gesondert behandelt werden können. Die Daten dürfen nur so lange aufbewahrt werden, wie es für die Analyse der Daten zwingend erforderlich ist.

Die Logeinträge werden im JSON-Format ausgegeben. Dies hat den Vorteil, dass die Einträge dadurch sehr einfach maschinell verarbeitet werden können und der Umfang der erzeugten Datenmengen (bspw. im Vergleich zu XML) reduziert wird. Die „Menschenlesbarkeit“ der erstellten Einträge wird durch die Verwendung von JSON leicht eingeschränkt, dies ist aber akzeptiert, da eine Aufbereitung der Logeinträge durch die Log-Infrastruktur stattfindet (siehe Kapitel Log-Auswertung).

Jedes Attribut eines Logeintrags wird in einem entsprechenden JSON Name/Wert-Paar abgelegt. Attributnamen werden dabei komplett in Kleinbuchstaben und ohne Sonderzeichen geschrieben. Im Folgenden wird ein exemplarischer Logeintrag dargestellt, ergänzt um Leerzeichen und Zeilenumbrüche um die Lesbarkeit zu erhöhen:

Zu beachten ist, dass durch das Logging-Framework sichergestellt wird, dass nur fest definierte Marker in den Logeintrag aufgenommen werden. Die Vergabe „beliebiger“ Marker ist nicht möglich, so dass ein Namenskonflikt zwischen Marker und den anderen Attributen des Eintrags ausgeschlossen ist.

Ein tatsächlicher Logeintrag (ohne zusätzliche Leerzeichen und Zeilenumbrüche) sieht demnach wie folgt aus:

Die Vorgaben zu Logdateien sowie deren Rotation und Komprimierung sind in den Nutzungsvorgaben Logging beschrieben.

isy-logging stellt eine Fassade zum Zugriff auf logback bzw. auf dessen Schnittstellen, die durch das allgemeine Framework SLF4J definiert werden, bereit. Wichtig ist, dass durch isy-logging selbst SLF4J nicht implementiert wird. Dies wird aus zwei Gründen nicht gemacht:

In Abbildung 2 ist eine Übersicht der Implementierung der Fassade dargestellt.

Die Klassen der Fassade sind in Tabelle 4 beschrieben.

Zur Aufbereitung der Logeinträge im JSON-Layout (Siehe Kapitel Logformat) steht die Klasse IsyJsonLayout zur Verfügung. Diese erweitert die Klasse JsonLayout von logback um die Auswertung der IsyMarker. Wird ein entsprechender Marker übergeben, so schreibt die Klasse diesen und alle enthaltenen Marker als Name/Wert-Paare (JSON-Attribute) in das Log.

Die zusätzliche Inhalte, die mithilfe von IsyMarker gespeichert werden, werden im Abschnitt Zusätzliche Inhalte mit isy-logging beschrieben.

In Abbildung 4 ist das Zusammenspiel der verschiedenen Klassen zur Aufbereitung der Logeinträge dargestellt.

isy-logging stellt zwei Hilfsklassen zur Erstellung von Logeinträgen bereit, um die Umsetzung der in dem Dokument Logging - Nutzungsvorgaben definierten Szenarien an die Logerstellung zu vereinfachen. Diese sind in Abbildung 5 dargestellt.

Die Klasse LogInterceptor dient dabei als Hilfsklasse, um verschiedene Informationen zu Methodenaufrufen zu loggen und wird per Spring-AOP konfiguriert.

Die Klasse LogApplicationListener dient dem Loggen von wichtigen Systemereignissen und wird als Spring-Bean konfiguriert.

Die Informationen zur Konfiguration und Verwendung der beiden Klassen sind in dem Dokument Logging - Nutzungsvorgaben beschrieben und werden an dieser Stelle nicht wiederholt.

Logback wird als einzige Implementierung von SLF4J eingesetzt (IsyLoggerFactory implementiert das Interface LoggerFactory von SLF4J nicht). Externe Bibliotheken, die SLF4J oder logback nutzen und in die Anwendung eingebunden werden, nutzen dadurch direkt die LoggerFactory und damit auch den Logger, der durch logback bereitgestellt wird. Dies ist ohne Einschränkungen möglich, da die Vereinheitlichung der Logeinträge durch das IsyJsonLayout auch in diesem Fall durchgeführt wird. Für Frameworks, die weder logback noch SLF4J nutzen, werden durch SLF4J entsprechende „Bridging Modules“ bereitgestellt, durch die die Aufrufe des Logging-Frameworks auf SLF4J (bzw. logback) umgeleitet werden können. Diese sind zu verwenden, so dass die Erstellung der Logeinträge ausschließlich durch logback erfolgt. Die Nutzung der Bridges ist in dem Dokument Logging - Nutzungsvorgaben) beschrieben.

Wie in dem Dokument Logging - Nutzungsvorgaben beschrieben, besitzen SLF4J und logback kein Log-Level FATAL. Log-Einträge im Level FATAL und ERROR erscheinen in den Logs beide im Level ERROR, können aber an Hand der Kategorie (FATAL oder ERROR) unterschieden werden:

Für die systematische Auswertung der Logeinträge durch die Betriebsplattform ist der Zeitstempel von besonderer Bedeutung. Daher stellt die Bibliothek isy-logging sicher, dass der Zeitstempel möglichst am Anfang des Logeintrags steht.