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. Sulla card di un nodo l'app li chiama così:

Sulla card	Cosa conta
Entrati	i record che il nodo ha ricevuto (extracted del nodo)
Usciti	i record che ha emesso a valle, o scritto se è un sink (written del nodo)
In errore	gli scartati del nodo più gli errori nati lì e catturati da un try-catch; un retry riuscito no

Durante la run, sui nodi che trattengono record (compresi quelli che aspettano un sistema esterno, e i sink con righe ancora da scrivere), c'è anche in lavorazione: quanti ne stanno tenendo in quel momento. A run conclusa vale zero e non compare, quindi riaprendo una run non c'è.

Entrati e usciti non vanno confrontati uno a uno: un filtro ne fa uscire meno senza errori, un nodo che espande un elenco ne fa uscire di più, un'aggregazione uno per gruppo. Anche una run failed conserva il grafo e i conteggi raggiunti prima di fermarsi, quindi il punto in cui si è interrotta si vede.

Nodi saltati

Un nodo può dover aspettare che un altro sia riuscito, per esempio lo scambio di due tabelle che parte solo dopo il caricamento. Se il nodo atteso non riesce, quello che aspettava è saltato: non è mai partito. Nel report ha skipped: { because }, dove because è l'id del nodo che l'ha fermato, e con lui sono saltati i nodi che ne dipendono. etl runs show lo scrive al posto della durata, come saltato (<id del nodo che l'ha fermato>). È saltato allo stesso modo un sink a cui non arriva nessun record perché un try-catch ha fermato un nodo a monte: non scrive niente.

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

Di norma il report porta solo conteggi e motivi, mai il contenuto dei record né credenziali. Fanno eccezione i nodi che dichiarano righe per record (recordReport): elencano i campi che la pipeline ha scelto, e la scheda della pipeline dice quali. Prima di condividere il report di una pipeline così, guarda la sua scheda. 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 <nome> --limit 5
pnpm run etl runs show <runId>                        # basta un prefisso non ambiguo
pnpm run etl runs show <runId> --json | jq '.status, .written'

Per vedere quali record sono passati da un nodo, e com'erano a ogni passaggio, si lancia una run tracciata: conserva il percorso dei primi record di ogni source, e dei record che ne derivano (aggregati, uscite di un join), accanto al report, in .runs/<runId>.trace.json.

pnpm run etl run <pipeline> --trace                    # primi 100 record di ogni source
pnpm run etl run <pipeline> --trace --trace-sample 10  # primi 10
pnpm run etl run <pipeline> --trace --trace-max-records 300  # al più 300 record in tutto
pnpm run etl run <pipeline> --trace --trace-max-errors 50    # al più 50 record in errore

I record tracciati, letti e derivati, hanno un tetto (default 1000). Quando la run lo raggiunge smette di aggiungerne e prosegue normalmente: la traccia è a campione esaurito, completa per i record che contiene ma non per tutti quelli che avrebbe seguito.

Dei record che vanno in errore fuori dal campione la traccia conserva il cammino, cioè i nodi da cui sono passati, e il valore che ha fatto fallire il nodo: sono quelli su cui si fa debug, e raramente sono fra i primi letti. Anche loro hanno un tetto (default 1000), oltre il quale la traccia lo segnala e non ne aggiunge altri.

Dall'app desktop si lancia con Esegui con tracciamento, e dal pannello di un nodo, o da un suo errore, se ne segue un record passaggio per passaggio (L'app desktop). etl runs list segna nella colonna TRACCIA le run che ne hanno ancora una, e quelle a campione esaurito.

La traccia contiene dati

A differenza del report, la traccia salva i valori dei record in chiaro, anche i dati personali. Si conservano solo le ultime 20 (per default, ETL_TRACES_KEEP), e non va condivisa come un report. Formato e regole: La traccia di una run.

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.