🛰 TRANSIT Error Intelligence Center ORCH-T111

📖 Cos'è Telemetry e perché l'abbiamo costruita

Telemetry, detto in una riga, è l'insieme degli strumenti che intercettano cosa fa il codice in produzione, in tempo reale, senza fermarlo. Non è un tool, è un livello dell'infrastruttura: una pipeline che parte dall'applicazione (PYBOT su VIPER), passa da un collector (OTel Collector), atterra su un backend di storage (Supabase schema telemetry), e viene visualizzata da strumenti come Grafana o questa pagina stessa.

Nel contesto GEKO l'abbiamo costruita con un obiettivo specifico: smettere di osservare TRANSIT solo quando qualcosa si è già rotto. Prima — e in parte ancora oggi — la conoscenza dei problemi arrivava "per incidente": un autista segnalava un comando che non rispondeva, tu aprivi i log del container in SSH, grep-pavi a mano, e nel 60% dei casi i log erano già stati ruotati. L'informazione dopo l'evento non basta più, perché TRANSIT è sul sentiero per diventare un prodotto verticale vendibile, e un prodotto vendibile deve avere osservabilità industriale, non artigianale.

🔍 Come si legge un errore con Telemetry Phase 2

La sequenza operativa che stiamo costruendo è questa. Un autista ti scrive "il briefing ZTL non è arrivato". Tu apri questa pagina. Prima cosa: guardi il KPI Errori 24h — se è salito rispetto a ieri, c'è qualcosa di nuovo. Seconda cosa: il tile Top Exception Classes: ti dice quale tipo di errore sta dominando. Terza cosa: Dove intervenire ti ranka gli handler dal più rotto al più stabile. A quel punto sai già, con molta probabilità, su quale file di codice mettere le mani. Se serve il dettaglio puntuale dell'evento specifico dell'autista, chiedi il trace_id (che la Phase 2 propagherà nei messaggi di fallback) e con quello apri Grafana Explore → filtro su traces_raw WHERE trace_id = 'abc123' → vedi l'intera timeline della richiesta: ingresso webhook, span del router, eccezione con stack trace, output finale. Quello che oggi richiede 20 minuti di grep su log di container diventa 10 secondi di query.

🧬 Il vocabolario minimo

Metrica — un numero che aggreghi nel tempo. Esempi: worker_memory_mb=144, errors_total=37. Basso costo, perfetto per dashboard e alerting, ma perde informazione: un counter di 37 errori non ti dice cosa sono.

Traccia (span) — il racconto di una singola richiesta attraverso il codice. Ingresso → funzioni chiamate → eccezioni → uscita. Porta molto contesto (parametri, exception class, stack trace) ma costa di più: non la aggreghi, la peschi on-demand con il trace_id.

Log — evento narrativo strutturato con livello (ERROR/WARN/INFO) e messaggio. La Phase 2 li correla automaticamente al trace_id della richiesta che li ha generati. Senza questo link, i log restano isola.

La regola d'oro del debug con Telemetry: parti dal counter (cosa sta aumentando?), scendi al trace (cosa è successo in quella richiesta?), leggi i log correlati (qual è il contesto narrativo?), quindi patcha il codice. Non al contrario.

🏷 Cardinalità — perché non basta "logga tutto"

Ogni label su una metrica moltiplica lo storage. Se metti user_id come label, con 50 autisti già moltiplichi per 50 ogni conteggio. Se metti trace_id esplodi. Per questo il nostro design separa le label basso-cardinality (handler, exception_class, user_role) che vanno sulle metriche aggregate, dalle dimensioni alto-cardinality (trace_id, message_id, driver_code) che vanno su traces e logs come attributi per la ricerca puntuale. È una scelta architetturale: il costo di storage di Supabase cresce linearmente con le righe, e la tabella metrics_raw oggi colleziona già ~119 campioni all'ora solo con le 4 metriche runtime.