Il tuo backend va in crash alle 3 di notte. Apri i log e trovi una stringa di testo lunga tre righe, con date in formato americano, messaggi troncati e nessuna traccia dell'ID utente che ha causato il problema. Ti serve un'ora per capire cosa è successo. Con i log strutturati JSON, quel problema lo risolvi in cinque minuti.
Noi, di Meteora Web, gestiamo decine di applicazioni in produzione da quasi un decennio. Abbiamo visto log di ogni tipo: da quelli testuali scritti male a quelli JSON fatti peggio. In questa guida ti mostriamo come fare logging strutturato JSON nel modo giusto, con esempi pronti da copiare e best practice che funzionano davvero.
Perché i log testuali non bastano più per le applicazioni moderne?
Un log testuale è come un messaggio scritto su un foglietto: utile se lo leggi subito, inutile se devi cercarlo tra mille altri. Le applicazioni moderne generano migliaia di log al minuto. Cercare un errore in un file di testo è come cercare un ago in un pagliaio, ma con gli occhi bendati.
I log strutturati JSON risolvono il problema alla radice: ogni log è un oggetto con campi definiti. Il messaggio è separato dal contesto. Il timestamp ha un formato standard. L'ID utente, l'IP, il tempo di risposta: tutto è un campo queryable. Puoi filtrare, aggregare e correlare in millisecondi, non in ore.
Il passaggio non è solo tecnico, è economico. Ogni minuto che il tuo team passa a decifrare log illeggibili è un minuto sottratto allo sviluppo di funzionalità che portano fatturato. Noi lo vediamo ogni giorno nei progetti che ci arrivano: i clienti che passano ai log strutturati riducono i tempi di debug del 60-70%. Non è un'opinione, è un dato che raccogliamo dai progetti reali.
Sponsored Protocol
Come passare da log testuali a log JSON senza riscrivere tutto
Se hai un'applicazione esistente, non devi buttare via nulla. La maggior parte dei framework moderni supporta il logging strutturato con poche righe di configurazione. In Node.js, ad esempio, puoi usare pino, in Python structlog, in PHP Monolog con il formatter JSON. La chiave è iniziare dai punti critici: errori, transazioni, chiamate API.
// Node.js con pino
const pino = require('pino');
const logger = pino({
level: process.env.LOG_LEVEL || 'info',
base: { service: 'api-gateway' },
timestamp: pino.stdTimeFunctions.isoTime
});
logger.info({ userId: 1234, action: 'login', ip: '192.168.1.1' }, 'User logged in');
Questo è un esempio minimo ma funzionante. Ogni log è un JSON con timestamp ISO, livello, messaggio e contesto. Lo puoi inviare a qualsiasi sistema di aggregazione: ELK, Grafana Loki, Datadog, qualsiasi cosa.
Quali campi deve avere un log strutturato JSON per essere utile?
Un log JSON senza campi standard è come un modulo compilato a metà. Per essere utile, deve avere una struttura minima che permetta di rispondere a tre domande: cosa è successo, quando, e in che contesto.
I campi essenziali sono: timestamp in formato ISO 8601, level (debug, info, warn, error), message leggibile, service (nome del servizio o microservizio), traceId per correlare richieste distribuite, e poi campi contestuali come userId, requestId, statusCode, durationMs. Non serve esagerare: ogni campo che aggiungi è un costo di storage, ma ogni campo mancante è un costo di debugging.
Sponsored Protocol
Noi abbiamo visto log JSON con 50 campi inutili e log con solo il messaggio. La verità sta nel mezzo: 10-15 campi ben scelti coprono il 90% dei casi d'uso. Il resto va aggiunto solo se serve.
Come strutturare il messaggio e il contesto nei log JSON
Il messaggio deve essere breve e descrittivo, come un titolo di un articolo. Il contesto va nei campi separati. Esempio corretto: "message": "Payment processed", "amount": 99.90, "currency": "EUR", "paymentMethod": "card". Esempio sbagliato: "message": "Payment of 99.90 EUR processed via card" — il messaggio diventa una stringa non queryable.
Un altro errore comune è loggare dati sensibili. Password, token, numeri di carta di credito: mai nei log. Noi abbiamo visto aziende che loggavano password in chiaro per "debugging". È un disastro di sicurezza. Se devi loggare un identificativo, usa un hash o un ID opaco.
Come gestire gli errori nei log JSON senza perdere lo stack trace?
Gli errori sono il caso d'uso più importante dei log. Un errore senza stack trace è come un incidente senza rapporto della polizia: sai che è successo, ma non sai perché. Con JSON, puoi includere lo stack trace come campo strutturato, senza mescolarlo al messaggio.
Sponsored Protocol
# Python con structlog
import structlog, logging, traceback
logger = structlog.get_logger()
try:
risky_operation()
except Exception as e:
logger.error("Operation failed", exc_info=True, user_id=user.id)
Con exc_info=True, structlog include automaticamente lo stack trace nel campo exception del JSON. Puoi cercare per tipo di errore, per modulo, per riga. È un livello di diagnostica che i log testuali non ti daranno mai.
Noi, di Meteora Web, abbiamo risolto un incidente in produzione su un server in cui si era rotto il rinnovo automatico dei certificati SSL. Con i log strutturati JSON, abbiamo trovato l'errore in 10 minuti: il campo error conteneva il codice esatto e il service indicava il modulo interessato. Senza JSON, sarebbe stata un'ora di grep e tail.
Quali strumenti usare per aggregare e visualizzare i log JSON?
Un log JSON senza un sistema di aggregazione è come un database senza query: puoi leggerlo, ma non puoi interrogarlo. Gli strumenti più comuni sono ELK Stack (Elasticsearch, Logstash, Kibana), Grafana Loki, e servizi cloud come Datadog o AWS CloudWatch. La scelta dipende dal budget e dall'infrastruttura.
Per una PMI, Grafana Loki è spesso la scelta migliore: open source, leggero, si integra con Prometheus e Grafana. Se già usi Grafana per le metriche, Loki è il complemento naturale per i log. L'integrazione è immediata: invii i log JSON a Loki e li visualizzi in Grafana con query tipo {service="api-gateway"} |= "error".
Sponsored Protocol
Il costo di storage è un fattore da considerare. I log JSON sono più pesanti dei testuali, ma la compressione di Loki e la retention policy ti permettono di tenere sotto controllo i costi. Noi consigliamo sempre di impostare una retention di 30 giorni per i log di debug e 1 anno per gli errori, se serve per audit.
Come inviare log JSON a un aggregatore con un semplice script
Se non vuoi integrare un SDK, puoi inviare i log JSON via HTTP a un endpoint. Ecco un esempio con curl:
curl -X POST http://loki:3100/loki/api/v1/push \
-H "Content-Type: application/json" \
-d '{"streams": [{"stream": {"service": "api-gateway"}, "values": [["'$(date +%s%N)'", "{\"level\":\"error\",\"message\":\"Connection refused\",\"port\":5432}"]]}]}'
Questo script invia un log JSON a Loki. Puoi adattarlo per qualsiasi aggregatore. La cosa importante è che il payload sia JSON e che i campi siano coerenti tra loro.
Quali errori comuni evitare quando si implementano log JSON?
Il primo errore è non loggare nulla o loggare troppo. Il secondo è loggare dati sensibili. Il terzo è non avere un formato standard tra servizi diversi. Il quarto è non impostare una rotazione dei log, causando dischi pieni. Il quinto è ignorare il contesto: un log senza traceId in un sistema a microservizi è inutile per il debugging distribuito.
Noi abbiamo visto tutti questi errori nei progetti che ci arrivano. Un cliente aveva un e-commerce con log testuali enormi, senza rotazione. Il server si riempiva ogni settimana. Abbiamo implementato JSON logging con pino e Loki, impostato una retention di 30 giorni, e il problema è sparito. Il costo? Un giorno di lavoro. Il beneficio? Zero downtime e debugging 10 volte più veloce.
Sponsored Protocol
Un altro errore è non testare i log in staging. I log JSON funzionano diversamente in produzione, con volumi reali. Simula un carico di test e verifica che i log siano completi e queryable. Noi lo facciamo sempre prima di andare in produzione.
Cosa fare adesso
Ecco le azioni concrete per implementare i log strutturati JSON nella tua applicazione:
- Identifica i punti critici: errori, autenticazione, pagamenti, chiamate API. Inizia da lì.
- Scegli una libreria: pino per Node.js, structlog per Python, Monolog per PHP. Configura il formatter JSON.
- Definisci i campi comuni: timestamp ISO, level, service, message, traceId, userId. Usali ovunque.
- Imposta un aggregatore: Grafana Loki se vuoi open source, Datadog se hai budget. Inviami i log JSON.
- Testa in staging: simula un carico di test e verifica che i log siano completi e queryable.
I log strutturati JSON non sono una moda: sono il minimo sindacale per chi gestisce applicazioni in produzione. Se non li hai ancora implementati, stai pagando in ore di debugging ciò che potevi risolvere in minuti. Noi, di Meteora Web, li usiamo in tutti i progetti che seguiamo, dal dominio al fatturato. Se vuoi vedere come funzionano in pratica, dai un'occhiata alla nostra guida sul monitoring e observability.
