Leggere l'esito di una run

Ogni esecuzione produce un report: è il risultato vero della run, e tutto ciò che l'app mostra — il badge nella lista, i colori e i contatori sui nodi — viene da lì. Lo schema completo è nella scheda del report di run; qui c'è ciò che serve per leggerlo.

I tre stati

Stato	Cosa significa	Cosa fare
success	la run è arrivata in fondo senza scarti né errori	niente
partial	la run è arrivata in fondo, ma alcuni record sono stati scartati o catturati	guardare quanti e perché, e recuperarli dallo scarto
failed	la run si è fermata	leggere l'errore e il nodo che l'ha causato

partial non è un fallimento: i record validi sono stati scritti. Da riga di comando infatti esce con codice 0, come success; solo failed esce con un codice diverso.

I numeri

Campo	Cosa conta
extracted	i record letti dalle sorgenti
written	i record scritti dai sink. Se lo stesso record va su due sink, conta due volte
rejected	i record finiti in uno scarto, su tutti i nodi
rejectedReasons	gli stessi scarti, divisi per motivo
caught	sui nodi try-catch: gli errori catturati e deviati sul ramo di gestione

Gli stessi contatori esistono per ogni nodo, insieme ai tempi di attraversamento: è così che nell'app si vede dove si sono persi i record e quale nodo è il collo di bottiglia. Anche una run failed conserva il grafo e i conteggi raggiunti prima di fermarsi, quindi il punto in cui si è interrotta si vede.

Dove finiscono i record scartati

Un record che fallisce segue uno di tre percorsi, decisi quando il processo è stato scritto:

Percorso	Dove si vede nel grafo	Effetto sulla run
Dead-letter	ramo rosso tratteggiato dal nodo	il record va nello scarto, la run prosegue: partial
Ramo catch	ramo ambra che parte da un nodo try-catch	il record passa dai nodi del ramo, la run prosegue: partial
Fail-fast	nessun ramo	la run si ferma: failed

Un errore che non dipende dai dati ma dal codice (un bug) ferma sempre la run, anche sotto un try-catch: un bug va visto, non scaricato in uno scarto. I tre percorsi si vedono in azione nel grafo interattivo.

Il report non contiene dati

Il report porta solo conteggi e motivi, mai il contenuto dei record né credenziali: si può archiviare e condividere senza rischi. I record scartati completi stanno nello scarto del processo — una tabella, un file, una coda — indicato nella scheda della pipeline.

Da riga di comando

Ogni run eseguita da riga di comando lascia il suo report in locale, consultabile senza app e senza rete:

pnpm run etl runs list                               # le ultime run
pnpm run etl runs list --pipeline langfuse-sessions-daily --limit 5
pnpm run etl runs show <runId>                        # basta un prefisso non ambiguo
pnpm run etl runs show <runId> --json | jq '.status, .written'

Quando qualcosa non torna

• Run failed. Il report indica tipo e messaggio dell'errore e il nodo che ha fallito. Parti da quel nodo nel grafo e dal runbook della pipeline, se esiste.
• Tanti scarti. rejectedReasons dice il motivo prevalente; i record completi sono nello scarto indicato nella scheda della pipeline.
• Il processo non compare nella lista. Il server ETL va riavviato dopo che un processo nuovo è stato approvato: vedi L'app desktop.