Osservabilità: trace, log e dataset di conversazioni

Quando una feature LLM sbaglia, la domanda non è “cosa ha detto il modello?”. La domanda è: quale template, con quali variabili, quale modello, quali parametri, quali tool, quale contesto e quale fallback hanno prodotto quell’output?

Senza osservabilità, ogni errore diventa un aneddoto. Qualcuno incolla una risposta strana in chat, il team prova a riprodurla, ma mancano prompt version, input originale, tool call, latenza, costo e output validato.

Perché questa lezione conta

Le feature LLM hanno più fonti di variabilità rispetto al codice deterministico: input naturale, contesto recuperato, sampling, modello, tool, output strutturato, fallback. Se non tracci questi elementi, non puoi fare debug, evaluation o governance.

Osservabilità non significa salvare tutto. Salvare tutto è spesso pericoloso: prompt e output possono contenere dati personali, segreti, codice proprietario o informazioni sensibili. Devi osservare abbastanza da spiegare il comportamento, ma non così tanto da creare un archivio rischioso.

Obiettivo operativo

Alla fine della lezione devi saper definire una traccia minima per una chiamata LLM, decidere quali campi loggare o redigere e trasformare casi reali in dataset di regressione.

Trace minimo

Una trace utile contiene:

{
  "trace_id": "req_123",
  "feature": "classify_ticket",
  "prompt_version": "v2.1",
  "schema_version": "v1",
  "model": "model-class-or-name",
  "temperature": 0,
  "input_size_tokens": 1840,
  "output_size_tokens": 210,
  "latency_ms": 1420,
  "estimated_cost": 0.013,
  "outcome": "ok",
  "fallback_used": false,
  "tool_calls": 0
}

Questi dati non bastano a ricostruire ogni dettaglio, ma bastano per rispondere a molte domande operative: quale versione costa di più, quale modello fallisce, quale feature genera output non valido, quale fallback si attiva spesso.

Prompt renderizzato: sì o no?

Salvare il prompt completo è comodo per il debug, ma rischioso. Una soluzione più sicura è salvare livelli diversi:

Sempre salvabile. Versione template, hash del prompt renderizzato, dimensione token, outcome, costo, latenza.

Salvabile con redazione. Prompt renderizzato con PII, segreti e contenuti sensibili mascherati.

Salvabile solo in ambienti controllati. Campioni completi per debug temporaneo, con retention breve e accesso limitato.

Da non salvare. Segreti, token, documenti riservati, dati personali non necessari, payload non autorizzati.

L’hash è utile: permette di sapere se due richieste erano uguali senza salvare tutto il testo.

Tool call

Quando ci sono tool, logga almeno:

1. nome tool;
2. versione schema;
3. parametri redatti;
4. esito;
5. errore normalizzato;
6. durata;
7. side effect prodotto;
8. conferma umana se presente.

Non serve salvare ogni byte della risposta del tool. Serve capire quale azione è stata tentata e con quale risultato.

Outcome applicativo

Un output tecnicamente valido può essere sbagliato per l’utente. Per questo il trace deve collegarsi all’outcome della feature:

1. JSON valido o non valido;
2. accettato o modificato dall’utente;
3. escalation a umano;
4. feedback esplicito;
5. azione completata;
6. rollback;
7. errore di policy.

Se misuri solo “la chiamata API è andata a buon fine”, stai osservando infrastruttura, non qualità.

Sampling e retention

Non tutte le conversazioni vanno salvate allo stesso livello. Puoi applicare sampling:

1. 100% delle metriche tecniche aggregate;
2. 100% degli errori e fallback;
3. percentuale bassa dei successi;
4. campioni completi solo con redazione;
5. retention breve per dati dettagliati;
6. retention lunga per metriche aggregate.

La retention deve essere una scelta esplicita. I log LLM tendono a diventare dataset ombra se nessuno decide quando eliminarli.

Da errore reale a eval case

Ogni errore importante dovrebbe produrre un caso di valutazione:

trace_id: req_123
problema: classificato come billing, doveva essere security
input redatto: ...
prompt_version: v2.1
atteso:
  category: security
  needs_human_review: true
regressione: blocca release se fallisce

Così gli incidenti smettono di essere discussioni e diventano protezione contro regressioni future.

Laboratorio guidato

Scegli una feature LLM reale o plausibile. Disegna il percorso:

input -> redazione -> template -> modello -> tool -> validazione -> output -> feedback

Per ogni step decidi:

1. evento da loggare;
2. campi salvabili;
3. campi da redigere;
4. campi da non salvare;
5. retention;
6. metrica collegata.

Poi prendi tre casi problematici e trasformali in eval case.

Output atteso

Devi produrre uno schema di osservabilità:

event | campi | redazione | retention | accesso | uso in eval

Lo schema deve permettere a un collega di sapere cosa viene raccolto, perché e con quali limiti.

Errori comuni

Loggare tutto per comodità. Aumenta rischio privacy e rende i log difficili da usare.

Non loggare prompt version. Senza versione, un errore non è riproducibile.

Separare log ed eval. Gli errori reali devono alimentare il dataset di regressione.

Ignorare feedback utente. La qualità percepita non si vede solo da schema valido e HTTP 200.

Checklist di verifica

• ogni chiamata ha trace_id;
• prompt version, modello, costo e latenza sono tracciati;
• i campi sensibili sono redatti o esclusi;
• errori e fallback entrano in eval;
• retention e accesso ai log sono dichiarati.

Collegamenti

• Modulo: Prompt in produzione e governance — questa lezione è la numero 37 del corso.
• Si collega alle lezioni 29, 30 e 38 su dati sensibili, budget e rollout.