Logging strutturato con JSONL
Una guida completa al logging strutturato in formato JSONL (JSON Lines). Scopri come integrarlo con ELK Stack, Fluentd, CloudWatch, GCP Logging e Azure Monitor, con esempi di codice pronti per la produzione.
Perché usare JSONL per il logging strutturato?
I log tradizionali in testo semplice sono facili da leggere, ma per un software è quasi impossibile interpretarli in modo affidabile. In una riga come '2024-01-15 ERROR User login failed for admin', il livello di gravità, il tipo di evento e il nome utente sono tutti racchiusi in una stringa non strutturata. Per estrarre queste informazioni, ogni strumento di aggregazione dei log deve ricorrere a espressioni regolari fragili: basta una modifica al formato dei log per interrompere la pipeline.
Il logging strutturato risolve il problema generando ogni voce di log come oggetto JSON con campi ben definiti. JSONL (JSON Lines) semplifica ulteriormente il formato: un oggetto JSON per riga, senza un array che racchiuda gli oggetti e senza virgole finali. Ai log JSONL è quindi facile aggiungere nuove voci in coda; inoltre, si possono elaborare in streaming e analizzare con facilità su tutte le principali piattaforme di gestione dei log. In questa guida imparerai a generare log JSONL con Python, Node.js e Go e a inviarli a ELK, Fluentd e ai tre principali provider cloud.
Rispetto ad altri formati strutturati, come CSV o XML, JSONL offre il miglior equilibrio tra flessibilità, supporto da parte degli strumenti e leggibilità. I campi possono essere annidati, i tipi di dato vengono mantenuti e non serve definire uno schema fisso in anticipo. Per questo JSONL è diventato lo standard de facto per il logging strutturato nelle infrastrutture moderne.
Librerie di logging per linguaggio
La maggior parte delle librerie di logging moderne supporta l'output JSON strutturato in modo nativo o con una semplice modifica alla configurazione. Ecco le librerie consigliate per Python, Node.js e Go: tutte producono un output compatibile con JSONL.
Python: structlog
Consigliatastructlog è la libreria di riferimento per il logging strutturato in Python. Si appoggia al modulo logging della libreria standard e genera output JSON per impostazione predefinita. La sua pipeline di processori ti permette di arricchire, filtrare e trasformare le voci di log prima della serializzazione.
import structlog
# Configure structlog for JSONL output
structlog.configure(
processors=[
structlog.processors.TimeStamper(fmt="iso"),
structlog.processors.add_log_level,
structlog.processors.StackInfoRenderer(),
structlog.processors.JSONRenderer(),
],
wrapper_class=structlog.BoundLogger,
context_class=dict,
logger_factory=structlog.PrintLoggerFactory(),
)
log = structlog.get_logger()
# Each call produces one JSONL line
log.info("user.login", user_id="u-42", ip="10.0.0.1")
# {"event":"user.login","user_id":"u-42","ip":"10.0.0.1","level":"info","timestamp":"2026-02-15T08:30:00Z"}
log.error("db.connection_failed", host="db-primary", retries=3)
# {"event":"db.connection_failed","host":"db-primary","retries":3,"level":"error","timestamp":"2026-02-15T08:30:01Z"}Node.js: pino
Il più velocepino è il logger più veloce per Node.js e genera output JSONL per impostazione predefinita, senza richiedere alcuna configurazione. Mantiene basso l'overhead grazie alla scrittura asincrona e a un processo di serializzazione ridotto al minimo. Il pacchetto complementare pino-pretty rende l'output più leggibile durante lo sviluppo in locale.
import pino from 'pino';
// pino outputs JSONL by default
const log = pino({
level: 'info',
timestamp: pino.stdTimeFunctions.isoTime,
});
// Each call produces one JSONL line
log.info({ userId: 'u-42', ip: '10.0.0.1' }, 'user.login');
// {"level":30,"time":"2026-02-15T08:30:00.000Z","userId":"u-42","ip":"10.0.0.1","msg":"user.login"}
log.error({ host: 'db-primary', retries: 3 }, 'db.connection_failed');
// {"level":50,"time":"2026-02-15T08:30:01.000Z","host":"db-primary","retries":3,"msg":"db.connection_failed"}
// Child loggers inherit context
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');Go: zerolog
Zero allocazionizerolog è un logger JSON per Go che non effettua allocazioni, progettato per offrire le massime prestazioni nei servizi ad alto throughput. Scrive direttamente su un io.Writer senza allocazioni intermedie, una caratteristica ideale per le applicazioni sensibili alla latenza. La sua API con chiamate concatenate è comoda da usare ed efficiente.
package main
import (
"os"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// Configure JSONL output to stdout
zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()
// Each call produces one JSONL line
log.Info().
Str("user_id", "u-42").
Str("ip", "10.0.0.1").
Msg("user.login")
// {"level":"info","user_id":"u-42","ip":"10.0.0.1","time":1739608200,"message":"user.login"}
log.Error().
Str("host", "db-primary").
Int("retries", 3).
Msg("db.connection_failed")
}Integrazione con ELK Stack
ELK Stack (Elasticsearch, Logstash, Kibana) è la piattaforma open source per la gestione dei log più diffusa. I log JSONL si integrano senza difficoltà: Logstash e Filebeat supportano nativamente il parsing JSON, quindi non servono pattern grok complessi.
Filebeat è uno strumento leggero che legge le nuove righe aggiunte ai tuoi file di log JSONL e le inoltra a Logstash o Elasticsearch. Impostando json.keys_under_root a true, i campi JSON diventano campi di primo livello in Elasticsearch, su cui puoi eseguire ricerche direttamente in Kibana.
# filebeat.yml
filebeat.inputs:
- type: log
enabled: true
paths:
- /var/log/app/*.jsonl
json.keys_under_root: true
json.add_error_key: true
json.message_key: message
json.overwrite_keys: true
output.elasticsearch:
hosts: ["http://elasticsearch:9200"]
index: "app-logs-%{+yyyy.MM.dd}"
# Optional: send to Logstash instead
# output.logstash:
# hosts: ["logstash:5044"]Se devi trasformare o arricchire i log prima di indicizzarli, inserisci Logstash tra Filebeat ed Elasticsearch. Il codec json analizza automaticamente ogni riga JSONL. Usa il filtro mutate per rinominare i campi, aggiungere tag o rimuovere dati sensibili prima di archiviare i log.
# logstash.conf
input {
beats {
port => 5044
codec => json
}
}
filter {
# Parse timestamp from the JSON field
date {
match => ["timestamp", "ISO8601"]
target => "@timestamp"
}
# Add environment tag
mutate {
add_field => { "environment" => "production" }
remove_field => ["agent", "ecs", "host"]
}
# Route by log level
if [level] == "error" or [level] == "fatal" {
mutate { add_tag => ["alert"] }
}
}
output {
elasticsearch {
hosts => ["http://elasticsearch:9200"]
index => "app-logs-%{+YYYY.MM.dd}"
}
}Fluentd e Fluent Bit
Fluentd e Fluent Bit, la sua alternativa più leggera, sono progetti che hanno raggiunto lo stato graduated nella CNCF e sono molto diffusi negli ambienti Kubernetes. Entrambi gestiscono i log JSONL in modo nativo e possono inoltrarli praticamente a qualsiasi destinazione: Elasticsearch, S3 o servizi di logging cloud nativi.
Fluent Bit è lo strumento di raccolta dei log da preferire per Kubernetes e per gli ambienti con risorse limitate. Usa circa 450KB di memoria e può elaborare centinaia di migliaia di record al secondo. Il parser json gestisce l'input JSONL senza bisogno di configurazioni personalizzate.
[SERVICE]
Flush 5
Daemon Off
Log_Level info
Parsers_File parsers.conf
[INPUT]
Name tail
Path /var/log/app/*.jsonl
Parser json
Tag app.*
Refresh_Interval 5
[FILTER]
Name modify
Match app.*
Add cluster production-us-east-1
Add service my-api
[OUTPUT]
Name es
Match app.*
Host elasticsearch
Port 9200
Index app-logs
Type _doc
Logstash_Format OnFluentd offre un ecosistema di plugin più ricco di quello di Fluent Bit, con oltre 500 plugin sviluppati dalla community. Usalo quando ti servono routing avanzato, buffering o trasformazioni. Il plugin in_tail con format json legge i file JSONL in modo nativo.
# fluentd.conf
<source>
@type tail
path /var/log/app/*.jsonl
pos_file /var/log/fluentd/app.pos
tag app.logs
<parse>
@type json
time_key timestamp
time_format %Y-%m-%dT%H:%M:%S%z
</parse>
</source>
<filter app.logs>
@type record_transformer
<record>
hostname "#{Socket.gethostname}"
environment production
</record>
</filter>
<match app.logs>
@type elasticsearch
host elasticsearch
port 9200
index_name app-logs
logstash_format true
<buffer>
@type memory
flush_interval 5s
chunk_limit_size 5m
</buffer>
</match>Piattaforme di logging cloud
Tutti e tre i principali provider cloud accettano log in formato JSONL e ne analizzano automaticamente i campi JSON, rendendoli attributi su cui puoi eseguire ricerche e applicare filtri. Puoi così mantenere le stesse funzionalità di query sui dati strutturati senza dover gestire una tua infrastruttura di logging.
AWS CloudWatch Logs
AWSCloudWatch Logs analizza automaticamente le voci di log JSON e ti permette di interrogare ogni campo con CloudWatch Logs Insights. Se la tua applicazione viene eseguita su ECS, Lambda o EC2 con l'agente CloudWatch, l'output JSONL viene indicizzato come dati strutturati senza configurazioni aggiuntive. Usa la sintassi di Logs Insights, simile a SQL, per eseguire query su milioni di voci di log in pochi secondi.
# CloudWatch Logs Insights query examples
# Find all errors in the last hour
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100
# Aggregate error counts by event type
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc
# P99 latency by endpoint
fields path, duration_ms
| filter ispresent(duration_ms)
| stats pct(duration_ms, 99) as p99 by path
| sort p99 descGCP Cloud Logging
GCPGoogle Cloud Logging (in precedenza Stackdriver) supporta nativamente i payload JSON come voci di log strutturate. Quando scrivi JSONL su stdout in Cloud Run, GKE o Cloud Functions, l'agente di logging analizza ogni riga e la converte in un oggetto LogEntry strutturato. Il campo severity corrisponde direttamente ai livelli di gravità di Cloud Logging, mentre i campi jsonPayload vengono indicizzati e diventano disponibili per le ricerche.
# Python example for Cloud Run / Cloud Functions
import json
import sys
def log(severity: str, message: str, **fields):
"""Write a JSONL log entry compatible with GCP Cloud Logging."""
entry = {
"severity": severity.upper(), # Maps to Cloud Logging severity
"message": message,
**fields,
}
print(json.dumps(entry), file=sys.stdout, flush=True)
# GCP automatically parses these as structured logs
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)
# Query in Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERRORAzure Monitor Logs
AzureAzure Monitor acquisisce i log JSONL tramite Azure Monitor Agent o direttamente via API. Application Insights analizza automaticamente le tracce JSON e gli eventi personalizzati. KQL (Kusto Query Language) permette di eseguire query avanzate sui dati di log strutturati, con supporto per aggregazioni, analisi delle serie temporali e rilevamento delle anomalie.
// KQL queries for JSONL logs in Azure Monitor
// Find recent errors
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| project TimeGenerated, parsed.event, parsed.user_id,
parsed.error_message
| order by TimeGenerated desc
| take 100
// Error rate over time (5-minute buckets)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart
// Top error events
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by CountBest practice per il logging JSONL
Adottare convenzioni uniformi in tutti i tuoi servizi facilita le query sui log JSONL, la correlazione delle voci e la configurazione degli alert. Queste best practice provengono da sistemi in produzione che elaborano miliardi di voci di log al giorno.
Usa livelli di log coerenti
Adotta una scala di gravità standard e usala in modo coerente in tutti i servizi. La convenzione più comune prevede cinque livelli: DEBUG per la diagnostica durante lo sviluppo, INFO per le normali operazioni, WARN per i problemi recuperabili, ERROR per gli errori che richiedono attenzione e FATAL per i crash irreversibili. Durante l'acquisizione, associa i livelli numerici (come la scala 10-60 di pino) a questi nomi testuali, così da poter eseguire query uniformi.
{"level":"debug","event":"cache.miss","key":"user:42","timestamp":"2026-02-15T08:30:00Z"}
{"level":"info","event":"request.completed","method":"GET","path":"/api/users","status":200,"duration_ms":45,"timestamp":"2026-02-15T08:30:01Z"}
{"level":"warn","event":"rate_limit.approaching","client_id":"c-99","current":950,"limit":1000,"timestamp":"2026-02-15T08:30:02Z"}
{"level":"error","event":"payment.failed","order_id":"ord-123","error":"card_declined","timestamp":"2026-02-15T08:30:03Z"}
{"level":"fatal","event":"startup.failed","reason":"missing DATABASE_URL","timestamp":"2026-02-15T08:30:04Z"}Uniforma i nomi dei campi
Definisci uno schema condiviso per i campi comuni a tutti i servizi. Usa snake_case per i nomi dei campi, ISO 8601 per i timestamp e una convenzione uniforme per i nomi degli identificatori di correlazione. Ogni voce di log dovrebbe contenere almeno timestamp, level, event (un nome di evento interpretabile dal software) e service. Le voci relative a una specifica richiesta dovrebbero includere request_id e user_id per il tracing.
// Recommended field schema
{
"timestamp": "2026-02-15T08:30:00.000Z", // ISO 8601, always UTC
"level": "info", // debug|info|warn|error|fatal
"event": "order.created", // dot-notation event name
"service": "order-api", // emitting service
"version": "1.4.2", // service version
"request_id": "req-abc-123", // correlation ID
"trace_id": "4bf92f3577b34da6", // distributed trace ID
"user_id": "u-42", // authenticated user
"duration_ms": 120, // numeric, not string
"order_id": "ord-789", // domain-specific context
"items_count": 3 // domain-specific context
}Considerazioni sulle prestazioni
Il logging strutturato comporta un costo di serializzazione a ogni chiamata al logger. Nei servizi ad alto throughput, questo overhead può diventare significativo. Usa il logging asincrono (pino, zerolog) per spostare la serializzazione fuori dal percorso critico di esecuzione. Evita di registrare oggetti di grandi dimensioni o body di richieste e risposte al livello INFO. Per i log di debug generati in grandi volumi, usa il campionamento. Scrivi i log su file locali e affidane l'invio a un sidecar (Filebeat, Fluent Bit), anziché inviarli in rete in modo sincrono.
Usa logger asincroni (pino, zerolog) per non bloccare il thread principale durante la serializzazione JSON.
Non registrare mai nei log i body completi delle richieste o delle risposte al livello INFO. Usa il livello DEBUG e attivalo solo quando devi diagnosticare un problema.
Campiona gli eventi che si verificano più di frequente. Registra nei log 1 richiesta di health-check ogni 100, anziché tutte.
Scrivi i log su file locali e inviali in modo asincrono con Filebeat o Fluent Bit. Evita chiamate di rete sincrone durante l'elaborazione dei log.
Imposta una dimensione massima per le righe di log (ad esempio 16KB), per evitare che voci troppo grandi intasino la pipeline.
Configura la rotazione dei file di log con logrotate o con la funzione integrata nella libreria, per evitare di esaurire lo spazio su disco.
Valida i tuoi log JSONL online
Usa i nostri strumenti gratuiti nel browser per esaminare, validare e convertire i file di log JSONL. Non devi caricare nulla su un server: tutta l'elaborazione avviene in locale.
Impara a elaborare dati JSONL in streaming in tempo reale con Node.js, Python, Server-Sent Events e WebSocket. Crea pipeline di streaming per log, metriche e flussi di dati in tempo reale.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Formatta i file JSONL con un’indentazione corretta per renderli più leggibili e facilitare il debug e la revisione dei dati.
Apri i file .jsonl e .ndjson direttamente nel tuo editor, in una tabella veloce da consultare e in cui puoi effettuare ricerche. Pensata per file troppo grandi da scorrere e per log ancora in fase di scrittura.