Di Jerry Fan

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

Consigliata

structlog è 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.

Python: structlog
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ù veloce

pino è 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.

Node.js: pino
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 allocazioni

zerolog è 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.

Go: zerolog
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.

Configurazione di Filebeat
# 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.

Pipeline di Logstash
# 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.

Configurazione di Fluent Bit
[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 On

Fluentd 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.

Configurazione di Fluentd
# 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

AWS

CloudWatch 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.

AWS CloudWatch Logs
# 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 desc

GCP Cloud Logging

GCP

Google 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.

GCP Cloud Logging
# 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 >= ERROR

Azure Monitor Logs

Azure

Azure 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.

Azure Monitor Logs
// 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 Count

Best 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.

Usa livelli di log coerenti
{"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.

Uniforma i nomi dei campi
// 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.

Esamina i log JSONL nel browser

Visualizza file di log JSONL fino a 1GB, esegui ricerche al loro interno e validali. Caricamento istantaneo, elaborazione lato client e privacy al 100%.

Domande frequenti

Riferimenti