Aussagekräftige Log-Nachrichten

Rolf Jufer

10. Aug. 2023 • 4 min read

Es ist schwierig, inhaltlich sinnvolle Log-Meldungen zu schreiben. Zwar gibt es eine Vielzahl von Leitfäden, welche die Implementierung von Log-Messages auf technischer Ebene erläutern. Hinweise, wie diese inhaltlich zu formulieren sind, damit sie nützlich sind, gibt es jedoch kaum.

Das Schreiben von aussagekräftigen Log-Nachrichten ist ebenso wichtig wie die technische Implementierung. Gut formulierte Log-Nachrichten helfen nicht nur beim Debuggen und der Wartung von Code, sondern auch bei der Überwachung und Analyse von Anwendungen.

Nachstehend einige Hinweise, wie man inhaltlich nützliche Log-Nachrichten formulieren kann.

Stellen Sie sicher, dass die Log-Nachricht den Kontext und die Relevanz der Situation beschreibt. Beantworten Sie die Fragen: Was ist passiert? Warum ist es wichtig? Welche Komponente oder Funktion ist betroffen?
Vermeiden Sie internen Fachjargon. Verwenden Sie stattdessen eine klare und präzise Sprache, um sicherzustellen, dass auch Personen, welche den Code nicht kennen, die Bedeutung der Nachricht verstehen können.
Verwenden Sie ein konsistentes Format für Log-Nachrichten. Dies erleichtert das Filtern, Analysieren und Sortieren der Nachrichten, wenn diese in Log-Dateien oder Dashboards angezeigt werden.
Nutzen Sie verschiedene Log-Levels (z.B. DEBUG, INFO, WARN, ERROR) entsprechend der Dringlichkeit und Bedeutung der Nachricht. Dies hilft dabei, Probleme schnell zu erkennen und angemessen darauf zu reagieren.
Fügen Sie nach Möglichkeiten relevante Variablenwerte oder Zustandsinformationen zur Log-Nachricht hinzu. Dies kann bei der Diagnose von Fehlern und der Nachverfolgung von Problemen sehr hilfreich sein.
Ergänzen Sie die Log-Nachricht jeweils mit einem Zeitstempel, um den Zeitpunkt des Ereignisses festzuhalten. Dies ist besonders wichtig, wenn Sie zeitabhängige Abläufe überwachen.
Bei Fehlern oder Ausnahmen sollten Sie nicht nur die Fehlermeldung protokollieren, sondern auch den Kontext und mögliche Ursachen beschreiben. Dies erleichtert die Fehleranalyse und -behebung.
Wenn die Anwendung Benutzerinteraktionen verarbeitet, protokollieren Sie wichtige Ereignisse, z.B. Anmeldungen, Aktionen oder Transaktionen. Dies kann bei der Verfolgung von Benutzerverhalten und -problemen hilfreich sein.
Achten Sie streng darauf, keine sensiblen oder persönlichen Informationen in Log-Nachrichten aufzunehmen, um Sicherheits- und Datenschutzrichtlinien einzuhalten.
Bedenken Sie auch, dass Log-Nachrichten oft langfristig gespeichert werden. Formulieren Sie Nachrichten so, dass sie auch Wochen oder Monate später verständlich und aussagekräftig bleiben.
In der Regel sollten Log-Nachrichten in der Standardsprache der Anwendung verfasst werden, um die Klarheit, Konsistenz und Verständlichkeit zu gewährleisten. Es ist wichtig, dass Entwickler, Support-Teams und andere Personen, welche die Logs überwachen, die Nachrichten ohne Übersetzung verstehen können: Es gibt jedoch einige Szenarien, in denen mehrsprachige Log-Nachrichten sinnvoll sein könnten: Mehrsprachige Anwendungen, Internationale Teams, Systeme mit unterschiedlichen Sprachen.

Beispiele für gut formulierte Log-Nachrichten:

// DEBUG-Nachricht zur Verfolgung eines Schleifendurchlaufs:
logger.debug("Verarbeite Element {0} von {1} in der Schleife.", currentIndex, totalElements);

// INFO-Nachricht zur Erfassung einer wichtigen Aktion:
logger.info("Neuer Benutzer {0} wurde erfolgreich registriert.", newUsername);

// WARN-Nachricht für eine kritische Situation:
logger.warn("Verbindungszeitüberschreitung beim Zugriff auf {0}. Möglicherweise besteht ein Netzwerkproblem.", endpointUrl);

// ERROR-Nachricht zur Protokollierung einer Ausnahme:
logger.error("Fehler beim Verarbeiten der Anfrage: {0}. Details: {1}", errorMessage, exception.getMessage());

// INFO-Nachricht zur Verfolgung einer erfolgreichen 
// Datenbankoperation:
logger.info("Datensatz mit ID {0} wurde erfolgreich aktualisiert.", 

// INFO-Nachricht zur Verfolgung eines erfolgreichen Imports:
logger.info("Import abgeschlossen. {0} Datensätze wurden erfolgreich verarbeitet.", importedCount);

// DEBUG-Nachricht zur Verfolgung von Benutzeraktionen:
logger.debug("Benutzer {0} hat die Option '{1}' ausgewählt.", username, selectedOption);

// WARN-Nachricht zur Erkennung eines überhöhten Ressourcenverbrauchs:
logger.warn("Der Speicherverbrauch hat {0}% erreicht. Es könnte zu Leistungsproblemen kommen.", memoryUsagePercentage);

// ERROR-Nachricht zur Protokollierung einer kritischen Systemstörung:
logger.error("Kritischer Fehler: Die Datenbankverbindung konnte nicht hergestellt werden. Anwendung wird beendet.");

Diese Beispiele verdeutlichen, wie unterschiedliche Arten von Ereignissen und Situationen in Log-Nachrichten dargestellt werden können.

Beispiele von Log-Nachrichten, welche vermieden werden sollten:

// Unspezifische Nachrichten ohne Kontext:
logger.info("Fehler aufgetreten.");

// Zu technische Details ohne Bedeutung:
logger.debug("Variable x = 42, y = 17, z = 99.");

// Nicht aussagekräftige Fehlermeldungen:
logger.error("Fehler beim Ausführen der Methode.");

// Übermässig viele Meldungen ohne Wert:
for (int i = 0; i < 1000; i++) {
    logger.debug("Schleifendurchlauf Nr. {0}.", i);
}

// Fehlende Zeitstempel:
logger.info("Benutzer angemeldet.");

// Zu viele technische Details in Produktionslogs:
logger.error("NullPointerException: at com.example.MyClass.method(MyClass.java:42)");

//Vertrauliche oder sensible Informationen in Logs:
logger.error("Fehler: Benutzername: {0}, Passwort: {1}", username, password);

Die Formulierung der Nachrichten hängt aber letztlich immer von der Art der Anwendung, den Anforderungen an die Protokollierung und dem gewünschten Detailgrad ab.

Unterschied zwischen einer Log-Nachricht und einer Exception-Nachricht

Eine Log-Nachricht und eine Nachricht bei Auftreten einer Exception dienen unterschiedlichen Zwecken, sind aber eng miteinander verbunden:

Log-Nachricht:

Eine Log-Nachricht ist eine vom Entwickler platzierte Information, die im Protokoll (Log) einer Anwendung aufgezeichnet wird. Sie dient dazu, wichtige Ereignisse, Zustände, Aktionen oder Fehler während der Laufzeit der Anwendung zu dokumentieren.
Log-Nachrichten helfen beim Verständnis des Anwendungsverhaltens, der Diagnose von Fehlern und der Überwachung der Anwendung im Produktionsbetrieb.
Sie können in verschiedenen Ebenen wie DEBUG, INFO, WARN und ERROR protokolliert werden, je nach Dringlichkeit und Relevanz des Ereignisses.
Log-Nachrichten können vielfältige Informationen enthalten, darunter Kontext, Zeitstempel, Zustandsinformationen, Benutzeraktionen usw.

Nachricht bei einer Exception:

Eine Exception-Nachricht ist eine Information, die mit einer Ausnahme (Exception) in Verbindung steht. Eine Exception ist eine spezielle Art von Ereignis, welches sich manifestiert, wenn während der Ausführung des Codes ein Fehler auftritt.
Die Nachricht bei einer Exception beschreibt normalerweise das Problem oder den Grund für den Fehler. Sie kann den Entwicklern oder Benutzern helfen, den Fehler besser zu verstehen.
Exceptions können abgefangen und behandelt werden, entweder um den Fehler zu beheben oder um eine angemessene Reaktion darauf zu geben.
In der Regel enthalten Exception-Nachrichten technische Details, die es Entwicklern ermöglichen, die Ursache des Fehlers zu identifizieren und zu beheben.

In vielen Fällen werden Log-Nachrichten verwendet, um Ereignisse zu protokollieren, die nicht unbedingt fehlerhaft sind, sondern Informationen über den Zustand und das Verhalten der Anwendung liefern. Nachrichten bei Exceptions hingegen sind spezifisch mit Fehlern verbunden und sollen helfen, die Fehlerursache zu identifizieren und gegebenenfalls zu beheben.

Es ist eine bewährte Praxis, in Log-Nachrichten auch Informationen über aufgetretene Exceptions einzufügen, um das Protokoll während der Fehlersuche aussagekräftiger zu machen.

Zusammenfassung

Log-Nachrichten sind protokollierte Informationen, die relevante Ereignisse, Zustände und Fehler in Anwendungen während der Laufzeit dokumentieren. Sie dienen der Verständnisförderung, Fehlerdiagnose und Überwachung. Nachrichten bei Exceptions sind mit Fehlern verknüpfte Informationen und beschreiben das Problem, das zu einem Fehler geführt hat. Beide sind wichtig: Log-Nachrichten geben Einblick in den Anwendungsfluss, während Nachrichten bei Exceptions die Fehlerursachen verdeutlichen. Zusammen ergänzen sie sich für ein besseres Verständnis und eine effektive Fehlersuche in der Softwareentwicklung.

Bleiben Sie informiert.