Migliori pratiche di logging LLM: 9 regole che seguiamo in produzione [2026]

Migliori pratiche di logging LLM: 9 regole che seguiamo in produzione [2026]

Queste nove migliori pratiche di logging LLM sono le regole che il nostro stack di produzione segue davvero: registriamo 1,2 milioni di richieste LLM al mese su quattro servizi, e ognuna finisce in Grafana Loki come una singola riga JSON con model, tokens, latency, cost_usd e trace_id. structlog 25.4.0 scrive il record, Presidio rimuove prima i PII, e l'intera pipeline è la metà di logging del nostro stack di osservabilità.

Punti chiave

• Registra ogni richiesta LLM come JSON strutturato con almeno 14 campi nominati, mai come testo libero.
• Oscura i PII prima della scrittura del log con Presidio o equivalente, non dopo.
• Allega a ogni trace gli attributi delle convenzioni semantiche OpenTelemetry GenAI.
• Per 1 milione di richieste al giorno, gli stessi 60GB costano $108 al mese su Datadog, $30 su Loki, $1,20 su ClickHouse.

Cosa significa davvero fare logging LLM (e perché "registrare tutto" non funziona)

Fare logging LLM significa catturare un record strutturato di ogni richiesta e risposta del modello: il prompt, la completion, il conteggio dei token, la latenza, il costo e il trace che collega tutto a una sessione utente. Non è logging infrastrutturale. CPU, memoria e riavvii dei pod appartengono al tuo stack di metriche; questo articolo copre solo il record a livello di richiesta che ti permette di fare debug, analizzare i costi e verificare il comportamento del modello.

L'istinto del "registrare tutto" è duro a morire, e costa caro. Prompt e completion completi per 1 milione di richieste al giorno producono circa 60GB di testo al mese, e una parte di quel testo è PII dei clienti che ora stai archiviando a tempo indeterminato. Il principio di minimizzazione dei dati dell'articolo 5 del GDPR richiede che i dati personali siano "adeguati, pertinenti e limitati a quanto necessario", e un dump grezzo dei prompt fallisce questo test dal primo giorno. Registrare tutto non è una strategia; è una passività con una fattura mensile.

Quali sono le 9 regole di logging LLM?

Nove regole, nell'ordine in cui le implementeremmo: registrare prompt e risposte completi con identificatori con hash, emettere JSON strutturato, catturare token e costo per richiesta, allegare il contesto di trace di OpenTelemetry, oscurare i PII prima della scrittura, campionare ad alti volumi, impostare livelli di retention, separare gli eventi di sicurezza e rendere interrogabile il risultato. Ognuna di quelle qui sotto è accompagnata dal codice o dalla tabella che la fa rispettare.

Regola 1: registra prompt e risposta completi (con hash, non PII grezzi)

Registra il prompt completo e la completion completa per ogni richiesta, perché i log parziali sono il modo in cui finisci a fissare un incidente senza alcuna traccia di ciò che il modello ha effettivamente visto. L'unica eccezione è l'identità: non scrivere mai ID utente, email o nomi grezzi nel record. Memorizza invece un hash SHA-256 dell'ID utente. Un hash ti permette comunque di ricostruire l'intera cronologia di sessione di un utente con una lookup offline, mentre la riga di log resta inutile per chiunque non debba leggerla. Stessa logica per i system prompt: fanne l'hash, registra l'hash e conserva il testo in chiaro nel tuo registro dei prompt, dove è già versionato.

Regola 2: usa JSON strutturato: ogni campo nominato, niente testo libero

Per le migliori pratiche di logging LLM in Python o in qualsiasi altro linguaggio, il logging strutturato in JSON è il punto non negoziabile: ogni campo nominato, tipizzato e interrogabile, niente scaricato come stringa formattata. Una riga di testo libero come INFO called gpt-4o, took 812ms può solo essere cercata con grep. Un record JSON può essere aggregato per modello, sommato per costo e collegato a un trace. Le best practice di produzione di OpenAI spingono nella stessa direzione: catturare metadati strutturati a livello SDK invece che con istruzioni print.

Ecco lo schema che ogni servizio Techsy emette, quattordici campi:

{
  "request_id": "req_01J9XK4M7Q",
  "timestamp": "2026-07-18T09:24:31.482Z",
  "environment": "production",
  "model": "claude-sonnet-4-20250514",
  "prompt_tokens": 1284,
  "completion_tokens": 396,
  "latency_ms": 812,
  "cost_usd": 0.0098,
  "system_prompt_hash": "sha256:9f2c1a4e...",
  "user_id_hash": "sha256:b7e4d831...",
  "rag_sources": ["kb/pricing-2026.md", "kb/refund-policy.md"],
  "guardrail_result": "pass",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7"
}

Tre campi meritano una nota. cost_usd è calcolato al momento della richiesta dal conteggio dei token e dalla tariffa pubblicata del modello, mai ricalcolato da un job notturno. I due campi hash sono il compromesso della Regola 1: correlabili offline, opachi nel log. E trace_id e span_id sono valori del trace-context W3C, che è esattamente l'argomento della Regola 4.

Se quattro servizi che chiamano direttamente i provider ti sembrano quattro punti da strumentare, un proxy LiteLLM centralizza tutto: un unico hook di logging davanti a ogni provider.

Regola 3: cattura conteggio dei token e costo per richiesta

Il monitoraggio dell'uso dei token appartiene alla riga di log stessa, non a un job di data warehouse che gira domani. Ogni provider restituisce il conteggio dei token di input e output nella risposta; moltiplica per la tariffa per token del modello in quell'esatto momento e scrivi cost_usd nel record. Le tariffe cambiano, e differiscono tra token di input in cache e nuovi, quindi calcolare il costo in seguito con una tabella di prezzi statica riscrive la storia in silenzio. Con il costo su ogni riga, "quale funzionalità costa di più?" diventa una query di una riga invece di un progetto finanziario, e alimenta direttamente il lavoro per ridurre la spesa API LLM.

Regola 4: allega il contesto di trace (Semconv GenAI di OpenTelemetry)

Una riga di log senza trace ID è orfana: puoi leggerla, ma non puoi dire quale retry, quale fase RAG o quale turno utente l'ha prodotta. La soluzione sono le convenzioni semantiche GenAI di OpenTelemetry, i nomi di attributo standard per strumentare le chiamate ai modelli. Emetti il log dentro uno span attivo e trace_id e span_id si allegano da soli, così un clic in Grafana ti porta dal waterfall del trace dritto al record grezzo.

Gli attributi che vale la pena impostare su ogni span gen_ai:

from opentelemetry import trace

tracer = trace.get_tracer("ai-sdr")

with tracer.start_as_current_span("chat.completion") as span:
    span.set_attribute("gen_ai.system", "anthropic")
    span.set_attribute("gen_ai.request.model", "claude-sonnet-4-20250514")
    response = client.messages.create(**payload)
    span.set_attribute("gen_ai.usage.input_tokens", response.usage.input_tokens)
    span.set_attribute("gen_ai.usage.output_tokens", response.usage.output_tokens)
    span.set_attribute("gen_ai.response.finish_reasons", [response.stop_reason])
    log.info("llm.request", cost_usd=cost)  # Rule 2 record, trace IDs auto-attached

Regola 5: oscura i PII prima della scrittura del log

L'oscuramento dei PII deve avvenire prima che il record venga scritto, non ripulito dopo. Una volta che un indirizzo email è in Loki, è anche nei backup del tuo object storage, e "l'abbiamo cancellato dopo" non è una risposta accettabile per il GDPR. Nel nostro setup, Microsoft Presidio gira come processor di structlog e intercetta il 94% di email e numeri di telefono prima che raggiungano Loki; i casi mancati sono quasi tutti formati insoliti, che trasformiamo in recognizer personalizzati man mano che li troviamo.

L'intero hook è quindici righe:

from presidio_analyzer import AnalyzerEngine
from presidio_anonymizer import AnonymizerEngine

analyzer = AnalyzerEngine()
anonymizer = AnonymizerEngine()

PII_ENTITIES = ["PERSON", "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IBAN_CODE"]

def redact_pii(text: str) -> str:
    results = analyzer.analyze(text=text, language="en", entities=PII_ENTITIES)
    return anonymizer.anonymize(text=text, analyzer_results=results).text

# In the structlog processor chain, before JSONRenderer:
# event_dict["prompt"] = redact_pii(event_dict["prompt"])

L'oscuramento sta nello stesso livello di pipeline dei filtri di input e output, e va testato allo stesso modo. La nostra pipeline di guardrail tratta un'email trapelata in un log come un eval fallito, non come una nota a piè di pagina operativa.

Regola 6: campiona in modo intelligente ad alti volumi

Sotto circa 100.000 richieste al giorno, registra tutto. Sopra quella soglia, il logging a volume pieno è una tassa di archiviazione su dati che non leggerai mai, e il campionamento è il modo per conservare i record che contano. Il trucco: il campionamento casuale è l'opzione peggiore per il traffico LLM, perché fallimenti, rifiuti e richieste da cinque dollari sono rari per definizione, quindi un tasso uniforme del 10% scarta esattamente gli eventi di cui fai il debug. Campiona per esito, non a sorte.

Un setup comune è a regole ai bordi (produzione e tenant enterprise: registra sempre) più a coda nel mezzo. L'angolazione specifica per i log di questo framework: i tuoi campi guardrail_result e cost_usd sono i segnali di campionamento, già presenti se hai seguito le Regole 2 e 8.

Regola 7: definisci una politica di retention prima che ti serva

Una politica di retention dei log è una decisione che prendi quando sei tranquillo, perché l'alternativa è prenderla durante una revisione dei costi a volumi raddoppiati. Il principio di limitazione della conservazione dell'articolo 5 del GDPR dice che i dati personali vanno conservati "non più a lungo del necessario", che in pratica significa retention a livelli:

Hot risponde veloce e a caro prezzo a "cosa è successo dieci minuti fa?"; cold risponde lentamente e a buon mercato a "cosa abbiamo detto a questo cliente a marzo?". Cancella secondo programma, automaticamente, o i livelli sono solo un diagramma.

Regola 8: registra separatamente gli eventi di guardrail e sicurezza

Gli eventi di sicurezza (blocchi del guardrail, rifiuti, violazioni di policy) non sono telemetria; sono record di audit, e appartengono a un loro flusso. Tre motivi. Alerting: un picco di prompt injection bloccate dovrebbe svegliare qualcuno, e non puoi regolare quell'alert su 1 milione di righe di routine. Retention: la compliance può richiedere che i record di sicurezza sopravvivano ai log di debug di anni. Accesso: gli auditor ricevono il flusso di sicurezza, non l'intero flusso di log. Etichetta il verdetto nel record principale (guardrail_result: "block") e instrada il record completo al flusso separato. Cosa conti come evento di sicurezza è coperto nella nostra guida agli eventi di guardrail.

Regola 9: rendi i log interrogabili, non solo archiviati

Un log che non riesci a interrogare in meno di un minuto è un backup, non un segnale di osservabilità. Interrogabile significa campi indicizzati, un linguaggio di query che chi è di reperibilità conosce davvero e dashboard costruite prima dell'incidente. Noi usiamo Loki e lo interroghiamo più di 30 volte a settimana per anomalie di costo, regressioni di latenza e "mostrami ogni rifiuto per il tenant X di ieri". La documentazione di Grafana Loki è il riferimento per la sintassi; il pattern che ripaga è filtrare direttamente sui campi JSON parsificati:

{service="ai-sdr"} |= "llm.request" | json
  | model = "claude-sonnet-4-20250514"
  | cost_usd > 0.05
  | line_format "{{.timestamp}} {{.request_id}} ${{.cost_usd}} {{.latency_ms}}ms"

Cinque righe, nessuna esportazione in un notebook. Se il tuo store attuale non può farlo, è il problema da risolvere per primo.

Cosa registriamo davvero in produzione

Basta teoria. Ecco la configurazione anonimizzata della nostra pipeline AI SDR, il servizio dietro il numero di 1,2 milioni di richieste al mese nell'introduzione. Gira con structlog 25.4.0 che renderizza JSON, spedito a Grafana Cloud Loki via Promtail. Il modello su questa pipeline è claude-sonnet-4-20250514, e ogni chiamata attraversa esattamente la catena di processor delle Regole 2 e 5:

import structlog

structlog.configure(
    processors=[
        structlog.contextvars.merge_contextvars,
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        redact_pii,          # Rule 5: Presidio, before serialization
        add_otel_trace_ids,  # Rule 4: trace_id + span_id from the active span
        structlog.processors.JSONRenderer(),
    ],
)
log = structlog.get_logger()

Due numeri dal primo trimestre con questo setup. L'ingest mensile si è stabilizzato a 47GB su quattro servizi, e la latenza p95 di scrittura del log è 3ms, cioè la pipeline non aggiunge nulla di misurabile al tempo di richiesta.

Il cambio di configurazione che si è ripagato da solo: abbiamo aggiunto cost_usd a ogni voce di log a marzo 2026. Entro una settimana abbiamo trovato un template di prompt che bruciava $340 al mese in cicli di retry. Un errore API transitorio scatenava tre retry, ognuno dei quali reinviava l'intero contesto da 4.000 token. I log l'hanno resa una query di una riga; senza il costo per richiesta, sarebbe emersa come una voce inspiegata nella prossima revisione di budget trimestrale.

Quanto costa archiviare i log LLM su larga scala?

Per 1 milione di richieste al giorno, l'archiviazione dei log LLM costa tra circa $1,20 e $108 al mese per gli stessi dati, a seconda dello store. Il calcolo: un record strutturato completo è in media circa 2KB, quindi 1 milione di richieste al giorno sono 2GB al giorno, ovvero 60GB al mese. I prezzi pubblicati dai vendor qui sotto (luglio 2026) sono quanto costano quei 60GB in tre backend comuni.

Fonti: prezzi Datadog, Grafana Loki e la documentazione observability di ClickHouse.

Due avvertenze, perché questo è un nostro calcolo dalle tariffe dei vendor, non un benchmark che abbiamo eseguito. Primo, il numero di Datadog assume che tu indicizzi tutto; molti team indicizzano un sottoinsieme e pagano molto meno, mentre Loki e ClickHouse fanno pagare soprattutto ciò che archivi. Secondo, il $1,20 di ClickHouse self-hosted nasconde un conto reale: il compute per far girare il cluster e le ore di ingegneria per gestirlo. A 60GB al mese, un servizio gestito è quasi sempre la risposta complessivamente più economica. Il self-hosting inizia ad avere senso oltre circa 1TB al mese, dove il divario per GB supera l'overhead operativo.

Il divario è il punto. Per 1 milione di richieste al giorno, la distanza tra Datadog indicizzato e ClickHouse self-hosted è circa 90x: $108 contro $1,20 per gli stessi 60GB. Scegli lo store al momento dell'architettura, non dopo che arriva la fattura.

Quale strumento di logging scegliere?

Per molti team la scelta si riduce a quattro opzioni: una piattaforma nativa LLM (Langfuse o LangSmith), uno strumento a livello proxy (Helicone), o una semplice pipeline OpenTelemetry nell'infrastruttura che già gestisci. La tabella copre i punti decisionali che differiscono davvero; dashboard, replay e versioning dei prompt sono requisiti minimi in tutte e quattro.

La nostra opinione, senza giri di parole: usiamo nativo OTel più Loki perché avevamo già lo stack Grafana per tutto il resto, e aggiungere un'altra sorgente dati ha battuto l'adottare un quarto vendor. Se parti da zero senza alcuno stack di osservabilità, il modello di tracing di Langfuse e il suo piano gratuito sono la strada più rapida verso risultati concreti, e l'opzione self-host tiene aperta la porta di uscita. Se stai scegliendo tra i due leader nativi LLM, il nostro confronto Langfuse vs LangSmith fa la comparazione completa. E se il logging è un pezzo di una decisione di monitoraggio più ampia, il confronto completo delle piattaforme copre il campo più ampio.

Quali sono gli errori più comuni nel logging LLM?

Sei errori spiegano la maggior parte dei setup di logging LLM rotti che abbiamo visto. Ognuno costa poco da evitare se lo intercetti prima che il volume dei log lo faccia per te:

• Registrare PII grezzi senza oscuramento. Il più comune e il più costoso. Un export di supporto o un bucket violato trasformano i log dei prompt in un incidente di protezione dei dati. Oscura prima della scrittura (Regola 5), non in lettura.
• Nessuna politica di retention. L'archiviazione illimitata è il default ovunque, e raddoppia silenziosamente la tua fattura ogni anno. Se non cancelli mai, non hai un sistema di logging; hai un archivio con manie di grandezza.
• Log di testo non strutturato. L'output di print che puoi solo cercare con grep funziona alla scala di una demo e crolla a 100.000 richieste al giorno, quando "trova ogni richiesta fallita per il modello X" diventa un pomeriggio di script shell invece di una query.
• Registrare solo gli errori. Le richieste riuscite sono la baseline rispetto a cui rilevi il drift, e sono la materia prima della tua pipeline di valutazione. Registra anche i successi, campionati se il volume lo impone.
• Ignorare i campi di costo. Niente cost_usd per richiesta significa niente alert di costo, nessuna attribuzione per funzionalità, e il ciclo di retry da $340 al mese della sezione produzione qui sopra resta invisibile fino alla fattura trimestrale.
• Nessuna correlazione dei trace. Log scollegati dagli span rendono il debug di agenti multi-fase un esercizio di congetture. Se alla tua riga di log manca un trace_id, la Regola 4 è la soluzione.

Domande frequenti

Cosa dovresti registrare per ogni richiesta LLM?

Come minimo: prompt e completion completi con i PII oscurati, il nome del modello, il conteggio dei token di input e output, la latenza, il costo in USD, un identificatore utente con hash e gli ID di trace e span di OpenTelemetry. Aggiungi gli ID delle sorgenti RAG e il verdetto del guardrail se la tua pipeline ha quelle fasi. Quattordici campi nominati, una riga JSON per richiesta.

Qual è il formato migliore per i log LLM?

JSON strutturato, un oggetto per richiesta, con ogni campo esplicitamente nominato. I log di testo libero possono solo essere cercati con grep; i record JSON possono essere aggregati per modello, sommati per costo e collegati ai trace. Emetti il record con un logger strutturato come structlog in Python o pino in Node, e renderizzalo con un serializzatore JSON, mai con la formattazione di stringhe.

Come gestisci i PII nei log LLM?

Oscura prima della scrittura del log, non dopo. Fai passare prompt e completion attraverso un detector come Microsoft Presidio dentro la tua pipeline di logging, sostituendo nomi, email e numeri di telefono con token come <EMAIL_ADDRESS>. Una volta che PII grezzi raggiungono il tuo log store, sono anche nei tuoi backup, e la cancellazione retroattiva raramente soddisfa il test di minimizzazione del GDPR.

Quanto costa archiviare i log LLM su larga scala?

Per 1 milione di richieste al giorno, circa 60GB al mese a 2KB per record, aspettati circa $108 al mese con i prezzi indicizzati di Datadog LLM Observability, $30 al mese su Grafana Cloud Loki, o circa $1,20 al mese in archiviazione S3 compressa per ClickHouse self-hosted più il compute. Queste sono le tariffe pubblicate dai vendor a luglio 2026; il self-hosting aggiunge tempo di ingegneria.

Cosa sono le convenzioni semantiche GenAI di OpenTelemetry?

Sono i nomi di attributo standard di OpenTelemetry per strumentare le chiamate LLM: gen_ai.system per il provider, gen_ai.request.model per il modello, gen_ai.usage.input_tokens e output_tokens per il conteggio dei token, e gen_ai.response.finish_reasons per il motivo per cui la generazione si è fermata. Usarle significa che qualsiasi backend compatibile OTel, da Jaeger a Tempo a Langfuse, legge i tuoi trace senza parser personalizzati.

Come campioni i log LLM ad alto traffico?

Tieni ogni errore, ogni blocco del guardrail e ogni richiesta sopra una soglia di costo, poi campiona il resto. Questo approccio a coda preserva gli eventi rari di cui fai davvero il debug, mentre il campionamento casuale uniforme li scarta alla stessa frequenza del traffico noioso. Sotto 100.000 richieste al giorno, salta del tutto il campionamento e registra tutto.

Per quanto tempo dovresti conservare i log LLM?

A livelli: 7 giorni in hot per il debug in tempo reale, 30 giorni in warm per la revisione degli incidenti e l'analisi dei costi, e fino a 1 anno in cold in object storage compresso per compliance e audit. Il principio di limitazione della conservazione del GDPR vieta di conservare i dati personali più a lungo del necessario, quindi abbina a ogni livello una cancellazione automatica invece di una pulizia manuale.

Qual è la differenza tra logging LLM e tracing LLM?

Un log è un record piatto di un singolo evento: questa richiesta è successa, con questi campi. Un trace è un albero causale di span attraverso un intero percorso di richiesta, ad esempio retrieval, poi la chiamata al modello, poi due chiamate a tool. I log ti dicono cosa; i trace ti dicono dove e perché. I setup di produzione li emettono entrambi, uniti da trace_id.

Conclusione

Riepilogo: registra ogni richiesta come JSON con campi nominati, calcola il costo al momento della richiesta, allega il contesto di trace OTel, oscura i PII prima della scrittura, campiona per esito una volta superate 100.000 richieste al giorno e scegli uno store che sai davvero interrogare. Le nove regole sono ordinate così che tu possa adottarne una per sprint, e le Regole 2, 4 e 5 sono le tre che ripagano più in fretta. Se stai scegliendo lo stack di monitoraggio più ampio attorno ai log, parti dalla nostra rassegna delle migliori piattaforme di osservabilità AI. E se ti serve aiuto per integrare il logging strutturato nel tuo stack LLM, richiedi una consulenza gratuita.