Worker und Queues
Dieses Kapitel beschreibt den Lebenszyklus der Worker und der Warteschlangen im Normalbetrieb, also wie eine Email durch Queue, Lock und Worker-Schleife wandert, wenn alles funktioniert. Die Fehlerpfade mit Retry-Logik, Idempotenz und Dead-Letter-Behandlung stehen im Kapitel Fehler und Resilienz.
Einer nach dem anderen: Queue-Verarbeitung
Die Zustandsmaschine beschreibt, welche Zustände eine Email durchlaufen kann. Aber wer sorgt dafür, dass die Übergänge tatsächlich stattfinden? Das ist die Aufgabe der Warteschlange (en: Queue) und des Workers, der sie abarbeitet.
Wichtig zur Abgrenzung: Queue-Status und Email-Status sind zwei getrennte Ebenen. Der Queue-Eintrag hat einen eigenen Lifecycle (pending, processing, done, failed, dead) und beschreibt den technischen Verarbeitungsdurchlauf. Dabei markiert failed einen technischen Fehlschlag eines Job-Retry, bevor nach Überschreiten der maximalen Wiederholungen dead erreicht ist. Die Email hat einen Fach-Status (fetched, parsed, … bis sent oder failed) und beschreibt den fachlichen Zustand der Email. Ein Queue-Eintrag im Status dead bedeutet nicht zwangsläufig, dass die Email failed ist; er bedeutet nur, dass für diesen Verarbeitungsschritt keine automatische Wiederholung mehr erfolgt. Siehe email-rag-ki-fehler-und-resilienz für den Email-Fachstatus.
Wie die Queue funktioniert
Die Queue ist eine Tabelle in MariaDB mit fünf möglichen Zuständen: pending, processing, done, failed und dead. Jeder Eintrag hat eine Priorität (critical, high, normal, low), einen Retry-Zähler und einen Zeitstempel.
Der Queue-Worker ist ein Daemon, ein dauerhaft laufender Prozess. Er holt sich den nächsten anstehenden Eintrag, wobei höhere Prioritäten zuerst bedient werden. Innerhalb derselben Priorität gilt: wer zuerst kam, wird zuerst verarbeitet.
Retry mit exponentiellem Backoff
Wenn die Verarbeitung einer Email fehlschlägt, wird sie nicht sofort verworfen. Das System nutzt exponentielles Backoff (en: Exponential Backoff): drei Versuche mit zunehmenden Wartezeiten.
- Erster Retry: nach 30 Sekunden
- Zweiter Retry: nach 120 Sekunden (2 Minuten)
- Dritter Retry: nach 600 Sekunden (10 Minuten)
Bei jedem fehlgeschlagenen Versuch wird der Retry-Zähler erhöht und der Status auf pending zurückgesetzt. Erst nach dem dritten Fehlversuch wechselt der Status auf dead. Diese Email wird nicht mehr automatisch verarbeitet, bleibt aber im System sichtbar.
Die Fehlerklassen
Der Worker unterscheidet drei Arten von Fehlern:
- Indexierungsfehler (Qdrant/Embedding nicht erreichbar): Die Email wird als
partially_indexedmarkiert, die Pipeline hat aber teilweise funktioniert. - LLM-Fehler (Timeout, ungültiges JSON, Parsing-Fehler): Die Email wird als
failedmarkiert und in die Retry-Queue gestellt. - Unerwartete Fehler: Alles andere wird ebenfalls als
failedbehandelt, mit dem Fehlertext im Audit-Log.
Jeder Fehler wird protokolliert: Fehlertyp, betroffene Email, Zeitpunkt. So lässt sich nachvollziehen, warum eine Email in der Dead-Letter-Queue gelandet ist und ob das Problem behoben werden kann.