Sechs Monate OpenClaw-Protokolle. Das war, was ich hatte, als ich endlich anfing herauszufinden, warum einige Debugging-Sitzungen 5 Minuten und andere 2 Stunden dauerten. Die Antwort war im Rückblick offensichtlich: Protokollierung.
Es ging nicht darum, ob ich Protokolle hatte – ich hatte immer Protokolle. Das Problem war, dass die Hälfte meiner Protokolle nutzloser Lärm war („Prozess gestartet… Prozess läuft… Prozess läuft immer noch…“) und die andere Hälfte die Informationen fehlte, die ich tatsächlich benötigte, wenn etwas schiefging.
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 entworfen, die genau wissen, was alles bedeutet. Wenn der Entwickler „Kontextkompaktierung wurde bei 142K Zeichen ausgelöst“ sieht, weiß er genau, was das bedeutet und was als Nächstes zu überprüfen ist. Wenn ich das um 3 Uhr morgens sehe, denke ich „Ist das normal? Ist 142K hoch? Sollte es sich bei 142K oder bei 100K kompaktiert haben? Hat das mit dem Fehler zu tun, den ich untersuche?“
Standardprotokolle gehen davon aus, dass du perfektes Wissen über das System hast. Debugging in der Produktion erfolgt, wenn du unvollkommenes Wissen hast und wahrscheinlich gestresst bist.
Was ich jetzt protokolliere
Ich habe meine Protokollierung nach einem Prinzip umstrukturiert: Jeder Protokolleintrag sollte mir helfen, „Was ist passiert und warum?“ zu beantworten, ohne in ein anderes System schauen zu müssen.
API-Aufrufe: Verwendetes Modell, Anzahl der Eingabetoken, Anzahl der Ausgabetoken, Antwortzeit, Status (Erfolg/Fehler), Fehlermeldung, falls vorhanden. Eine Zeile pro Aufruf. Das sagt mir sofort, ob die API langsam, fehlerhaft oder teuer ist.
Toolausführungen: Tool-Name, Eingabezusammenfassung, Ausgabezusammenfassung, Dauer, Erfolg/Misserfolg. Wenn ein Tool fehlschlägt, kann ich genau sehen, was versucht wurde und was schiefgelaufen ist, ohne durch rohe Ausgaben graben zu müssen.
Sitzungsaktivität: Sitzungsstart, signifikante Ereignisse (neue Benutzer-Nachricht, Toolaufruf, Kontextkompaktierung), Sitzungsende. Das gibt mir einen Zeitrahmen, was in jeder Sitzung passiert ist.
Fehler: Vollständige Fehlermeldung, Stack-Trace, relevanter Kontext (Sitzungs-ID, Benutzeranfrage, kürzliche Aktivitäten). Der Kontext ist entscheidend – ein Fehler ohne Kontext sagt dir, dass etwas kaputt ist, aber nicht warum.
Was ich nicht mehr protokolliere: Routine-Herzschläge („noch aktiv“-Nachrichten alle 30 Sekunden), erfolgreiche Gesundheitsprüfungen, interne Statusübergänge, die normal und zu erwarten sind. Diese erhöhten das Volumen, ohne Informationen hinzuzufügen.
Log-Level, die Sinn machen
Die meisten Protokollierungsframeworks bieten DEBUG-, INFO-, WARN-, ERROR-Levels an. Ich verwende sie wie folgt:
ERROR: Etwas ist fehlgeschlagen und benötigt menschliche Aufmerksamkeit. Ich lese jedes ERROR-Protokoll. Wenn ich in einem normalen Betrieb mehr als 5 ERROR-Einträge pro Tag erhalte, sind meine Schwellenwerte falsch.
WARN: Etwas Ungewöhnliches ist passiert, aber das System hat damit umgegangen. Rate Limiting erreicht und zurückgegangen, Kontextkompaktierung ausgelöst, erneuter Versuch nach einem Fehler erfolgreich. Ich überprüfe WARN-Einträge täglich, um Muster zu erkennen.
INFO: Normale Operationen, die ich nachverfolgen möchte. API-Aufrufe, Toolausführungen, Sitzungsereignisse. Ich lese diese nur, wenn ich ein spezifisches Problem debugge.
DEBUG: Detaillierter interner Zustand für tiefes Debugging. Eingabe/Ausgabe jeder Funktion, Speicherzuweisung, Status des Verbindungspools. In der Produktion deaktiviert, es sei denn, ich untersuche einen bestimmten Fehler.
Der Schlüssel: In der Produktion laufe ich auf INFO-Level. Das gibt mir genügend Details, um die meisten Probleme ohne den Lärm von DEBUG zu diagnostizieren. Ich wechsle vorübergehend zu DEBUG, wenn ich spezifische Probleme untersuche, und wechsle dann zurück.
Strukturierte Protokollierung
Einfacher Textprotokolle sind schwer zu durchsuchen und unmöglich zu aggregieren. Ich habe auf JSON-strukturierte Protokollierung umgestellt:
Anstatt: 2024-03-15 14:23:45 ERROR API-Aufruf fehlgeschlagen: Timeout nach 30s
Protokolliere ich: ein JSON-Objekt mit Zeitstempel, Level, Ereignistyp, Modell, Fehler, Dauer, Sitzungs-ID und Anfrage-ID.
Das JSON-Format ermöglicht mir:
– Nach beliebigem Feld zu suchen (alle Fehler für Sitzung X, alle Timeouts für Modell Y)
– Metriken zu aggregieren (durchschnittliche Antwortzeit pro Modell und Stunde)
– Dashboards zu erstellen (Grafana kann JSON-Protokolle direkt lesen)
– Ereignisse zu korrelieren (eine Anfrage von der Ankunft über die Verarbeitung bis zur Antwort nachzuvollziehen)
Der Kompromiss: JSON-Protokolle sind weniger menschenlesbar, wenn du die Protokolldatei überwacht. Ich verwende ein Protokollanzeigetool, das JSON schön formatiert für die Echtzeitüberwachung.
Protokollrotation und -aufbewahrung
Protokolle von KI-Agenten wachsen schnell. Eine mäßig aktive OpenClaw-Instanz erzeugt 50-200MB Protokolle pro Tag auf INFO-Level. Ohne Rotation füllt sich deine Festplatte in wenigen Wochen.
Mein Aufbewahrungsrichtlinie:
– Letzte 7 Tage: vollständige Protokolle (INFO-Level), unkomprimiert für schnellen Zugriff
– Tage 8-30: komprimierte Protokolle (gzipped, etwa 10x Größenreduktion)
– Tage 31-90: nur ERROR- und WARN-Einträge (aus vollständigen Protokollen vor der Löschung extrahiert)
– Über 90 Tage hinaus: nur monatliche aggregierte Metriken (keine Rohprotokolle)
Das hält meinen gesamten Protokollspeicher unter 5GB und bewahrt gleichzeitig genügend Verlauf für Trendanalysen und Vorfalluntersuchungen.
Der Debugging-Workflow
Wenn etwas kaputt geht, folge ich dieser Reihenfolge:
1. Überprüfe die letzten 10 ERROR-Einträge – meistens zeigt es die unmittelbare Ursache
2. Suche nach dem gleichen Fehlertyp in der vergangenen Woche – ist das ein wiederkehrendes Problem oder ein Einzelfall?
3. Schau dir die Zeitleiste rund um den Fehler an – was ist in den 60 Sekunden vor dem Fehler passiert?
4. Überprüfe korrelierende Ereignisse – fiel der Fehler mit einem Deployment, einer Konfigurationsänderung oder einem Ausfall eines externen Dienstes zusammen?
Dieser systematische Ansatz, kombiniert mit guter Protokollierung, löst die meisten Probleme in 10-15 Minuten. Vor der strukturierten Protokollierung benötigten die gleichen Probleme 30-60 Minuten, da Schritt 3 und 4 manuelle Protokolldatei-Archäologie erforderten.
🕒 Published: