Workflow Ledger

Das Nachverfolgungsregister für Workflows speichert dauerhaften Zustand für lange Automatisierungen. Es beantwortet operative Fragen, die ein Konsolenlog nicht zuverlässig beantworten kann:

• Welche Ausführung ist aktiv?
• Welche Items sind queued, running, completed, skipped, retry-ready, cancelled, failed oder dead?
• Welches Item hat eine abgelaufene Lease?
• Welche Events führten zum aktuellen Zustand?
• Welches Queue-Item ist mit diesem Workflow-Item verbunden?
• Kann ein Item erneut versucht, neu eingereiht, abgebrochen oder in die Fehlerwarteschlange verschoben werden?

Ledger-Konzepte

Konzept	Bedeutung
Run	Eine Ausführung eines Workflows mit Status, Quelle, Zeitstempeln, Metadaten und Fehlerzustand
Item	Dauerhafte Arbeitseinheit, etwa Portal, URL, Dokument oder Datensatz
Stage	Workflow-Schritt des Items, etwa discovery, fetch, parse oder review
State	Zustand des Items innerhalb der Stage, etwa queued, running, completed, retry-ready, dead oder cancelled
Event	Nur anhängbarer Verlaufseintrag, der erklärt, was mit Run oder Item passiert ist
Verknüpfte Ausgabe	Ausgabe oder verknüpfter Nachweis, etwa Snapshot, Listing, Datei oder Suchdokument
Lease	Reservierung eines Workers, die ein Item bis zu einer Frist als laufend markiert

States und Stages sind durch den Workflow definierte Zeichenketten. Guida bleibt generisch, während jeder Workflow eigene Präsentationsmetadaten liefern kann.

Workflow-Ledger-Panel

Das Panel im Hauptfenster ist eine kompakte Status- und Startoberfläche. Es zeigt Ausführungszähler, Item-Zähler, Aufmerksamkeitspunkte und eine kurze Liste von Runs.

Workflow Ledger Console

Die Workflow Ledger Console ist die eigentliche Betreiberoberfläche. Sie läuft in einem eigenen Fenster und zeigt Runs, Items der ausgewählten Ausführung, Item-Details, Events, verknüpfte Ausgaben, Metadaten, Wiederherstellungszustand sowie Graph-/Debugging-Ansichten.

Nutzen Sie sie, um:

• Runs zu verwalten und Zustand der ausgewählten Ausführung zu prüfen
• Items nach Text und operativem Zustand zu filtern
• große Item-Mengen serverseitig zu paginieren
• Stage/State-Zählungen über die ganze Ausführung zu lesen
• Items erneut versuchbar zu markieren, abzubrechen oder in Fehlerwarteschlangen zu verschieben
• Item-IDs, Schlüssel, Versuche, Lease-Zustand, Fehler und Metadaten zu prüfen
• Events und verknüpfte Ausgaben als Timeline zu lesen
• zu prüfen, ob ein Ledger-Item genug Queue-Metadaten für Requeue enthält

Große Ausführungen

Die Konsole ist für Runs mit tausenden Items ausgelegt. Die Item-Liste ist serverseitig paginiert; Zusammenfassungen und Stage/State-Matrizen kommen aus aggregierten Repository-Abfragen über die gesamte ausgewählte Ausführung.

Das ist wichtig: Virtualisierung kontrolliert nur Rendering, während Pagination und Aggregate Korrektheit und Datenbanklast kontrollieren.

Retry-Vokabular

Guida trennt dauerhaften Ledger-Zustand von ausführbarer Queue-Arbeit:

• Mark Retry Ready ändert Ledger-Zustand, sodass Workflow-Logik das Item wieder claimen kann. Es erzeugt keine Queue-Arbeit.
• Requeue and Retry erzeugt ausführbare Queue-Arbeit, wenn das Ledger-Item gespeicherte Queue-Metadaten hat, und setzt das Ledger-Item zurück in einen claimable Zustand.

Fehlen Queue-Metadaten, soll Guida eine klare Meldung zeigen. Üblicherweise muss das Item durch den Quellprozess neu erzeugt oder korrigiert neu eingereiht werden.

Queue-Verknüpfung

Queue-Items können einen Workflow-Umschlag enthalten:

{
  "workflow": {
    "workflowName": "careers-crawl",
    "runId": "abc123",
    "itemId": "def456",
    "itemKey": "portal:example"
  }
}

Wenn diese Metadaten vorhanden sind, kann die Queue Console das verwandte Ledger-Item öffnen, und die Workflow Ledger Console kann erklären, ob ausführbare Queue-Arbeit existiert.

Präsentationsmetadaten

Workflows können mit workflow-ledger.display.json neben workflow-ledger.schema.json definieren, wie Items dargestellt werden. Diese Regeln wählen Labels, Untertitel und Kontextfelder aus Item-Feldern oder Metadaten, ohne eine domänenspezifische UI in Guida einzubauen.

Rohschlüssel, Item-ID, Run-ID, Metadaten, Events und verknüpfte Ausgaben bleiben in Details und Kopieraktionen verfügbar.

Aufmerksamkeit und Wiederherstellung

Die Konsole zeigt Aufmerksamkeitspunkte für die ausgewählte Ausführung:

• abgelaufene Leases
• retry-ready Items
• dead oder failed Items
• Queue-Verknüpfungsprobleme
• Items, die nicht automatisch requeued werden können

Ausführungsübergreifende Aufmerksamkeit gehört in Run-Management-Ansichten. Die Arbeit an einer ausgewählten Ausführung bleibt auf diese Ausführung begrenzt.

Reconciliation

Workflow-Ledger-Werkzeuge und die Betriebsdashboard-API liefern kompakte Reconciliation-Zusammenfassungen für eine Ausführung, etwa für Handoffs von Fetch zu Parse. Sie helfen bei der Frage: “Wo ist die Arbeit geblieben?”

Für große Crawling-Arbeitsbereiche verwenden Sie die Workflow Control Console, um Ledger-Stages, Queues, Module und Handoffs zu Operationen zu gruppieren. Nutzen Sie die Workflow Ledger Console, wenn Sie die detaillierte Item-Wahrheit hinter einer Operatorkachel brauchen.

Nächste Schritte

• Warteschlangen und Prüfung - ausführbare Queue-Arbeit betreiben
• Warteschlangen-Worker - queue-gestützte Worker ausführen
• Workflows - Operationen, Karten, Module und Handoffs modellieren
• Betriebsdashboard-API - Runs, Queues, Worker, Fehler und Reconciliation überwachen