Eine fehlgeschlagene Aktion im selbst gehosteten Stack nachverfolgen: die Checkliste
Mit dieser Checkliste prüfst du, welche Protokolle, Kennungen und Zeitangaben dir helfen können, eine fehlgeschlagene Aktion in deinem selbst gehosteten Stack nachzuvollziehen.
Skizziere den Ablauf, bevor du die Logs durchsuchst
Beginne mit dem sichtbaren Fehler: Was ist passiert, wann ungefähr und welches Ergebnis hast du erwartet? Skizziere dann, welche Teile deiner Anwendung an der Aktion beteiligt sein könnten. Je nach Stack können das etwa ein Reverse-Proxy, die Anwendung, ein Hintergrund-Worker, eine Datenbank oder ein externer Dienst sein.
Nutze die Skizze als Suchplan. Prüfe, welche Komponenten Protokolle bereitstellen, wie du darauf zugreifst und welche Einträge etwas über den Eingang oder Abschluss der Aktion aussagen könnten.
- Welche Aktion ist fehlgeschlagen, und wann ist das ungefähr passiert?
- Welche Komponenten könnten beteiligt gewesen sein, auch wenn die Verarbeitung asynchron abläuft?
- Wo findest du die Protokolle der einzelnen Komponenten?
- Gibt es Teile des Ablaufs, für die dir keine Protokolle zur Verfügung stehen?
Suche nach einer Kennung, die Ereignisse verbindet
Eine Request-ID oder Korrelations-ID kann als Suchbegriff helfen, zusammengehörige Ereignisse zu finden. Prüfe in den tatsächlich verfügbaren Protokollen, ob eine solche Kennung vorhanden ist und wie sie dort dargestellt wird.
Suche dieselbe Kennung in den Protokollen der beteiligten Komponenten. Falls sie nicht überall auftaucht, notiere, an welcher Stelle die Verbindung abbricht. Du kannst auch andere vorhandene Felder nutzen, um die Suche einzugrenzen.
- Welche Kennungen enthalten die Protokolle tatsächlich?
- Findest du dieselbe Kennung im Proxy, in der Anwendung und in nachgelagerten Komponenten?
- Welche weiteren Felder können die Suche eingrenzen, etwa ein Zeitfenster oder eine Job-ID?
- Enthält eine Kennung Informationen, die nicht in den Protokollen stehen sollten?
Verknüpfe die Aktion mit einem Warteschlangenjob
Falls die Aktion einen Warteschlangenjob auslöst, vergleiche die Einträge zum Einreihen, Starten und Abschließen des Jobs. Achte darauf, welche Kennungen in den jeweiligen Protokollen auftauchen und ob du daraus eine Verbindung zur ursprünglichen Aktion herstellen kannst.
Halte fest, welche Schritte sich anhand der Einträge nachvollziehen lassen und wo keine Verbindung erkennbar ist. Eine Job-ID kann bei der Suche helfen, wenn sie in den verfügbaren Protokollen steht.
- Gibt es einen Eintrag zum Einreihen des Jobs, und welche Kennungen enthält er?
- Welche Einträge gibt es zum Start und Ergebnis des Jobs?
- Lassen sich die Job-Einträge einer Job-ID und der auslösenden Aktion zuordnen?
- Ist kein Einreihungsereignis auffindbar, oder fehlt ein sichtbares Ergebnis für einen eingereihten Job?
Vergleiche Zeitstempel und Log-Felder
Prüfe, welche Zeitstempel und Felder in den Protokollen vorhanden sind und ob deine Suchwerkzeuge sie erkennen. Achte auf die angegebene Zeitzone, wenn du Einträge aus verschiedenen Komponenten vergleichst. So kannst du die Ereignisse nach Zeit und Inhalt ordnen und erkennen, welche Schritte sich belegen lassen.
Für die Korrelation von Logs mit Traces empfiehlt Datadog, Logs im JSON-Format bereitzustellen oder sie mit dem passenden sprachspezifischen Log-Prozessor zu parsen. Diese Empfehlung bezieht sich auf die Korrelation mit Traces. Für eine Suche nur in Logs prüfe, welche Felder deine Werkzeuge durchsuchen können. (Datadog: [Logs und Traces korrelieren](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/))
- Welche Einträge enthalten Zeitstempel, Komponentennamen, Schweregrad, Meldung oder Kennungsfelder?
- Ist bei den Zeitangaben eine Zeitzone angegeben?
- Erkennen deine Suchwerkzeuge die benötigten Felder, oder musst du im Text der Einträge suchen?
- Welche Reihenfolge der Ereignisse lässt sich anhand der vorhandenen Einträge nachvollziehen?
Nutze ein kontrolliertes Beispiel
Wenn du prüfen möchtest, wie gut sich eine Aktion über mehrere Komponenten hinweg nachvollziehen lässt, wähle ein passendes Beispiel mit einem erwartbaren Ergebnis. Achte darauf, dass die Prüfung deine wichtigen Abläufe und Daten nicht beeinträchtigt.
Suche anschließend die Einträge zur Aktion, verfolge vorhandene Kennungen und prüfe, ob du den Ablauf bis zum Ergebnis nachzeichnen kannst. Notiere, wo Protokolle oder Verknüpfungen fehlen.
- Kannst du eine Aktion mit einem klar erwarteten Ergebnis auswählen?
- Welche Einträge findest du dazu, und welche Kennungen enthalten sie?
- Lässt sich ein möglicher Job mit der auslösenden Aktion verbinden?
- Wo werden Zeitangaben, Felder oder Verknüpfungen unklar?
Prüfe Inhalt, Zugriff und Verfügbarkeit der Logs
Sieh dir Beispiele aus den Protokollen an und prüfe, welche Informationen darin erscheinen. Achte besonders auf Zugangsdaten, Tokens und personenbezogene Daten, die für die Untersuchung nicht benötigt werden.
Kläre außerdem, wer auf die Protokolle zugreifen kann und wie lange sie verfügbar sind. Halte fest, wo diese Regelungen dokumentiert sind und ob sie zu den Anforderungen deiner Anwendung passen.
- Welche Informationen zeigen die Log-Beispiele?
- Sind darin Zugangsdaten, Tokens oder unnötige personenbezogene Daten enthalten?
- Wer kann auf die Protokolle zugreifen?
- Wie lange bleiben sie verfügbar, und wo sind die geltenden Regeln dokumentiert?
Ordne die Aussagekraft der Protokolle ein
Protokolle können Hinweise auf den Ablauf eines Fehlers geben. Prüfe, welche Schritte deiner Aktion sich anhand der vorhandenen Einträge nachvollziehen lassen und welche offenbleiben.
Wenn du Aufzeichnungen für Rechenschaftspflicht oder Governance benötigst, kläre separat, welche Nachweise dafür erforderlich sind. Dokumentiere Lücken, fehlende Kennungen und Ereignisse, die sich nicht zuverlässig verknüpfen lassen.
- Welche Teile des Ablaufs sind durch vorhandene Protokolle nachvollziehbar?
- Welche Fragen bleiben offen, weil Einträge oder Verknüpfungen fehlen?
- Benötigen deine Governance-Anforderungen zusätzliche oder andere Aufzeichnungen?
- Welche Änderungen an Komponenten oder Protokollierungseinstellungen könnten die Nachvollziehbarkeit beeinflussen?
Häufige Fragen
Benötige ich Distributed Tracing, um eine fehlgeschlagene Aktion zu untersuchen?
Diese Checkliste konzentriert sich auf die Protokolle, die in deinem Stack vorhanden und durchsuchbar sind. Prüfe, ob du zusammengehörige Einträge anhand einer Kennung, eines Zeitfensters oder anderer vorhandener Felder finden kannst.
Was kann ich tun, wenn ein Warteschlangenjob keine Request-ID enthält?
Suche nach einer Job-ID in den Einträgen zum Einreihen und zur Verarbeitung. Prüfe, ob sie sich mit der auslösenden Aktion verbinden lässt. Wenn keine verlässliche Verbindung erkennbar ist, halte fest, wo die Nachverfolgung endet.
Sollten Anwendungslogs im JSON-Format vorliegen?
Für die Korrelation von Logs mit Traces empfiehlt Datadog, Logs im JSON-Format bereitzustellen oder sie mit dem passenden sprachspezifischen Log-Prozessor zu parsen: https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/. Für andere Untersuchungen prüfe, welche Formate deine Log-Werkzeuge erkennen und durchsuchen können.
Sind Diagnose-Logs dasselbe wie Aufzeichnungen für Rechenschaftspflicht?
Prüfe, welche Aussagen sich anhand deiner Diagnose-Logs tatsächlich treffen lassen und ob deine Anforderungen an Rechenschaftspflicht oder Governance zusätzliche oder andere Aufzeichnungen erfordern.
Wie prüfe ich den Zugriff auf Logs und ihre Aufbewahrung?
Kläre, wer auf die Protokolle zugreifen kann, wie lange sie verfügbar sind und wo die dafür geltenden Regeln dokumentiert sind. Vergleiche diese Regelungen mit den Anforderungen deiner Anwendung.
Quellen und weiterführende Literatur
- Correlate Logs and Traces — Datadog
- Application logs and agent traces in one view — Braintrust