Registro di tracciabilità dei flussi di lavoro

Il registro di tracciabilità dei flussi di lavoro conserva dati persistenti per flussi di lavoro di automazione di lunga durata. Risponde a domande operative a cui un log di console non può rispondere in modo affidabile:

• Quale esecuzione è attiva?
• Quali elementi sono in coda, in esecuzione, completati, saltati, pronti per un nuovo tentativo, annullati, falliti o morti?
• Quale elemento ha una presa in carico scaduta?
• Quale cronologia di eventi ha portato alla situazione corrente?
• Quale elemento di coda è collegato a questo elemento del flusso di lavoro?
• Questo elemento può essere riprovato, rimesso in coda, annullato o spostato nella coda degli scarti?

Concetti del registro

Concetto	Significato
Esecuzione	Una esecuzione di un flusso di lavoro, con stato, origine, timestamp di inizio/fine, metadati e stato di errore
Elemento	Un’unità persistente di lavoro del flusso di lavoro, come un portale, URL, documento o record
Fase	Il passaggio del flusso di lavoro a cui appartiene l’elemento, come discovery, fetch, parse o review
Stato	Lo stato dell’elemento all’interno della fase, come queued, running, completed, retry-ready, dead o cancelled
Evento	Una voce di cronologia append-only che spiega cosa è successo a un’esecuzione o a un elemento
Risultato collegato	Un file, risultato o riferimento di tracciamento collegato, come istantanea, elenco o documento di ricerca
Presa in carico	L’assegnazione a un processo di lavoro che marca l’elemento come in esecuzione fino a una scadenza

Stati e fasi sono stringhe definite dal flusso di lavoro, non concetti fissi del prodotto. Il registro è abbastanza generico per molti flussi di lavoro, mentre ogni flusso può fornire metadati di visualizzazione per rendere leggibili gli elementi.

Pannello del registro di tracciabilità

Il pannello del registro di tracciabilità nella finestra principale è una vista compatta per controllo rapido e avvio. Mostra conteggi di esecuzioni, conteggi di elementi, conteggi che richiedono attenzione e un breve elenco di esecuzioni.

Il pannello è volutamente leggero. Usalo per una verifica rapida e per aprire la console completa.

Console del registro di tracciabilità

La console del registro di tracciabilità è l’interfaccia operativa principale. Si apre in una finestra separata e usa pannelli dedicati per esecuzioni, elementi dell’esecuzione selezionata, dettagli elemento, eventi, risultati collegati, metadati, ripristino e viste grafo/debug.

La console serve alla gestione seria delle esecuzioni e al ripristino degli elementi, non solo all’osservazione dei log.

Usala per:

• Gestire esecuzioni e ispezionare lo stato dell’esecuzione selezionata.
• Cercare e filtrare elementi per testo e condizione operativa.
• Sfogliare grandi insiemi di elementi senza caricare un’intera esecuzione nell’interfaccia.
• Leggere conteggi fase/stato calcolati sull’intera esecuzione selezionata, non solo sulla pagina di elementi visibile.
• Selezionare uno o più elementi per nuovo tentativo, annullamento, coda degli scarti o ripristino in coda.
• Ispezionare dettagli elemento, ID grezzi, chiavi elemento, tentativi, informazioni sulla presa in carico, errori e metadati.
• Seguire le timeline degli elementi attraverso eventi e risultati collegati.
• Vedere se un elemento del registro contiene abbastanza metadati di coda per essere rimesso in coda.
• Copiare dati dell’elemento, ID e dettagli diagnostici.

Grandi esecuzioni e paginazione

La console è progettata per esecuzioni con migliaia di elementi. Il pannello degli elementi usa paginazione lato server con dimensioni di pagina limitate, mentre riepiloghi e matrice fase/stato usano query aggregate del repository sull’intera esecuzione selezionata.

Questa distinzione conta: la virtualizzazione controlla solo la visualizzazione, mentre paginazione e aggregati controllano correttezza e carico sul database. Una pagina può mostrare 250 righe, ma totali dell’esecuzione, conteggi fase/stato, conteggi degli elementi pronti per un nuovo tentativo, conteggi delle prese in carico e riepiloghi di attenzione sono calcolati dal repository, che resta il riferimento autorevole.

Filtri rapidi come Problemi (Problems), Pronti per nuovo tentativo (Retry Ready), In esecuzione (Running), Presi in carico (Leased) e Terminali (Terminal) vengono applicati lato server all’elenco paginato degli elementi.

Vocabolario dei nuovi tentativi

Guida separa i dati persistenti del registro dal lavoro eseguibile in coda:

• Segna come pronto per nuovo tentativo (Mark Retry Ready) aggiorna l’elemento del registro così può essere preso in carico dalla logica del flusso di lavoro. Non crea lavoro in coda da solo.
• Rimetti in coda e riprova (Requeue and Retry) crea lavoro eseguibile in coda quando l’elemento del registro contiene metadati di coda registrati, poi riporta l’elemento del registro a una condizione idonea alla presa in carico.

Se mancano i metadati di coda, Guida dovrebbe mostrare un messaggio di ripristino chiaro per l’operatore. La correzione abituale è rigenerare l’elemento rieseguendo il processo di lavoro sorgente o mettendo in coda un elemento corretto, non indovinare il vecchio contenuto.

Collegamento alle code

Gli elementi di coda possono includere metadati di collegamento al flusso di lavoro:

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

Quando questi metadati sono presenti, la console delle code può aprire l’elemento di registro collegato, e la console del registro di tracciabilità può spiegare se esiste lavoro di coda eseguibile per un elemento.

Metadati di visualizzazione

I flussi di lavoro possono definire la presentazione degli elementi con workflow-ledger.display.json accanto a workflow-ledger.schema.json. Le regole di visualizzazione permettono a un flusso di scegliere etichette, sottotitoli e campi di contesto da campi o metadati degli elementi, senza incorporare nell’interfaccia di Guida logica specifica del dominio.

La chiave grezza dell’elemento, ID elemento, ID esecuzione, metadati, eventi e risultati collegati restano disponibili nei dettagli e nelle azioni di copia anche quando un flusso di lavoro fornisce etichette più leggibili.

Attenzione e ripristino

La console mette in evidenza elementi dell’esecuzione selezionata che richiedono attenzione, come:

• prese in carico scadute
• elementi pronti per un nuovo tentativo
• elementi morti o falliti
• problemi di collegamento alle code
• elementi che non possono essere rimessi automaticamente in coda

L’attenzione tra esecuzioni diverse appartiene alle viste di gestione esecuzioni. Il lavoro sull’esecuzione selezionata dovrebbe restare limitato a quell’esecuzione, così l’operatore non viene distratto da errori non correlati.

Riconciliazione delle esecuzioni

Gli strumenti MCP del registro di tracciabilità dei flussi di lavoro e l’API della dashboard operativa includono riepiloghi compatti di riconciliazione per un’esecuzione selezionata. Sono utili per controlli del flusso, per esempio il passaggio da fetch a parse:

• conteggi fetch elaborati, saltati, morti, pronti per nuovo tentativo, in esecuzione e presi in carico
• conteggi parse/index in coda e completati
• conteggi completi raggruppati per fase/stato

Questi riepiloghi servono alla diagnosi operativa e agli agenti remoti. Non sostituiscono la console, ma danno a script e client MCP un modo limitato per rispondere alla domanda: “dove è finito il lavoro?”

Per spazi di lavoro con molti flussi crawler, usa la Workflow Control Console per raggruppare fasi del registro, code, moduli e passaggi tra fasi in operazioni a livello di operatore. Usa la Workflow Ledger Console quando ti serve la verità dettagliata degli elementi dietro una riga dell’operazione.

Passi successivi

• Code e revisione — gestisci lavoro eseguibile in coda
• Processi di lavoro delle code — esegui processi di lavoro basati su code
• Workflow Control Console — modella operazioni, mappe dei flussi, moduli e passaggi tra fasi
• API della dashboard operativa — monitora conteggi esecuzione, code, processi di lavoro, errori, attenzione e riconciliazione tramite HTTP/SSE in sola lettura
• Flussi di lavoro — organizza l’automazione dello spazio di lavoro in cartelle di flusso