Sechs Monate OpenClaw-Logs. Das war, was ich hatte, als ich mich endlich hingesetzt habe, um zu verstehen, warum einige Debugging-Sitzungen 5 Minuten dauerten und andere 2 Stunden. Die Antwort war mit dem nötigen Abstand offensichtlich: die Protokollierung.
Das Wissen, ob ich Logs hatte — ich hatte immer Logs. Das Problem war, dass die Hälfte meiner Logs unnötige Geräusche waren („Prozess gestartet… Prozess läuft… Prozess läuft immer noch…“) und die andere Hälfte fehlte die Informationen, die ich wirklich brauchte, wenn die Dinge schief gingen.
Hier ist, was ich geändert habe, und wie meine Debugging-Zeit von durchschnittlich 45 Minuten auf etwa 12 Minuten pro Vorfall gesunken ist.
Das Problem mit der Standardprotokollierung
Die Standardprotokollierung wird von Entwicklern konzipiert, die wissen, was alles bedeutet. Wenn der Entwickler sieht „Kontextkompaktierung ausgelöst bei 142K Zeichen“, weiß er genau, was das bedeutet und was er als Nächstes überprüfen muss. Wenn ich es um 3 Uhr morgens sehe, frage ich mich: „Ist das normal? Ist 142K hoch? Sollte es bei 142K oder bei 100K kompaktiert werden? Hängt das mit dem Fehler zusammen, den ich untersuche?“
Die Standardlogs setzen voraus, dass Sie ein perfektes Wissen über das System haben. Debugging in der Produktion geschieht, wenn Sie unvollständige Kenntnisse haben und vermutlich gestresst sind.
Was ich jetzt protokolliere
Ich habe meine Protokollierung um ein Prinzip herum strukturiert: Jeder Logeintrag sollte mir helfen, „Was ist passiert und warum?“ zu beantworten, ohne ein anderes System ansehen zu müssen.
API-Calls: Verwendetes Modell, Anzahl der Eingabetokens, Anzahl der Ausgabetokens, Antwortzeit, Status (Erfolg/Fehler), Fehlernachricht falls vorhanden. Eine Zeile pro Aufruf. Das sagt mir sofort, ob die API langsam, fehlgeschlagen oder teuer ist.
Toolausführungen: Name des Tools, Zusammenfassung der Eingaben, Zusammenfassung der Ausgaben, Dauer, Erfolg/Misserfolg. Wenn ein Tool fehlschlägt, kann ich genau sehen, was versucht wurde und was schiefgelaufen ist, ohne in den Rohdaten wühlen zu müssen.
Sessionsaktivität: Sitzungsbeginn, signifikante Ereignisse (Nachricht neuer Benutzer, Toolaufruf, Kontextkompaktierung), Sitzungsende. Das gibt mir eine Zeitleiste dessen, was in jeder Sitzung passiert ist.
Fehler: Vollständige Fehlermeldung, Stack-Trace, relevanter Kontext (Session-ID, Benutzeranfrage, kürzliche Aktivitäten). Der Kontext ist entscheidend – ein Fehler ohne Kontext sagt Ihnen, dass etwas kaputt gegangen ist, aber nicht warum.
Was ich aufgehört habe zu protokollieren: Routine-Herzschläge („still alive“-Nachrichten alle 30 Sekunden), erfolgreiche Gesundheitsprüfungen, interne Statusübergänge, die normal und erwartet sind. Diese erzeugten Volumen, ohne Informationen hinzuzufügen.
Logging-Ebenen, die Sinn machen
Die meisten Protokollierungs-Frameworks bieten die Ebenen DEBUG, INFO, WARN, ERROR. Ich verwende sie so:
ERROR: Etwas ist fehlgeschlagen und benötigt menschliche Aufmerksamkeit. Ich lese jeden ERROR-Log. Wenn ich mehr als 5 ERROR-Einträge pro Tag bei normalem Betrieb erhalte, sind meine Schwellenwerte falsch.
WARN: Etwas Ungewöhnliches ist passiert, aber das System hat es gehandhabt. Durchsatzgrenze erreicht und zurückgerollt, Kontextkompaktierung ausgelöst, erneuter Versuch nach Fehler erfolgreich. Ich überprüfe die WARN-Einträge täglich, um Muster zu erkennen.
INFO: Normale Operationen, die ich möglicherweise nachverfolgen möchte. API-Aufrufe, Toolausführungen, Sitzungsereignisse. Ich lese sie nur, wenn ich ein spezifisches Problem debugge.
DEBUG: Detaillierter interner Zustand für tiefgreifendes Debugging. Eingabe/Ausgabe jeder Funktion, Speicherauslastung, Status des Verbindungspools. In der Produktion deaktiviert, es sei denn, ich untersuche einen spezifischen Bug.
Der Schlüssel: In der Produktion arbeite ich auf dem INFO-Niveau. Das gibt mir genügend Details, um die meisten Probleme zu diagnostizieren, ohne das DEBUG-Geräusch. Ich wechsle vorübergehend zu DEBUG, wenn ich spezifische Probleme untersuche, und kehre dann zu INFO zurück.
Strukturierte Protokollierung
Rohtextprotokolle sind schwer zu durchsuchen und unmöglich zu aggregieren. Ich habe auf strukturierte Protokollierung in JSON umgestellt:
Statt: 2024-03-15 14:23:45 ERROR API-Call fehlgeschlagen: Timeout nach 30s
Protokolliere ich: ein JSON-Objekt mit Zeitstempel, Level, Ereignistyp, Modell, Fehler, Dauer, Session-ID und Request-ID.
Das JSON-Format ermöglicht mir:
– Nach jedem beliebigen Feld zu suchen (alle Fehler für die Session X, alle Timeouts für das Modell Y)
– Metriken zu aggregieren (Durchschnittsantwortzeit pro Modell pro Stunde)
– Dashboards zu erstellen (Grafana kann JSON-Logs direkt lesen)
– Ereignisse zu korrelieren (eine Anfrage vom Eingang bis zur Antwort verfolgen)
Der Kompromiss: JSON-Logs sind weniger lesbar für Menschen, wenn Sie die Logdatei kürzen. Ich benutze ein Logvisualisierungs-Tool, das JSON schön formatiert für die Echtzeitüberwachung.
Protokollrotation und -aufbewahrung
Logs von KI-Agenten wachsen schnell. Eine moderat aktive OpenClaw-Instanz erzeugt 50 bis 200 MB Logs pro Tag auf INFO-Ebene. Ohne Rotation füllt Ihr Speicherplatz sich innerhalb weniger Wochen.
Meine Aufbewahrungspolitik:
– Letzte 7 Tage: vollständige Logs (INFO-Level), unkomprimiert für schnellen Zugriff
– Tage 8-30: komprimierte Logs (gzipped, etwa 10-fache Reduzierung der Größe)
– Tage 31-90: nur ERROR- und WARN-Einträge (aus den vollständigen Logs extrahiert vor der Löschung)
– Über 90 Tage: nur aggregierte monatliche Metriken (keine Rohprotokolle)
Das hält meinen gesamten Log-Speicher unter 5 GB, während genügend Historie für Trendanalysen und Vorfalluntersuchungen erhalten bleibt.
Der Debugging-Workflow
Wenn etwas kaputt geht, folge ich dieser Sequenz:
1. Die letzten 10 ERROR-Einträge überprüfen – zeigt normalerweise die unmittelbare Ursache
2. Den gleichen Fehlertyp in der vorhergehenden Woche suchen – handelt es sich um ein wiederkehrendes Problem oder um einen Einzelfall?
3. Die Zeitleiste um den Fehler herum ansehen – was ist in den 60 Sekunden vor dem Fehler passiert?
4. Korrelationen überprüfen – hat der Fehler mit einem Deployment, einer Konfigurationsänderung oder einem Ausfall eines externen Dienstes zusammengefallen?
Dieser systematische Ansatz, kombiniert mit guter Protokollierung, löst die meisten Probleme in 10 bis 15 Minuten. Vor der strukturierten Protokollierung benötigten die gleichen Probleme 30 bis 60 Minuten, da die Schritte 3 und 4 eine manuelle Archäologie der Logdateien erforderte.
🕒 Published: